MCP 接入实践

选择入口

AutoBridge 把既有 Gateway/OpenAPI 方法变成 MCP Tool；原生 MCP 用于手动定义 Tool、Resource 或 Prompt。当前实现不是 LLM Client 或 Agent 编排框架。

aiconnector:
  enable: true
  mcp_server:
    enable: true
    path: /mcp
    transport: streamable_http
    allowed_tags:
      - mcp

配置详见智能连接。默认端点挂在已有 HTTP listener 上，需配置 services.http_address。

自动桥接的前提

启用 services.integrations.grpc.admin，保证框架可取得业务 Gateway/OpenAPI 元数据。在业务方法的 OpenAPI 配置中声明 mcp tag 并重新生成；标签规则以项目现有配置格式为准。

allowed_tags 为 OR 匹配，只控制 AutoBridge；不匹配或没有 tag 的方法不自动暴露。Admin 未启用时 AutoBridge 跳过，原生资源仍可注册。AutoBridge 在 HTTPHandlerFrontend 中同步执行，不要求启用静态前端页面。

调用链是 MCP → 本机 HTTP Gateway → 本机 gRPC → 业务 handler。授权 Header 会向后传递，最终 RPC 策略仍需正确配置。应实测 token、deadline、错误映射与调用成本，不把 HTTP Gateway 转换当作进程内函数调用。

原生资源

在 handler/private.go 的 privateMCPHandle 中获取 m.baseCfg.MCPServerInstance()；未开启时返回 nil。该 hook 位于 AutoBridge 完成后、服务监听启动前。沿用模板 Registrar 与 option 注入模式，避免修改托管的 register.go。

原生资源不受 allowed_tags 约束。入口认证不能代替对象级权限检查；自定义工具应校验身份、角色、资源归属，记录审计，并对写入操作明确幂等性和确认语义。不要把原始 Authorization Header 当作已验证用户声明。

验收顺序

1. 使用符合所选 transport 的 MCP 客户端完成 initialize 与资源/工具列表查询；普通 curl GET 不能代表协议握手成功。
2. 检查默认白名单只暴露预期方法，自定义资源有明确清单。
3. 分别测试无凭据、无效 token、合法但无权限用户、允许用户；确认拒绝发生在业务操作之前。
4. 测试服务未就绪、Gateway 失败、业务超时和取消，核对 MCP 返回与审计记录。
5. 对有副作用的工具测试重复调用、权限变更和失败恢复。

当前支持 streamable_http 与 sse；使用 SSE 时按实际服务器路由和客户端能力配置，不混用两种传输。本轮未进行 MCP 客户端联调。

来源：MCP 装配与 AutoBridge、业务扩展模板。