通用接入规范

本页适用于其他语言、已有 HTTP 服务或不使用官方 SDK 的场景。接入方必须自行实现本页全部要求；任何遗漏都会导致 Gateway 无法发现、认证或调用服务。新建 Python 和 Go 服务优先使用官方 SDK。

1. 服务接口与协议

服务必须暴露以下接口，并仅向 Gateway 网络来源开放 /mcp：

POST   /mcp
GET    /mcp
DELETE /mcp
GET    /health
GET    /metrics

传输使用 streamable-http，请求体为 JSON-RPC 2.0。
至少支持 initialize、tools/list、tools/call；声明 Resource 或 Prompt 时也支持对应的 list/read/get 方法。
支持 MCP 协议 2025-06-18 及以后版本，推荐 2025-11-25。
严格模式的 POST 请求应接受 Accept: application/json, text/event-stream 和 MCP-Protocol-Version；initialize 后的会话请求按 Streamable HTTP 处理 Mcp-Session-Id。
/health 返回 HTTP 200 和 {"status":"ok"}；/metrics 输出 Prometheus 格式指标。

Gateway 到 Server 使用以下 Header，不接受 Client 的 Authorization 作为服务认证：

X-MCP-Gateway-Token: <gateway-to-server-token>
X-Request-Id: <request-id>

缺少或错误 Token 必须返回 HTTP 401。服务还必须在网络层以 Kubernetes NetworkPolicy、安全组或防火墙限制，仅允许 Gateway 访问服务端口。

2. 使用注册 Token 自注册

先在平台申请 namespace 权限并创建注册 Token。服务首次启动时调用 Admin API：

curl -sS -X POST "$MCP_ADMIN_BASE_URL/admin/bootstrap/register-server" \
  -H 'Content-Type: application/json' \
  -d '{
    "registration_token":"<registration-token>",
    "namespace":"<namespace>",
    "name":"<server-name>",
    "display_name":"<display-name>",
    "transport_mode":"internal_http"
  }'

成功响应包含 gateway_token。将它作为运行时 Secret，用于校验后续 X-MCP-Gateway-Token；不能返回给 Client、写入日志或提交到仓库。同一注册 Token 只能绑定一个 Server；用它为其他 namespace 或服务名注册会失败。

内网测试平台地址为 192.168.50.133。将 MCP_ADMIN_BASE_URL 设置为测试环境公布的完整 Admin API 地址；地址只有 IP 时不能推断端口，须向平台运维获取。

3. 使用 etcd 上报实例与能力

每个实例申请 60 秒 lease，并在同一 lease 下写入以下五个 key；持续 keepalive，优雅退出时 revoke lease。{instance_id} 在同一服务内必须唯一。

/mcp/servers/{namespace}/{server_name}/instances/{instance_id}
/mcp/servers/{namespace}/{server_name}/tools/{instance_id}
/mcp/servers/{namespace}/{server_name}/resources/{instance_id}
/mcp/servers/{namespace}/{server_name}/resource_templates/{instance_id}
/mcp/servers/{namespace}/{server_name}/prompts/{instance_id}

实例 value 至少包含：schema_version: 1、namespace、name、instance_id、server_version、transport: "streamable-http"、Gateway 可访问的 base_url、mcp_path: "/mcp"、health_path: "/health"、metrics_path: "/metrics"、network_mode: "internal_http" 和 started_at。

tools value 使用 schema_version: 2，每项至少包括 name、description、input_schema、access_type 和 risk_level。resources、resource_templates、prompts 使用 schema_version: 1，包含相同身份字段和对应数组。Resource URI 必须是 mcp://{namespace}/{server_name}/{resource_path}。能力清单变化后必须重新写入对应 key。

4. 能力治理与本地安全

每个 Tool 必须声明 access_type（read 或 write）和 risk_level（normal、warning、danger）。
Resource 和 Prompt 必须声明描述、风险等级和敏感性；敏感内容不得包含凭据或超出调用者权限的数据。
在业务 Server 内执行对象范围、查询成本、数据脱敏、写操作确认、幂等性和危险参数校验。
Client 始终连接 Gateway，不直接连接业务 Server。Gateway 负责 API Key、ACL、限流、路由和审计；Server 不得以此为由省略本地业务校验。

能力如何设计见 Tools、Resources 与 Prompts。

5. 上线前验收

服务自注册成功，实例和五类 manifest 在 etcd 中都绑定同一个有效 lease。
管理平台显示 Server 和能力；新增或风险变化完成 Review。
Gateway scoped endpoint 的 initialize、tools/list、tools/call 可用；有 Resource/Prompt 时验证其 list/read/get。
错误 Token 返回 401；无权限 API Key、限流和上游错误产生审计。
非 Gateway 网络来源无法访问 /mcp，且生产环境使用独立 Secret、namespace 和 endpoint。

详细的页面与静态构建验收步骤见仓库中的 mcp-docs/docs/手动测试-服务接入文档.md。