mcp-expert

MCP Expert

概述

构建和管理 Model Context Protocol 生态系统的权威资源。涵盖完整生命周期，从服务端开发和传输配置，到安全性、用户输入征询和异步任务执行。设计以 Agent 为先的工具接口，最大限度减少 token 用量并提高大模型准确性。

适用场景： 构建 MCP 服务、设计工具接口、配置传输方式（Stdio/Streamable HTTP）、实现 OAuth 2.1、排查连接问题，以及使用用户输入征询实现由服务端发起的用户交互。

不适用场景： 应用层业务逻辑、非 MCP API 设计、前端 UI 组件，以及与 MCP 无关的通用 HTTP API 开发。

快速参考

模式	API/方法	要点
以结果为导向的工具	单次调用操作	避免繁琐的多步骤 API
参数扁平化	带描述的扁平 Zod 模式	减少模型幻觉
渐进式披露	为大型数据返回 mcp:// URI	Agent 通过 resources/read 部分读取
可重试工具	返回 retry_with 建议	帮助大模型在输入不正确时自行纠正
有帮助的错误	提供修复指导的描述性字符串	绝不返回原始异常或堆栈跟踪
分页	has_more + next_cursor 元数据	每次调用最多返回 20-50 条记录
结构化输出	在 outputSchema 中使用 JSON Schema	为程序化使用提供类型化工具结果
Stdio 传输	本地工具，仅向 stderr 写入日志	除 JSON-RPC 外，绝不向 stdout 写入内容
Streamable HTTP	远程/云端工具，单一端点	替代已弃用的 SSE 传输
使用 PKCE 的 OAuth 2.1	企业数据访问	MCP 服务是资源服务端，而非认证服务端
用户输入征询	由服务端发起的用户输入	扁平模式映射到表单，包含三种响应状态
异步任务	tasks/get、tasks/cancel	长时间运行的操作返回任务句柄
能力范围	read:docs、write:code、admin:users	细粒度权限边界
HITL 门控	confirmation_required 标志	对破坏性操作进行人工审批
URL 用户输入征询	安全凭据收集	将用户重定向到浏览器，以输入敏感信息
扩展	带命名空间的能力协商	无需分叉规范即可支持可选功能
带工具的采样	由服务端发起的大模型请求	支持服务端 Agent 循环
MCP Inspector	npx @modelcontextprotocol/inspector	无需大模型即可交互式测试工具
单元测试	InMemoryTransport + Vitest	使用模拟客户端测试工具处理程序
评估框架	模式、错误、分页断言	验证工具对大模型的适用质量
工具契约测试	模式字段描述、边界情况	描述每个字段，并处理可选参数
CI 冒烟测试	GitHub Actions + Inspector CLI	自动执行构建、测试和传输健康检查

规范版本

当前 MCP 规范为 2025-11-25。重要里程碑：

• 2025-03-26：Streamable HTTP 传输（弃用独立 SSE）、工具注释
• 2025-06-18：结构化工具输出、引导式输入、OAuth 授权服务器分离
• 2025-11-25：异步任务、扩展框架、带工具的采样、CIMD 授权、服务发现

入门流程

当 Agent 需要新能力时：

1. 验证：检查所需的 MCP 服务是否已处于活动状态
2. 引导：如果缺少，则向用户提供直接的安装途径
3. 配置：尽可能使用 uvx 或 npx 实现零安装执行

常见错误

错误	正确做法
设计需要多次往返、交互繁琐的 API	构建以结果为导向的工具，一次调用即可完成任务
向 stdout 写入日志，导致 Stdio 传输中断	仅向 stderr 写入日志，以保持传输通道畅通
向大模型返回原始异常和堆栈跟踪	返回实用的错误消息，并附上建议的修正方法
构建包含数十种工具的单体服务	将服务的工具数量控制在 5-15 个，便于发现和维护
为新服务使用已弃用的 HTTP+SSE 传输	远程服务使用 Streamable HTTP（单个端点，可选 SSE）
在 MCP 服务配置中硬编码密钥	对所有敏感值使用环境变量映射
在一次工具调用中返回大型数据集	对大型数据使用分页（20-50 条记录）或资源 URI
在 MCP 服务内部实现授权服务器	MCP 服务仅充当 OAuth 2.1 资源服务器，并将授权委托给外部服务
工具描述含糊，导致大模型产生幻觉	在工具描述字段中添加用法示例和严格约束
对长时间运行的操作进行同步阻塞	对耗时超过超时阈值的操作返回异步任务句柄
将收到的令牌传递给上游 API	在本地验证令牌；切勿转发，以避免混淆代理人攻击
通过引导式输入请求密钥	使用 URL 模式的引导式输入或专用 OAuth 流程来收集凭证

MCP 原语

MCP 服务向客户端公开三种核心原语：

• 工具：由模型控制、供大模型调用以完成任务的操作（函数调用）
• 资源：由应用控制，通过 mcp:// URI 暴露、供客户端按需读取的数据
• 提示词：由用户控制的模板，为特定工作流提供结构化上下文

服务会在 initialize 握手期间进行能力协商，并声明其支持的原语。2025 年 11 月的规范将 Tasks 添加为用于异步执行的实验性原语。

传输方式选择

场景	传输方式	说明
本地 CLI 工具	Stdio	启动最快，无网络开销
远程／云端服务	Streamable HTTP	单个端点，可选 SSE 流式传输
旧版远程服务	HTTP+SSE	自 2025-03-26 起已弃用，请迁移至 Streamable HTTP

客户端应尽可能支持 Stdio。Streamable HTTP 通过可选的 Mcp-Session-Id 标头支持无状态和有状态服务实现。

委派

• 发现并审查现有 MCP 服务配置：使用 Explore Agent 检查活跃服务、验证连接，并找出缺失的功能
• 构建并部署经过验证且具备身份验证的新 MCP 服务：使用 Task Agent 搭建服务框架、实现 Zod 验证并配置 OAuth
• 为多 Agent 工作流设计 MCP 生态系统架构：使用 Plan Agent 规划工具边界、传输方式选择和安全范围

参考资料

• 服务端开发、工具设计、参数扁平化、分页和错误处理
• 传输配置：Stdio、Streamable HTTP，以及从 SSE 迁移
• 安全、OAuth 2.1 集成、引导式信息收集、能力范围和 HITL 门控
• 测试与评估：MCP Inspector、单元测试、契约测试、CI 集成
• 故障排除指南、MCP Inspector、常见错误和传输调试