MCP Server 管理

把 Claude Code 的"扩展能力"变成可视化操作——不必手编 ~/.claude.json，不必查 JSON 字段格式，添加 / 启用 / 禁用 / 切作用域，全部在 GUI 里点选完成。

MCP 是什么

MCP（Model Context Protocol）是 Claude Code 的扩展机制，让 AI 调用外部工具或访问外部数据源。最常见的几类：

• 本地工具型：context7 文档检索、filesystem 文件操作、git 仓库查询
• 远程 API 型：内部知识库、CRM、监控系统的 HTTP 接口
• 自研脚本型：你团队的内部工具（如自动化部署、日志查询）

MCP Server 启动后，AI 在对话中可以"调用"它定义的工具，相当于给 Claude 装外挂。

三种服务器类型

智码 AICoder 支持完整的 MCP 三种连接方式：

类型	通信方式	适用场景
Stdio	本地启子进程，通过标准输入/输出通信	大多数本地工具，如 npx 启动的 MCP 包
HTTP	HTTP 请求 / 响应	远程 REST API，无状态调用
SSE	Server-Sent Events 长连接	远程流式服务，需要实时推送

双作用域

每个 MCP Server 可以绑定到两种作用域：

作用域	存储位置	适用
全局（user）	~/.claude.json 顶层 mcpServers	所有项目共用，如通用文档检索
项目级（project）	~/.claude.json 的 projects[<path>].mcpServers	仅在该项目目录启动会话时生效，如项目内部工具

切换作用域时，配置自动写到对应位置，无需手动改 JSON。

操作流程

入口在哪里

MCP Server 是按 AI 工具分别配置的：打开 设置，在左侧选中要配置的 AI 工具（如 Claude Code、Codex），工具页里的「MCP Server」一栏就是管理面板。除 Claude Code 外，其他支持 MCP 的 CLI 也在各自的工具页里配置，操作方式相同。

Claude Code 的聊天模式会话还可以在头部条打开 MCP 面板，「配置」页就是这里的同一份面板（见查看运行状态与重连）。

添加 Stdio Server

设置 → 对应的 AI 工具 →「MCP Server」→「添加」→ 选 Stdio：

字段	说明	示例
名称	同作用域内唯一	context7
Command	可执行命令	npx
Args	命令参数（每行一个）	-y @upstash/context7-mcp@latest
Env	环境变量 K-V	API_KEY=sk-xxx
Scope	全局 / 项目级	全局

保存后立即写入 ~/.claude.json，下次启动 Claude Code 时生效。

添加 HTTP / SSE Server

「添加」→ 选 HTTP 或 SSE：

字段	说明	示例
名称	同作用域内唯一	internal-api
URL	服务器端点	https://api.example.com/mcp
Headers	请求头 K-V	Authorization: Bearer xxx
Scope	全局 / 项目级	项目级

写入格式（HTTP/SSE 必须包含 type 字段）：

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": { "Authorization": "Bearer xxx" }
    }
  }
}

启用 / 禁用

每个 Server 卡片有开关，关掉时写入 "disabled": true，CLI 启动时会跳过它。

临时禁用 vs 删除

禁用保留所有配置，将来可一键打开（适合"暂时关掉看看是不是它的问题"）。删除彻底移除（适合不再用的 Server）。

编辑 / 重命名

编辑器允许修改任意字段。重命名时保留 disabled 状态——如果你之前禁用了它，重命名后仍是禁用。

列表视图

「MCP Server」面板默认按作用域分组：

[全局 MCP Server]
  ✓ context7        npx -y @upstash/context7-mcp@latest
  ✗ filesystem      （已禁用）

[当前项目: /path/to/project]
  ✓ internal-api    https://api.example.com/mcp [HTTP]
  ✓ db-query        ./scripts/db-mcp.sh

每个条目右侧有「编辑 / 禁用 / 删除」按钮。

查看运行状态与重连

上面管的是配置：写在文件里，会话下次启动才生效。某个会话此刻连上了哪些 MCP、哪台挂了，要看运行状态。这部分目前只支持 Claude Code。

聊天模式：MCP 面板

在 聊天模式 的会话里，点头部的「MCP」按钮，或在输入框发 /mcp，打开「MCP 服务器」面板。有服务器连接失败时，「MCP」按钮会变红并显示失败台数。

面板分「运行态」和「配置」两页。「运行态」页答的是这条会话现在连上了什么：

能看到 / 能做	说明
状态	已连接 / 连接中 / 待授权 / 连接失败 / 已禁用，附工具数、版本、类型、作用域
失败原因	先告诉你该查什么，原始报错另起一行
重连	只重连这一台，不重启会话，也不丢上下文
启用 / 禁用	当前会话立刻生效，同时写进配置，下次启动也照此
自动重连	右上角开关。连接失败的服务器在会话空闲时自动重连，最多 3 次（间隔 0 / 1 / 5 分钟）；成功不打扰，放弃了才在聊天里说一声。只对本条会话生效
待授权的 claude.ai 连接器	点「去 claude.ai 授权」，授权后回来重开这条会话

