跳到主要内容
api工厂
AI 开发

MCP Server 开发入门:tools/resources/prompts 三件套与传输方式

api工厂资讯栏目 约 6 分钟阅读
本文由 AI 辅助生成,内容基于公开资讯整理改写,技术细节以官方文档为准。

结论先行: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 行:

typescript
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,官方调试器可以直接验证:

bash
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 配置里加一段即可(示意,键值以官方文档为准):

json
{
  'mcpServers': {
    'apifm': {
      'url': 'https://common.apifm.com/你的subDomain/mcp/endpoint',
      'type': 'http'
    }
  }
}

配置完成后,模型就能直接查商品、建订单、读 CMS 内容,等于把你自己的业务系统变成了三件套里的 tools 与 resources。接入细节见 https://www.it120.cc/ai.html 。

六、常见坑清单

  • 工具描述写给人看而不是给模型看,导致调用命中率低;
  • 把业务错误当协议错误抛出,模型失去重试机会;
  • 远程服务把上游凭据原样透传,违反规范的最小权限建议;
  • 工具返回内容未做隔离,被提示注入利用——工具描述与返回都应视为不可信输入;
  • 一次暴露几十个工具,模型选择困难,按场景拆分 Server 更稳。

先跑通最小闭环,再按踩坑迭代,比一上来设计「完美工具集」有效得多。

文章标签

MCPAI开发协议工具集成

相关产品

api工厂是面向开发者的开放 SaaS 平台:开箱即用的后台管理系统 + 全端 SDK,只需前端开发即可构建小程序、App、H5 与网站。

WebGPU端侧AI浏览器

浏览器端 AI:WebGPU 与端侧小模型的能与不能

WebGPU 让浏览器跑量化小模型成为生产选项,价值在隐私、离线与零延迟,约束在尺寸、质量与首次下载。本文客观盘点支持现状,给出检测回退代码与端云协同架构。

AI 开发约 5 分钟阅读