MCP
TIP
MCP（Model Context Protocol）用于把外部服务的工具接入 ChatLuna。接入后，这些工具对模型来说与原生工具无异，实际执行则在独立的本地进程或远程服务中完成。
接入数据库、搜索引擎、GitHub 或内部业务系统时，不一定要写插件。只要服务支持 MCP 这一开放协议，就能直接接入，它提供的工具会出现在 ChatLuna 的工具箱中。
MCP 页
点击「能力 → MCP」进入管理页面。可以在「卡片」和「列表」视图间切换，也可以按连接状态或传输方式分组。每张卡片显示：
- 服务 ID 和名称。
- 传输方式：本地命令或远程地址。
- 连接状态。
- 工具数量：成功导入的工具数。
- 最近一次错误。
点击卡片打开详情抽屉，查看配置、连接参数和完整的工具清单。参数结构不兼容的工具会被跳过，并在清单中注明原因。
添加服务
点击「添加服务」，有三种方式：
- 本地命令：填写可执行文件、参数、环境变量和工作目录，在宿主机上启动服务。
- 远程地址：填写端点和请求头，连接已独立部署的 HTTP 服务。
- 粘贴导入：粘贴现成的配置文本，自动解析并批量导入。
填写后先点击「测试连接」：系统会连接服务、拉取一次工具清单后断开，不会影响正在运行的会话。确认无误后点击「保存并启用」。
WARNING
本地命令以与 ChatLuna 进程相同的权限运行。不要连接来源不明的命令或脚本；不可信的服务请部署在隔离容器或远程主机中，通过远程地址接入。
两种传输方式
stdio
在宿主机上启动子进程，通过标准输入输出通信。适合本地轻量工具、命令行封装或需要读写本地文件的服务。可以设置：
- 启动命令：可执行文件名或绝对路径。
- 命令行参数。
- 环境变量：敏感值可以作为密钥保存，不在界面上明文显示。
- 工作目录。
- 单次调用超时：默认
120秒。
启用服务时自动启动子进程，停用服务、卸载插件或关闭实例时终止。子进程意外退出时卡片显示出错，可以手动重连。
http
通过 HTTP/HTTPS 连接远程端点，适合独立部署的服务，或多个实例共享同一个服务。可以设置端点 URL、请求头（认证令牌可以作为密钥保存）和单次调用超时。
HTTP 方式不需要在本机管理子进程，但远程服务必须完整支持 MCP 的流式传输规范。
工具命名
为避免与原生工具冲突，MCP 工具统一命名为 mcp__服务ID__工具名。例如服务 github 的 search_repos 工具会变成 mcp__github__search_repos。
- 非法字符会被替换。
- 过长的名称会截断到
64个字符以内。 - 处理后与已有工具重名时，跳过该工具并记录警告。
工具的参数结构会映射为 ChatLuna 的参数模型。不支持的参数会被忽略并记录日志，整体无法解析的工具会被跳过。
TIP
在「工具」页面搜索 mcp__ 即可筛选出所有 MCP 工具，也可以用通配符批量设置，例如全部设为按需加载或需要审批。
连接状态
- 已停用：已保存但未启用。
- 连接中：正在建立连接并拉取工具定义。
- 已连接：工具已就绪。
- 出错：连接失败或中途断开，卡片显示原因。
- 缺少传输支持：缺少对应传输方式的插件。
- 空闲：已启用，但尚未实际连接。
单个服务出错不会影响其他服务和系统运行。修复后点击重连即可，无需重启实例。修改配置、安装或卸载插件、重启实例时，系统都会自动重连并刷新工具列表，正在执行的调用不会被中断。
与工具页、权限的关系
MCP 工具与原生工具遵循同一套治理规则：在「工具」页面单独设置策略，在「场景规则」中按群控制可见性，由全局权限模式把控高风险调用，开启工具搜索后可以按需加载（推荐的默认做法）。
MCP 服务本身不负责访问控制，工具能否执行、是否需要审批，始终由 ChatLuna 的工具策略和权限规则决定。
常见服务类型
- 文件与代码：读写本地文件、检索代码仓库、在沙箱中执行命令。
- 数据库：获取表结构、执行只读查询。
- 搜索与网页：调用搜索引擎、抓取网页、生成摘要。
- 项目管理：GitHub、GitLab 的 Issue、Pull Request 和任务看板。
- 内部系统：查询订单、同步库存、创建工单等。
接入前先了解工具是否只读、是否依赖认证、调用后是否有不可逆的副作用。会写入、修改或执行外部指令的工具，建议设为需要审批。
推荐配置
| 场景 | 建议 |
|---|---|
| 个人实例 | 用 stdio 接入一两个常用服务；修改本地文件或执行命令的工具设为需要审批 |
| 多实例共享 | 把服务部署为独立的 HTTP 服务供多个实例共用，各实例使用自己的认证凭据和工具策略 |
| 工具很多 | 开启工具搜索，MCP 工具默认按需加载，只把少数高频工具设为常驻，阈值保持 20 左右 |
| 高风险环境 | 避免用本地命令运行不可控程序，改为容器或独立主机 + 远程地址；写入类工具需要审批，命令执行类默认禁用 |
常见问题
服务一直显示出错：查看卡片上的错误信息。常见原因有命令不存在或路径错误、参数格式错误、远程端点不可达、认证失败或协议版本不兼容。本地命令可以先在终端中单独运行试试。
连上了但没有工具：服务可能没有暴露任何工具，或所有工具都因参数格式被跳过，在详情的工具清单中查看原因。
模型看不到某个 MCP 工具：依次检查服务是否「已连接」、工具是否被跳过、是否在「工具」页或「场景规则」中被禁用，以及是否处于按需加载且尚未被搜索到。
工具名冲突：两个服务导出了同名工具，或处理后名称相同。修改其中一个服务的 ID 来改变前缀，或在「工具」页禁用其中一个。
调用总是超时：调大「单次调用超时」，并检查外部服务是否存在阻塞或长时间无响应。
