用途:用于构建、接入或调试 MCP(Model Context Protocol)服务器,使 Claude 能访问其原本不了解的系统,例如数据库、内部 API 或运维工具。核心难点在于设计:暴露哪些工具、返回什么内容。
架构选择:本地 stdio 方式运行在用户机器上,由客户端启动,凭证取自本地环境,适合开发工具及访问 localhost 或本地数据库,仅该机器可用。远程 HTTP 方式一次部署、通过 URL 访问、用 OAuth 识别身份,适合同一团队共用或数据位于服务端,部署后所有人立即获得更新。若使用人数超过一个,应直接构建远程版。
工具设计要点:工具是给模型用的接口,不是 REST API。应命名任务而非端点,例如用 get_pipeline_board 取代 query_deals 加 query_stages 加 query_owners。一次调用应回答一个真实问题;若每次都要按相同顺序调用三次,应合并为一个工具。描述本身就是提示词,需说明用途、何时使用及不做什么。返回结果应紧凑、接近散文,去除空值和内部 id,避免大块 JSON 占用上下文。要分页并设默认上限,说明结果被截断及获取剩余内容的方法。读写分离,写操作使用明确、窄接口的工具,不要通用执行入口。错误信息应给出下一步建议。十个设计良好的工具胜过五十个薄封装。
最小可用服务器示例使用 @modelcontextprotocol/sdk,通过 McpServer 与 StdioServerTransport 注册工具并连接;写更多代码前需核对 SDK 当前 API,因其接口在不同版本间有变化。
安全:凭证最小权限;不要把模型提供的原始查询字符串直接传给数据库,应参数化、允许列表并做租户隔离;每个请求按已认证用户限定范围;不要记录或返回秘密;对写操作限流。
调试命令:npx @modelcontextprotocol/inspector node build/index.js、claude mcp list、claude mcp get <name>。工具在客户端缺失通常源于服务器启动崩溃、stdio 服务器向 stdout 写入 console.log 破坏协议流、配置指向过期构建或客户端未重启;stdio 服务器的日志必须全部写入 stderr。
发布清单:每个工具描述写明何时用与不用;通过 inspector 测试而非仅客户端;结果有上限并说明截断;错误给出后续建议;凭证来自环境变量而非仓库;README 包含安装、配置片段及每个工具一个示例提示。
限制:资料未提供具体收费、价格或平台支持范围,暂未提供。