MCP 接入

字数

1812 字

阅读时间

7 分钟

TIP

MCP（Model Context Protocol）是把外部服务的工具接入模型上下文的开放协议。现成的数据库查询服务、GitHub 客户端、内部工单系统不需要专门写 ChatLuna 插件，用 MCP 接入即可。接入后，这些工具对模型来说和内置工具完全一样。

服务定义

servers: {
  github: {
    transport: 'stdio',
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-github'],
    env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
    timeoutMs: 120_000,
  },
  internal: {
    transport: 'http',
    url: 'https://mcp.example.com/mcp',
    headers: { Authorization: 'Bearer ...' },
  },
}

键名就是服务 ID（如 github、internal），会作为投影工具名的前缀。

字段	说明
`transport`	传输协议类型，支持 `stdio` 或 `http`
`enabled`	实例启动时是否自动建立连接
`command` / `args` / `cwd`	`stdio` 模式下的启动命令、运行参数及工作目录
`env`	`stdio` 子进程的环境变量键值对
`url` / `headers`	`http` 模式下的服务端点 URL 与请求头
`timeoutMs`	单次工具调用的超时时间（毫秒）

环境变量与请求头作为机密加密保存，界面和导出配置中都会脱敏。

传输协议

stdio：在本地启动子进程，通过标准输入输出通信。适合本地开发工具、CLI 封装和需要读写本地文件的服务。子进程随服务启用而启动，随停用或插件卸载而终止。
http：连接远端 MCP 端点，支持流式传输。适合容器化或独立部署的服务，也便于多个实例共用。端点必须完整实现 MCP 的流式传输规范，否则连上后交互也可能异常。

WARNING

stdio 子进程拥有和 ChatLuna 相同的系统权限。不要接入来源不明的服务，尤其是能执行命令或写文件的。

连接生命周期

状态	含义
已停用	服务配置已保留，但连接处于关闭状态
连接中	正在建立连接并拉取工具清单
已连接	连接成功，导出的工具已就绪
出错	握手失败、连接中断或远端进程异常退出
缺少传输支持	当前运行环境缺少对应传输协议所需的插件
空闲	服务已开启，但尚未满足连接条件

以下情况会触发重连：保存服务配置、安装更新或卸载传输插件、实例启动或热重载、在控制台点击「重连」。

重连会重新拉取工具清单并更新定义。进行中的调用不会被打断，新调用使用刷新后的定义。工具清单是运行时快照，服务端改了工具不会自动推送过来，手动重连一次即可。

单个服务出错不会影响其他服务，也不会让实例崩溃，它会停在「出错」状态，并在界面和日志中显示原因。

工具投影

外部工具按以下规则投影为内部工具：

text

mcp__<服务 id>__<工具名>

例如 github 服务的 search_repos 投影为 mcp__github__search_repos。非法字符替换为下划线，总长度截断到 64 个字符；与已有工具冲突时跳过注册并记录警告。

TIP

借助 mcp__ 前缀和通配规则，可以一次性配置所有外部工具，例如统一设为按需发现或需要审批。

参数结构：外部工具的 JSON Schema 会转换为内部 Schema。标准字段直接映射，不支持的扩展字段忽略并写入调试日志，Schema 损坏的工具直接跳过。「连上了但工具列表为空」通常就是这个原因。

执行结果：返回内容序列化为文本注入上下文。服务把结果标记为失败（isError）时抛出执行异常，让 Agent 感知失败并重试或补救。

与工具系统的关系

投影后的工具与内置工具一样，受工具策略、场景规则、权限与审批的约束，也可以设为按需加载。服务方只负责提供能力，谁能在什么场景使用由 ChatLuna 决定。

WARNING

不要把 MCP 当作安全边界。服务端声明「只读」不能替代宿主的安全控制，权限要在 ChatLuna 的工具策略和权限规则中配置。

安全

凭据：环境变量和 Headers 作为机密存储，查看和导出时都脱敏。
超时：单次调用默认 120 秒，连接与握手默认 30 秒，可按服务调整。
进程：只连接官方或可信来源的服务；在启动参数中锁定依赖版本，避免动态拉取最新版；高危或需要强隔离时，把服务放进独立的 Docker 容器或远端服务器。

常见服务类型

类型	典型能力
文件与代码	读写本地代码仓库、代码符号检索、沙盒命令执行
数据库	表结构与 Schema 读取、只读 SQL 查询、元数据统计
搜索与网页	网页搜索抓取、正文解析与摘要提取
项目管理	GitHub / GitLab 的 Issue 与 PR 查询、看板协作
内部系统	企业内部 ERP、CRM、库存管理及工单系统对接

常见问题

服务一直出错：看控制台报错。常见原因是 command 路径不存在、参数错误、端点不通、鉴权失败或协议版本不兼容。stdio 服务先在终端手动运行启动命令；http 服务先查网络和 Headers。

连上了但没有工具：确认服务确实声明了 Tools（有的只提供 Resources 或 Prompts），并查看日志中是否有因 Schema 不规范被跳过的工具。

模型看不到某个 MCP 工具：依次检查服务是否已连接、工具是否因重名或 Schema 错误被跳过、全局策略是否禁用、场景规则是否过滤、是否设为按需加载而模型还没检索。

工具名冲突：修改服务 ID（如把 git 改为 github_corp），或在工具策略中禁用其中一个。

调用超时：调大该服务的 timeoutMs，检查外部服务是否阻塞。长时间的异步作业应改造成支持轮询或后台任务。

下一步

MCP 使用指南 — 面向使用者的接入与管理。
工具系统 — 投影工具如何被治理与过滤。
技能 — 如何组织工具的使用方法。
权限与审批 — 为外部工具配置审批边界。

页面历史

最后编辑于 26 分钟前

查看完整历史

MCP 接入 ​

服务定义 ​

传输协议 ​

连接生命周期 ​

工具投影 ​

与工具系统的关系 ​

安全 ​

常见服务类型 ​

常见问题 ​

下一步 ​