# MCP 服务器

MCP（Model Context Protocol）让 AI 接入外部工具——查数据库、搜网页、控制浏览器之类。连上之后这些工具会自动出现在 AI 的工具列表里，像内置工具一样调用。

入口在「设置 → MCP 服务器」。

## 两级作用域

MCP 配置分全局和项目两级：

- **全局**：所有项目共享，配置存在 `~/.muse/mcp.json`。
- **项目级**：只在当前工作区生效，配置存在 `<工作区>/.muse/mcp.json`，可以随项目一起提交到 git。

实际生效的是两者合并的结果，**项目级优先**——同名的服务器，项目里的配置会覆盖全局的。

## 服务器列表

每行显示服务器名称、来源（全局 / 项目）、类型（内置 / HTTP）、连接状态，已连接时还会显示工具数量，本地 stdio 服务未连接时显示启动命令；要求 OAuth 授权且尚未登录时会显示「需要登录」。

- 点行进入编辑。
- 左滑露出删除按钮，删除作用于该行标注的作用域。
- 右上角「重新连接」一键重连所有服务器，「+」添加新服务器。
- 当服务器数量较多时，可在顶部搜索栏按名称、地址或命令快速过滤。

### 批量操作

列表右上角的「多选」按钮（方框带勾的图标）可以一次处理多台服务器：

1. 点「多选」进入多选模式，每行左侧出现勾选框，整行点击即勾选。
2. 顶部操作条提供「启用 / 停用」、重连（环形箭头图标）与删除（垃圾桶图标），最右「×」或系统返回键退出多选。
3. 「全选」只勾中**当前搜索过滤后**的服务器；改了搜索词，被过滤掉的条目会自动取消勾选，不会误删看不见的条目。
4. 删除会弹确认框，确认后这些服务器从各自作用域的配置里移除并断开连接；启用 / 停用会立即重连生效，可以边看状态边继续调整。

多选模式下不能点击进入编辑页，也不能左滑删除单条。

如果你在容器内或用外部编辑器直接改了 `mcp.json`，App 会在几秒内自动发现并刷新：新增或启用的自动连接，删除或禁用的自动断开，不需要重启。

## 添加服务器

编辑页顶部先选**作用域**（新增时默认「项目」，编辑已有条目保持原作用域），下面的「是否启用」控制它是否参与连接。剩下的字段按传输类型分两种。

**名称**只作别名，但它会拼进给模型的工具名（`mcp__名称__工具名`），因此只能含字母、数字、下划线、连字符；填了中文之类的字符会提示错误且无法保存。

### 远程 HTTP

- **名称**：别名，例如 `fetch`、`github`。
- **服务器地址**：远程服务端的 Streamable HTTP 链接。
- **自定义请求头**：键值对，用来填认证 Token 这类固定头部。

### OAuth 登录

有些远程服务要求 OAuth 授权（连接时返回 401，列表里显示「需要登录」）。在编辑页打开「OAuth 认证」开关并保存，然后点「登录 / 重新授权」：

1. App 会打开系统浏览器，跳转到该服务的登录页。
2. 用你的账号完成授权，浏览器会提示「授权完成，可以返回 Muse」。
3. 回到 App，服务器会自动用新令牌重连，状态变为「已连接」。

- 大多数服务支持自动注册客户端，无需额外填写。若服务不支持（例如 GitHub 这类），可在「高级认证选项」的「client_id」中填入事先注册好的客户端 ID。
- 「授权服务器」一般留空，App 会自动发现；自动发现失败时可手动填写。
- 授权进行中时，若需要中止操作，可直接点击「取消授权」。
- 令牌过期后 App 会自动刷新；要换账号时点「退出登录」再重新授权。
- 授权令牌保存在 App 内部存储（`muse/mcp-oauth.json`），做了混淆处理但不属于加密存储，请勿在共享设备上用敏感账号授权。

### 本地 stdio

- **名称**：别名。
- **启动命令**：`npx`、`node`、`python` 之类。
- **命令参数**：逐项添加，例如 `-y`、`@modelcontextprotocol/server-xxx`。
- **环境变量**：传给该进程的键值对，例如 API_KEY。

stdio 服务器需要在容器里运行：本地模式下运行在当前容器上，远程 SSH 模式下运行在「默认容器」上。切换容器后所有 stdio 服务器会自动断开并用新容器重连，HTTP 服务器不受影响。

## 工具管理

连接成功后，编辑页的「工具」标签页会列出这个服务器提供的所有工具，每个工具一张卡片，显示描述和参数名。

- 顶部支持通过搜索栏按工具名或描述关键字实时筛选。
- 支持一键「全部启用」或「全部禁用」，方便快速批量管理。
- 右上角的开关可以**单独禁用某个工具**，禁用后它不再提供给模型，能省一些上下文。
- MCP 工具和内置工具走同一套权限机制：默认每次调用都要你确认，可以在授权弹窗里选「始终允许」记住。
- 没检测到工具时点右上角刷新重新拉取。

编辑页右上角的日志按钮可以跳到「日志」页并自动按这个服务器名过滤，排查连接失败问题时很有用。

## 让 AI 代为配置

复杂的 MCP 配置可以直接交由 AI 完成，其管理工具可指定安装到全局或项目。新增或移除后配置**在下一次会话生效**（新建会话时会自动连接未连接的服务器）。