4.6 KiB
DEMO-012 MCP Gateway 使用说明
范围
DEMO-012 提供独立的 Enterprise Knowledge MCP Gateway,通过标准 Streamable HTTP 暴露一个
只读工具:search_knowledge。Gateway 直接复用 API 进程使用的 SearchService 组合,不复制
Dense Retrieval、Reranker 或 Source Enrichment 逻辑。
当前 Demo 只建立认证和身份传递边界:一个运行时注入的专用 Bearer Token 映射到一个
user/service identity,并且只有 knowledge:search scope。它不是共享超级管理员 Token,也不
代表 V1 OAuth、Document ACL 或完整 MCP P0 工具已经完成。
配置
必须通过运行环境提供至少 32 字符的随机 Token:
export MCP_AUTH_TOKEN="<runtime-secret-with-at-least-32-characters>"
make run-mcp
默认地址为 http://127.0.0.1:8766/mcp。除现有数据库、BOS、Embedding、Vector 和 Reranker
配置外,Gateway 支持:
| 变量 | 默认值 | 说明 |
|---|---|---|
MCP_HOST |
127.0.0.1 |
监听地址;本地默认不暴露到其他网卡 |
MCP_PORT |
8766 |
Gateway 端口 |
MCP_PATH |
/mcp |
Streamable HTTP 单一端点 |
MCP_PUBLIC_URL |
http://127.0.0.1:8766/mcp |
MCP Resource Server URL |
MCP_ISSUER_URL |
http://127.0.0.1:8766 |
Demo Token 的身份颁发方标识 |
MCP_CLIENT_ID |
workbuddy-enterprise |
MCP Client 类型标识 |
MCP_SERVICE_IDENTITY |
workbuddy-demo |
传入业务边界的服务身份 |
MCP_REQUIRED_SCOPE |
knowledge:search |
Tool 所需最小 scope |
MCP_ALLOWED_HOSTS |
仅本机/test | DNS rebinding Host allowlist,JSON 数组 |
MCP_ALLOWED_ORIGINS |
仅本机 | Origin allowlist,JSON 数组 |
远程部署必须使用 TLS 反向代理,并把公开域名加入 MCP_ALLOWED_HOSTS;有 Origin 的客户端还
必须显式配置 MCP_ALLOWED_ORIGINS。Token、真实域名和内部 Endpoint 不得提交 Git。
WorkBuddy / CodeBuddy 配置
WorkBuddy Enterprise 官方客户端支持 type: "http"、远程 URL、自定义 Header 和环境变量
展开。可复制 deploy/workbuddy-mcp.example.json 作为项目配置,内容如下:
{
"mcpServers": {
"enterprise-knowledge": {
"type": "http",
"url": "${EKP_MCP_URL:-http://127.0.0.1:8766/mcp}",
"headers": {
"Authorization": "Bearer ${EKP_MCP_TOKEN}"
},
"description": "企业知识检索"
}
}
}
只提交包含环境变量占位符的配置;EKP_MCP_TOKEN 必须由每个运行环境安全注入。连接后应只
发现 mcp__enterprise_knowledge__search_knowledge 一个工具。
安全和错误语义
- 缺失或错误 Token 返回
401,缺少 scope 返回403; - 未批准 Host 返回
421,未批准 Origin 返回403; - Query 长度和
top_k在 MCP schema 层校验; - 预期业务错误返回安全 Tool Error;未知 Provider/数据库错误收敛为
knowledge search failed; - MCP 输出和 Gateway 日志不得包含 Token、Provider Endpoint、数据库表名、模型名或 Index Profile。
验证
uv run pytest tests/unit/test_mcp_auth.py tests/unit/test_mcp_search.py
uv run pytest tests/integration/test_mcp_server.py
集成测试使用官方 MCP Python Client 通过 Streamable HTTP 完成 initialize、tools/list 和 tools/call,并使用与 WorkBuddy 相同的 Bearer Header 配置验证身份传递、无结果、参数错误、 认证失败、Origin 防护和错误脱敏。
WorkBuddy 现场验收记录
2026-09-02 使用 WorkBuddy Desktop 5.3.14 自带的 CodeBuddy CLI 2.115.0 完成兼容性
验收。客户端直接加载 deploy/workbuddy-mcp.example.json,健康检查为 Connected;工具
发现结果只有 mcp__enterprise-knowledge__search_knowledge,随后以字符串 query 和
top_k=1 完成 Tool 调用并读取结构化 filename、section、content 等来源字段。
现场验收使用 DEMO-012 的真实 Gateway、Bearer 验证、service identity 传递、输入 Schema 和
Tool 注册代码。为避免外部数据库与模型波动掩盖客户端兼容性,检索应用使用确定性验收返回;
真实 Provider 检索链路由 ARCH-006 的受控验收负责。非交互 CLI 需要批准 MCP Tool 调用,
本次只在单次会话中允许 DeferExecuteTool,没有永久启用跳过权限。测试结束后已删除临时 MCP
配置并停止本地 Gateway,未写入真实凭据。
参考: