MCP 服务与注册表:带治理的工具协议

MCP 服务与注册表:带治理的工具协议

本节摘要:模型上下文协议(MCP)在 2026 年不再是未来,而成了默认的工具使用规范。Anthropic、OpenAI、Google 与每个主流 IDE 都内置了 MCP 客户端。Pinterest 公开了内部 MCP 服务生态,AAIF Registry 在 .well-known 上形式化了能力元数据,AWS ECS 发布了无状态参考部署。2026 的生产形态是:StreamableHTTP 传输、OAuth 2.1 范围、OPA 策略门控、一个让平台团队发现/验证/启用服务的注册表。本节要求你端到端构建这套东西。你会学到 StreamableHTTP 的无状态水平扩展、按工具的范围检查、破坏性工具的 Slack 审批门,以及只追加审计。

对应原课程:Phase 19 · Lesson 13 · mcp-server-with-registry(原英文 phases/19-capstone-projects/13-mcp-server-with-registry/docs/en.md)。

学习目标

阅读完本节,你应当能够:

1. 用 FastMCP 暴露 10 个内部工具(Postgres 只读、S3 列举、Jira、Linear、Datadog 等),配类型 schema 与范围标签。
2. 配 StreamableHTTP 无状态传输,在负载均衡后水平扩展。
3. 用 OAuth 2.1 在工具调用时(而非仅会话开始)检查按工具范围。
4. 用 OPA/Rego 给每工具写策略(范围/PII 脱敏/负载上限),每请求一次决策。
5. 把破坏性工具放到独立 MCP 服务,要求 Slack 审批拿到的 approved:by:human 短时范围。
6. 构建注册表服务,轮询各服务器的 .well-known/mcp-capabilities,提供发现/验证/启停 UI。

一、问题与直觉

MCP 成了工具使用的通用语。Claude Code、Cursor 3、Amp、OpenCode、Gemini CLI 与每个托管 Agent 现在都消费 MCP 服务。生产挑战不在写服务(FastMCP 让这很容易),而在带着企业需求规模部署:每租户 OAuth 范围、破坏性工具的 OPA 策略、StreamableHTTP 无状态扩展、用于发现的注册表、每次工具调用的审计日志。Pinterest 的内部 MCP 生态与 AAIF Registry 规范设了 2026 的标杆。

你要构建一个暴露 10 个内部工具的 MCP 服务、一个供平台发现的注册表 UI、一个破坏性工具的人工审批门。负载测试演示 StreamableHTTP 水平扩展。审计轨迹满足企业安全评审。

二、从零实现

MCP 2026 修订强制 StreamableHTTP 为默认传输。不同于早期的 stdio + SSE 形态,StreamableHTTP 默认无状态:单个 HTTP 端点接受 JSON-RPC 请求、流式响应、支持长连接做通知。无状态意味着在负载均衡后可水平扩展。

授权是 OAuth 2.1 配按工具范围。一个 token 带范围如 jira:read、s3:list、postgres:query:readonly。MCP 服务在工具调用时检查范围,不只看会话开始。对高风险工具,服务拒绝任何范围未在最近 N 分钟内升级到 approved:by:human 的调用——这个升级来自一张 Slack 审批卡。

破坏性工具的范围提升:

def authorize_destructive(token, tool):
    if "approved:by:human" not in token.scopes:
        raise NeedApproval(tool)              # 发 Slack 卡
    if token.elevated_at < now() - 15*MIN:
        raise NeedApproval(tool)              # 升级过期,重新审批
    return True
​

注册表是独立服务。每个 MCP 服务暴露一个 .well-known/mcp-capabilities 文档,含工具清单、传输 URL、授权要求。注册表轮询、验证、索引。平台团队用注册表 UI 看哪些工具可用、需要什么范围、归属哪个团队。

三、架构与技术栈

• 服务框架:FastMCP(Python)或 @modelcontextprotocol/sdk(TypeScript)。
• 传输:StreamableHTTP over HTTPS(无状态)。
• 授权:OAuth 2.1,经 SPIFFE/SPIRE 的负载身份。
• 策略:OPA/Rego 每工具规则;每请求一个策略决策服务。
• 注册表:自建,消费 .well-known/mcp-capabilities 清单。
• 人工审批:破坏性工具用 Slack 交互消息。
• 部署:AWS ECS Fargate 或 Fly.io,每租户一服务或共享配租户范围。
• 审计:按租户的结构化 JSONL,带每次调用血缘。

四、可复用产物

outputs/skill-mcp-server.md 描述交付物:一个生产级 MCP 服务 + 注册表 + 审计层,带 OAuth 2.1 范围与 OPA 门控。评分量表:

一次典型调用:

$ curl -H "Authorization: Bearer eyJhbGc..." \
       -X POST https://mcp.internal.example.com/ \
       -d '{"jsonrpc":"2.0","method":"tools/call",
            "params":{"name":"postgres.readonly","arguments":{"sql":"SELECT 1"}}}'
[registry]   capability validated: postgres.readonly v1.2
[policy]    scope postgres:query:readonly present; allowed
[audit]     logged: user=u42 tool=postgres.readonly outcome=ok
response:    { "result": { "rows": [[1]] } }
​

五、框架对比

FastMCP 是 Python 服务框架参考,装饰器风格最简洁;@modelcontextprotocol/sdk 是 TS 官方 SDK。传输侧,StreamableHTTP 的无状态是 2026 的关键升级——它取代了 stdio(本地)与 SSE(有状态、难扩展),让 MCP 服务能像普通 HTTP 服务一样水平扩展。治理侧,OPA/Rego 是策略引擎标准,把「范围/脱敏/上限」从代码里抽到声明式规则。本节的差异化在「注册表 + 治理」——光把工具暴露出来不够,平台团队需要发现、验证、启停、归属,这正是 AAIF Registry 规范要解决的。

六、练习

1. 加新工具:加一个 Confluence 搜索工具,经注册表验证流程上线,不动核心服务。
2. OPA 脱敏:写一个 OPA 策略,脱敏 Postgres 查询结果中名为 email/ssn/phone 的列,用探测查询验证。
3. 传输基准:基准测试 StreamableHTTP vs stdio 的本地延迟,报告单调用 p50/p95。
4. 按租户配额:实现按租户配额——每租户每工具每分钟最多 N 次调用,用第二个 OPA 规则强制。
5. 一致性套件:跑官方 MCP 一致性套件,修掉每个失败。

本节要点回顾

1. MCP 是 2026 默认工具规范:StreamableHTTP 无状态传输,OAuth 2.1 范围,OPA 门控。
2. 范围按调用检查:不只看会话开始,每工具调用时强制范围。
3. 破坏性工具分离:独立 MCP 服务 + approved:by:human 短时范围(Slack 审批,15 分钟过期)。
4. 注册表发现:每服务暴露 .well-known/mcp-capabilities,注册表轮询/验证/索引。
5. 只追加审计:按租户 JSONL,Presidio 脱敏后写,带每次调用血缘。
6. 无状态水平扩展:StreamableHTTP 在负载均衡后扩展,负载测试演示。

下一节,我们进入「推理服务」——构建一个用投机解码把吞吐推到 2.5 倍以上的推理服务器。