如何添加一个自定义 MCP 服务
MCP(Model Context Protocol)给 Agent 挂载”工具 / 数据源”。本教程说明如何在 GIS Agent 中新增 一个自定义 MCP,适用于本机开发环境与离线 / 内网部署。 与添加自定义技能不同,MCP 的生效面更窄也更专:它只影响 Agent 工具列表,没有”技能市场”那种文件遍历展示。所以理解 MCP 只需要抓住一条链路—— “登记 → 打包同步(或 L1 热更下发)→ 运行实例读取”。先选择形态
GIS Agent 支持两种 MCP,按需选一种:下面以内置的knowledgecli(remote)作为参照实现讲解。你新增自己的 MCP 时,把knowledgecli换成你自己的 id(如hello)、把服务与端口换成你自己的即可。
关键约束(离线部署)
- 镜像必须内置:remote MCP 的服务镜像要加入
package.sh的镜像清单,被docker save导出、 目标机docker load,运行期零公网(内网机器拉不到 registry)。 - 端口预留:新增 remote MCP 的内部端口不得与既有端口冲突——
17076(GISAgent)、17072(数据库)、18081、18088(knowledge MCP)、19081、3333(Gateway)、17077(文档站)。选一个未占用的内部端口即可,通常只需内部网络可达,不必对外发布。 - secret 卫生:MCP 若需鉴权 key,一律走
config/local/secrets/<ENV_KEY>(file 后端)或 ASE, 在配置里用${env.X}引用,绝不写死进目录 / 镜像 / 文档;并纳入verify-no-secret-literals.sh扫描。 - 多 CLI 对齐:Agent 侧除了 OpenCode,还有
.claude/.qwen/.qoder各自的settings.json。新 MCP 需在opencode.json与各 CLI 的mcpServers里都登记,指向同一服务, 否则换 Agent 内核时工具不一致。
MCP 生效链路(一条)
opencode.json 的 mcp 变更,只有被 rewrite_staged_agent_model_config 同步进
OPENCODE_CONFIG_CONTENT 才会被运行实例读到;不经过它就改了不生效。
形态一:新增一个 remote HTTP MCP(推荐路径)
参照内置knowledgecli:opencode.json 里就是
knowledge-mcp-http 服务(镜像 knowledge-mcp-http:latest、内部端口 18088、
健康检查 /health)。你新增自己的 remote MCP,按下面 6 步。
模板工程:官方在gisagent/custom/mcp/hello-mcp/提供了一个最小但完整的 remote HTTP MCP 模板工程(Node.js +@modelcontextprotocol/sdk、/health+/mcp、内部端口18090), 包含package.json、package-lock.json、tsconfig.json、src/index.ts、Dockerfile、README.md。 你可以直接复制 这个目录改造成自己的 MCP 服务。
1. 备好 MCP 服务镜像
用一个能对外暴露http://<host>:<port>/mcp 的服务,自带镜像或写一个 Dockerfile。
2. 在 docker-compose.yml 加服务
若源目录路径可能需要可移植(离线 bundle 用相对路径),在package.sh的generate_portable_compose替换表里,把宿主机绝对路径改写成 bundle 相对路径(参照 knowledge 的写法)。
健康检查工具注意:模板镜像基于node:20-alpine,内含wget但没有curl, 因此 healthcheck 用wget。若你的镜像里有curl也可以改用curl -f。
3. 让镜像离线内置
把hello-mcp:latest 加入 package.sh 顶部镜像清单(与 knowledge-mcp-http:latest 同列),
./package.sh 时会 docker save 进 bundle,目标机 docker load。
4. 在 opencode.json 登记
编辑 config/opencode/opencode.json,在 mcp 下新增一项:
url 用服务名 + 内部端口(Docker 内网解析),不是 localhost。
5. 对齐各 CLI 的 mcpServers
在 package.sh 重写 .claude / .qwen / .qoder 的 settings.json 的段落里,为 hello
增加同名 server,指向同一内部 URL(照 knowledgecli 现有写法复制一份)。这样换用 Claude / Qwen /
Qoder 内核时也能看到该工具。
6. 打包并生效
形态二:新增一个 local / stdio MCP
参照内置personal-knowledge-mcp(opencode.json 里以本地 stdio 拉起)。复用它的打包范式:
- 用
package.sh的copy_tree_contents_excluding把 npm 包拷进 bundle(默认去掉.git/node_modules/target;确需 vendornode_modules时再放行)。 - 写一个 sanitize 步骤(照
sanitize_staged_personal_knowledge):清空运行期数据 / 索引、 生成 portableconfig.json、chmod收紧、确保运行 UID(1001)可读其运行目录。 - Compose 把该目录只读挂进
agent-*(例如./personal-knowledge-mcp:/opt/mcp/<name>:ro), 以 stdio 命令启动。 - 在
config/opencode/opencode.json的mcp.<id>登记本地 / stdio 形态,并在各 CLImcpServers里对齐;纳入verify-no-secret-literals.sh扫描。
已部署环境就地热加(免全量重部署)
若目标机已在运行、只想挂一个 remote MCP 验证或增量上线,不需要走package.sh 全量重打包。
但先要认清生效载体,避免改错文件:
- 运行实例(含 Web UI 每会话拉起的临时 ACP 容器)真正读取的是 gisagent 挂载的
profile
config/local/agent.local-*.json(${GISAGENT_AGENT_CONFIG},默认agent.local-qwen-fable.json)里runtime.env.OPENCODE_CONFIG_CONTENT的mcp段。 - bundle 的
config/opencode/opencode.json是打包期源文件,经rewrite_staged_agent_model_config同步进上面的 profile;只改它、不热更也不重启, 对正在运行的会话无效。 - 变更后必须新建会话验证(旧会话缓存工具快照)。
OPENCODE_CONFIG_CONTENT 的 mcp 段,
所以热加是单步配置热更(L1)。以下两种方式任选其一(2026-09-23 已在本机栈
“应用 → Web UI 新会话验收 → 同链路还原清理”全闭环实测)。
方式 A:手工热更(步骤少,适合一次性调试)
方式 B:热更包(推荐,自动备份 + 健康闸门 + 失败自动回滚)
docker-hot-update 框架把更新分为 L0~L3:L0 免重启刷卷(用于 SKILL 同步),L1 配置
热更(MCP 注册就是这一层),L2 单镜像热更,L3 全量 bundle 冷更。
开发机改好 profile 后打包(scripts/package-hotfix.sh):
scripts/hot-update.sh,package.sh 自
2026-09-23 起同步拷贝;旧 bundle 把该脚本单独拷进栈目录即可;执行机需 python3 +
PyYAML 解析 manifest):
/gis/ 返回 200 才算过),
失败自动回滚;历史记录在 <栈目录>/.hotfix-backups/hotfix-history.log。
撤销热加:把还原后的 profile 再打一个 L1”还原包”,按同链路 apply 即可(实测清理即此法,
还原后生效副本回到 mcp=[hello, knowledgecli])。
若热加的是一个全新 MCP 服务镜像(不只是注册):起镜像属 L2(docker load 版本化 tag +
定向 recreate,镜像需已随 bundle 交付或人工 docker save/scp 传输);base 镜像链变化
(如 postgiscli)则必须回 L3 全量。
正式交付边界:热更加完别忘了把同一 MCP 登记回仓库config/opencode/opencode.json与各 CLIsettings.json的mcpServers,以下一次package.sh全量包为准——打包门禁会校验 注册面一致性,热更只解决”当场生效”。
验证结果
-
本机快速验证(看运行实例到底加载了哪些 MCP):
每个服务会带
connected/ 失败状态。注意opencode读的是运行实例当前生效的配置:聊天 ACP 的mcp来自OPENCODE_CONFIG_CONTENT(由 gisagent 从挂载目录注入,会与全局~/.config/opencode/opencode.json合并)。因此只改仓库config/opencode/opencode.json不会立刻 反映到这条命令——要么”重新打包 → 重启 gisagent → 重建运行实例”,要么按上文 “已部署环境就地热加”直接改挂载 profile 并定向重启;只想快速核对,可临时OPENCODE_CONFIG_CONTENT='{...}' opencode mcp list或直接改容器内生效配置。 -
服务健康(从 gisagent 容器网络):
curl -s -o /dev/null -w "%{http_code}\n" http://<mcp服务名>:<内部端口>/health返回200(gisagent 镜像里有curl,没有wget)。 - 对话可见:新建会话(旧会话缓存工具快照),向 Agent 询问它有哪些工具或直接触发该 MCP 能力。
常见问题
服务起了,但 Agent 里看不到工具? 确认opencode.json 的 mcp.<id> 已登记,并且已进入生效载体 OPENCODE_CONFIG_CONTENT——
要么经 package.sh 同步进 profile,要么按”已部署环境就地热加”直接改挂载 profile;
再确认已”重启 gisagent(+ agent-opencode)→ 新建会话”。只改仓库源文件而不热更/重打包,
运行实例读不到。
opencode mcp list 显示 connected,但 Web UI 聊天里 Agent 说工具不存在?
这是最常见的原因:Web UI 每个会话启动临时容器(gisagent-agent-opencode-<user>-<session>-<hash>),
不是长运行的 agent-opencode 容器。临时容器的 OPENCODE_CONFIG_CONTENT 来自 gisagent 挂载的
config/local/agent.local-*.json(→ /workspace/config/agent.json),不是仓库的
config/opencode/opencode.json。如果 agent.local-*.json 里的 OPENCODE_CONFIG_CONTENT 没有
包含你的 MCP,Web UI 会话就看不到工具。
开发机修复:更新 config/local/agent.local-*.json 的 OPENCODE_CONFIG_CONTENT(加入新 MCP),
然后 docker compose restart gisagent,再新建会话。不需要 package.sh
(package.sh 仅用于离线 bundle 交付打包)。
目标机拉不到镜像(connection refused)?
离线机器没有 registry 访问。remote MCP 镜像必须先加入 package.sh 镜像清单被 docker save 导出,
部署时 docker load;运行期不联网。
端口起不来 / 服务不健康?
检查端口是否在预留段内、有无冲突(对照上文端口清单),以及 url 用的是服务名+内部端口而非
localhost(跨容器要用服务名)。若服务本身正常(手动请求 /health 返回 200)但 Docker 报
unhealthy,检查 healthcheck 命令用的工具在镜像里是否存在——例如 node:20-alpine 有 wget
没有 curl,healthcheck 要用 wget。
换了 Claude / Qwen 内核后工具没了?
只在 opencode.json 登记不够,还要在各 CLI 的 settings.json mcpServers 里对齐同一服务。
MCP 需要密钥?
走 config/local/secrets/<ENV_KEY> 或 ASE,用 ${env.X} 引用,绝不写死;纳入
verify-no-secret-literals.sh。
下一步
- 想扩展技能而非工具:阅读如何添加自定义技能。
- 独立 volume、联网判定等更复杂扩展场景:参考工程规范
openspecs/changes/docker-skill-mcp-extension/(含”验证台账 / 场景用例”,CASE-07 即 SKILL/MCP 热加的实测记录)。 - 热更框架的分级模型(L0~L3)、manifest 契约与回滚语义:参考
openspecs/changes/docker-hot-update/。