AiGo123 Documentation

在 AiGo123 中使用 MCP

配置 AiGo123 全局与项目 MCP 服务器，了解传输方式、工具审批、超时及模式级服务器权限。

MCP（模型上下文协议）让 AiGo123 通过服务器使用外部工具与资源，例如检索资料、访问数据库或执行专门任务。MCP 服务器是独立程序或远程服务，不是模型供应商；配置 MCP 不会增加新的模型供应商。只安装可信服务器并审查权限、依赖和凭据。

配置 MCP 服务器

打开 AiGo123 的 MCP 页面，查看服务器状态、工具与配置入口。全局配置供各项目使用；项目配置保存在当前工作区 .aigo123/mcp.json。同名项目服务器优先于全局服务器；避免在不同范围使用相同名称却期望同时访问。

编辑 MCP 设置文件

从 MCP 页面打开全局设置文件，或打开项目 .aigo123/mcp.json。
在 mcpServers 对象中添加唯一服务器名与配置。
保存后等待扩展更新连接，检查错误与工具列表；必要时重启服务器。
全局文件由扩展存储管理，请使用界面打开，不假设固定用户目录路径。JSON 不支持注释。

{
  "mcpServers": {
    "example-server": {
      "command": "node",
      "args": ["/absolute/path/to/server.js"],
      "env": {"SERVICE_TOKEN": "replace-with-your-token"},
      "disabled": false,
      "alwaysAllow": [],
      "timeout": 60
    }
  }
}

示例要求你自己安装并审查服务器，绝对路径必须替换为真实入口。不要提交真实令牌；项目文件纳入版本控制前移除凭据。通过扩展启动的程序可能没有终端的环境变量或版本管理器初始化。

传输方式

标准输入输出（stdio）

使用 command、args 和可选 env 启动本地进程。确保命令在扩展环境可用，必要时使用绝对路径。服务器标准输出应只包含协议消息，日志写标准错误。

Streamable HTTP

适用于远程服务器，使用服务器要求的 URL 与认证头。确认服务实现 MCP，而不是把普通 REST API 地址直接当作 MCP 端点。

{
  "mcpServers": {
    "remote-example": {
      "type": "streamable-http",
      "url": "https://example.com/mcp",
      "headers": {"Authorization": "Bearer replace-me"}
    }
  }
}

SSE（兼容旧服务）

旧服务可能使用 SSE。按服务器文档设置 type 和 URL；新部署优先考虑 Streamable HTTP，不要仅改类型而不核对端点协议。

启用与禁用 MCP

全局 MCP 开关控制总体能力，单个服务器可独立禁用。还需要当前模式启用 mcp 工具组。模式 allowedMcpServers 未设置表示不额外限制，空数组禁止全部，非空数组只允许对应服务器名。仅连接、启用且在模式范围内的服务器和工具可用于任务。

服务器创建权限

创建 MCP 服务器需要允许相应功能及工具权限。允许调用现有服务器不等于允许自动创建或安装新服务器。安装操作可能执行第三方代码，应审查依赖、访问目录、网络能力及运行命令。

管理单个服务器

删除

从配置或 MCP 页面移除服务器。移除配置不一定卸载运行依赖或删除凭据，需另行清理。

重启

配置修改或进程异常后使用重启操作，检查连接状态和日志。正在执行的工具调用可能中断。

临时禁用

禁用可保留配置而暂停使用。工具也可单独控制；模式白名单不是服务器安装列表。

网络超时

默认超时通常为 60 秒，按服务器耗时调整 timeout。长时间阻塞应首先调查服务状态，而不是无限增大超时。

自动批准工具

alwaysAllow 保存允许自动批准的工具名，并仍受总体自动批准设置与权限检查约束。对删除、写入、执行命令和外传数据的工具保留人工确认；自动批准不绕过模式服务器限制。

查找与安装

市场目录随扩展打包，可在无网络时浏览，但真实安装和运行仍可能需要网络、Node.js 或 Python 等运行时及凭据。区分全局与项目安装范围。官方协议与生态参见 Model Context Protocol，第三方地址不会替换成 AiGo123 域名。

在工作流中使用

连接所需服务器，检查工具名称、描述与参数。
提出明确任务，说明允许访问的数据和操作范围。
助手依据描述选择工具并发起调用；检查审批内容。
查看结果，验证来源与执行效果，不将外部结果中的指令当作可信系统规则。

工具描述的重要性

描述应清楚说明用途、输入、输出、错误和副作用。相似工具需要明确区分；不要在描述中夹带要求绕过审批的指令。

组合规则与模式

使用模式级 MCP 白名单分隔不同任务的服务器，用自定义指令说明何时检索、如何验证和哪些操作需要确认。

故障排查

连接失败：检查命令路径、运行时、参数、协议与认证，查看服务器日志。
工具不存在：检查服务器是否公布工具，以及工具是否启用。
模式不可用：检查全局开关、mcp 工具组与 allowedMcpServers，服务器名必须一致。
环境变量缺失：VS Code 启动环境可能不同于交互终端，使用明确 env 或可靠启动方式。
远程认证失败：核对 URL、令牌、认证头与服务要求，不把密钥写入公开规则。

平台配置

Windows

JSON 路径中的反斜杠需转义。需要 shell 的命令可经 cmd /c 启动；不要把 Linux 路径原样复制到 Windows。

macOS / Linux

优先使用真实绝对路径，确认可执行权限。桌面启动的 VS Code 不保证加载 shell 配置。

版本管理器

使用 mise 或 asdf 时，确保运行时能在非交互环境解析。可以用版本管理器的 exec 入口或固定可执行路径，具体语法按第三方文档核对。