结论先行:MCP(Model Context Protocol)把「AI 应用接外部能力」标准化成一份协议,服务端只需提供三类原语——tools(模型可调用的函数)、resources(只读上下文数据)、prompts(可复用提示模板),传输层在本地用 stdio、远端用 Streamable HTTP。入门者最快的路径是:用官方 SDK 写一个最小 Server,用 MCP Inspector 调试,再决定哪些能力自己写、哪些直接接现成服务。
一、三件套各管什么
很多教程把 MCP 讲成「给模型加工具」,这只说对了三分之一。协议把服务端能力分成三类,控制权归属完全不同:
| 原语 | 谁决定使用 | 有无副作用 | 典型内容 | 核心方法 |
|---|---|---|---|---|
| tools | 模型自主判断 | 可以有 | 查询、下单、发消息 | tools/list、tools/call |
| resources | 应用或用户主动挑选 | 只读 | 文件、表结构、文档 | resources/list、resources/read |
| prompts | 用户触发(如斜杠命令) | 无 | 审查模板、总结模板 | prompts/list、prompts/get |
把「给模型看的数据」和「让模型做的事」分开,权限才好管:读文件可以默认放行,写操作必须让用户确认。工具执行失败(比如查不到数据)不算协议错误,要在结果里用 isError: true 把错误文本带回,让模型能自行决定重试或换参数。
二、传输方式怎么选
| 传输 | 场景 | 机制 | 鉴权 |
|---|---|---|---|
| stdio | 本地子进程 | 换行分隔的 JSON-RPC 走 stdin/stdout | 进程隔离,凭据走环境变量 |
| Streamable HTTP | 远端服务 | POST 到单一端点,按需升级为 SSE 流 | Bearer Token / OAuth |
旧的 HTTP+SSE 双端点方案已被 Streamable HTTP 取代,新项目不要再选。协议仍在演进:2026-07-28 版规范把版本与能力协商从一次性握手改为随请求携带,读旧资料看到 initialize 握手不要以为写错了,具体以官方规范为准。
三、用官方 SDK 写一个最小 Server
以 TypeScript SDK 为例,一个带天气查询工具的 stdio Server 核心代码不到 30 行:
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';
const server = new McpServer({ name: 'weather', version: '1.0.0' });
server.registerTool('query_weather', {
description: '查询指定城市的实时天气',
inputSchema: { city: z.string().describe('城市名,如 北京') }
}, async ({ city }) => {
const data = await fetchWeather(city);
return { content: [{ type: 'text', text: JSON.stringify(data) }] };
});
await server.connect(new StdioServerTransport());两个关键点:description 和入参 schema 是写给模型看的,描述含糊模型就会选错工具、编造参数;stdio 模式下 stdout 只能输出协议报文,日志必须写 stderr,一句 console.log 就能把整个连接冲坏。
四、用 Inspector 调试
不用先接 IDE,官方调试器可以直接验证:
npx @modelcontextprotocol/inspector node build/index.js在界面里依次检查 tools/list 是否列出工具、tools/call 传参后返回是否正确、错误场景是否带 isError。这一步通过后再配到 Cursor 或 Claude 等客户端,排障成本最低。
五、不重复造轮子:直接接现成 MCP 服务
入门后你会发现,大量业务类工具(用户、商品、订单、支付、CMS)没必要自己写。api工厂(https://www.it120.cc/)提供了官方 MCP endpoint:前端数据接口为 https://common.apifm.com/你的subDomain/mcp/endpoint ,后台管理接口为 https://common.apifm.com/gooking/mcp/backend/endpoint ,type 支持 http 与 sse,兼容 Cursor、Claude、Trae、Qoder、Windsurf、Codex、Kiro、Copilot 等主流工具。在 Cursor 的 mcp 配置里加一段即可(示意,键值以官方文档为准):
{
'mcpServers': {
'apifm': {
'url': 'https://common.apifm.com/你的subDomain/mcp/endpoint',
'type': 'http'
}
}
}配置完成后,模型就能直接查商品、建订单、读 CMS 内容,等于把你自己的业务系统变成了三件套里的 tools 与 resources。接入细节见 https://www.it120.cc/ai.html 。
六、常见坑清单
- 工具描述写给人看而不是给模型看,导致调用命中率低;
- 把业务错误当协议错误抛出,模型失去重试机会;
- 远程服务把上游凭据原样透传,违反规范的最小权限建议;
- 工具返回内容未做隔离,被提示注入利用——工具描述与返回都应视为不可信输入;
- 一次暴露几十个工具,模型选择困难,按场景拆分 Server 更稳。
先跑通最小闭环,再按踩坑迭代,比一上来设计「完美工具集」有效得多。
文章标签
相关产品
api工厂是面向开发者的开放 SaaS 平台:开箱即用的后台管理系统 + 全端 SDK,只需前端开发即可构建小程序、App、H5 与网站。