「配置」页就是本页的管理表单。注意时间差：在这里加、删、改命令，要等这条会话下次启动才生效，改完切回「运行态」看到的仍是旧状态，属正常。想让某台立刻停用，在「运行态」页点「禁用」。

终端模式：掉线自动重连

本地启动的 MCP（即上文的 Stdio 类型）进程一旦退出，Claude Code 既不提示、也不会自己重新拉起，工具会从 AI 的工具表里悄悄消失。智码会替你盯着：

行为	说明
自动发现并重连	发现某个之前在跑的 MCP 进程没了，就在会话空闲、输入框没有草稿时自动重连，并在会话上提示正在第几次重连
重试上限	最多 3 次（间隔 0 / 1 / 5 分钟）；仍未恢复就停下，提示你检查它的程序是否在运行，再手动重连
不打扰	重连不会被算作一轮回答，也不会弹「回答完成」通知
开关	设置 → MCP 接入 →「终端会话 MCP 掉线自动重连」，默认开启

手动重连

在标签栏或侧边栏里右键 Claude Code 会话 →「重连 MCP」→ 选要重连的服务器。它会在会话空闲时才发出，不会打断正在跑的工具；会话正忙就先排队，空闲后自动执行。侧边栏里要求该会话已经打开为标签。

自动重连和右键菜单只覆盖本页管理的服务器（全局与项目级），不含项目目录里自带的 .mcp.json 和插件附带的服务器。

接入了智码 MCP 的 AI 也能自己重连：发现某个工具不见了，它可以调 reconnect_mcp 让智码代为重连，见让外部 AI 接入 AICoder。

远程工作区里的 MCP

场景	说明
配置跟着工作区走	停在远程 SSH 工作区时，本页读写的是那台远程主机上的 MCP 配置，本机与远程互不影响，详见远程工作区
远程会话也能用本机智码的工具	远程主机上的 Claude Code 会话同样能调用智码自己的 MCP 工具（内置浏览器、会话记录、代码片段等）：每次开远程会话时自动接好，经 SSH 加密通道回连本机，不用手动配置，也不对外网开放

出于安全，远程会话只能访问该工作区的数据，不能读写本机其它项目的文件，也不能在本机启动任务或新会话。如果服务器关闭了 SSH 端口转发，远程会话里就没有这些工具，会话本身照常可用。智码对外提供的这组工具见让外部 AI 接入 AICoder。

跨实例同步

MCP 配置在 ~/.claude.json 里，WebDAV 云同步 默认勾选「Claude 配置」时会一并同步。换机器/设备时一次性带过来。

远程 Server 的认证密钥

如果 HTTP/SSE Server 的 Headers 里硬编码了 API Key，云同步时会明文上传到 WebDAV。建议：

• 私有 WebDAV 服务：可接受
• 公共云盘（如 webdav.aliyundrive.com）：把 Key 放本地环境变量，Server 配置只放占位符，导入后再补

常见 MCP Server 推荐

文档检索类

context7   →  npx -y @upstash/context7-mcp@latest

让 AI 实时查询任何库的官方文档，避免凭训练数据胡编 API。

文件系统类

filesystem  →  npx -y @modelcontextprotocol/server-filesystem /path

让 AI 读写指定目录（受 Claude 工具权限二次约束）。

Git 类

git  →  uvx mcp-server-git --repository /path/to/repo

让 AI 查询提交历史、diff、blame。

更多服务器列表见 MCP 官方仓库。

故障排查

现象	排查方向
Claude 启动后看不到 MCP 工具	检查是否禁用 / 检查 ~/.claude.json JSON 格式是否合法
Stdio Server 启动失败	在终端手动跑一遍 command + args 看是否报错；环境变量是否齐全
HTTP Server 401/403	Headers 里 Authorization 是否正确；URL 末尾斜杠是否多/少
项目级 Server 没生效	Claude Code 启动时 cwd 必须正好等于配置里的项目路径
同名 Server 添加失败	同作用域内名称必须唯一；改个名或先删旧的
工具用着用着消失了	多半是那台 MCP 的进程退出了：等自动重连，或右键会话「重连 MCP」
聊天模式里改了配置没生效	配置改动要等会话下次启动；想立刻启停，在 MCP 面板「运行态」页操作
自动重连 3 次后放弃	先确认那台 MCP 的程序本身能跑起来（在终端手动跑一遍 command + args），再手动重连

相关章节

• 多 AI 工具统一管理 — 九家 CLI 各自的扩展机制对比
• 配置档案管理 — MCP 配置随 Claude 配置一起作为 Profile 管理
• WebDAV 云同步 — MCP 配置跨设备同步
• 聊天模式 — 聊天模式会话的 MCP 面板所在
• 远程工作区 — MCP 配置按工作区隔离
• 让外部 AI 接入 AICoder — 反方向：智码自己当 MCP 服务，让 Claude Code 等调用它