MCP 基础

🎯 学习目标

• 说明 MCP 解决的是「工具集成碎片化」而非「模型能力」问题
• 区分 MCP Server、Client 与 Host 的职责
• 理解 stdio 与 HTTP/SSE 两种传输的典型使用场景
• 能列举 Tools、Resources、Prompts 各自适合暴露什么能力

引言

每接一个数据源就写一套适配层，是 AI 应用集成里的老痛点。MCP（Model Context Protocol）用开放协议统一「客户端如何发现与调用外部能力」。本节建立协议层直觉，下一节再谈多 Server 编排。

章节正文

第 1 步：MCP 在架构中的位置

典型分层：

用户 → Host（Cursor / Claude Desktop / 自研 App）
         → MCP Client（协议客户端）
            → MCP Server A（Git）
            → MCP Server B（Postgres）
         → LLM API（Function Calling / Tool Use）

MCP Server 不替代 LLM；它把「读仓库、查库、跑脚本」封装成标准原语。Host 负责把 MCP 能力映射成模型所需的 tools 定义，并执行策略（权限、确认）。

第 2 步：JSON-RPC 2.0 与 stdio 传输

MCP 消息基于 JSON-RPC 2.0。本地开发最常见的是 stdio：Client 启动 Server 子进程，经 stdin/stdout 交换 JSON 行。

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} }

响应携带 tools 数组，每项含 name、description、inputSchema。

远程场景可用 HTTP + SSE 传输，便于团队共享同一 Server 实例。选型原则：IDE 插件优先 stdio；多租户 SaaS 优先 HTTP。

第 3 步：三大原语：Tools、Resources、Prompts

原语	典型用途	是否「执行」
Tools	查 API、写文件、跑命令	有副作用或计算
Resources	规范文档、OpenAPI、配置片段	只读上下文
Prompts	代码审查清单、报告模板	参数化模板

示例：

• Tool：run_sql_query — 需严格权限
• Resource：file://docs/api-spec.md — 注入上下文
• Prompt：security-audit — 一键加载审计指令模板

不要把只读大文档塞进 Tool；Resource 更适合静态上下文供给。

第 4 步：用 SDK 启动最小 Server（概念 walkthrough）

TypeScript SDK 典型结构：

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'

const server = new McpServer({ name: 'demo', version: '1.0.0' })

server.tool('echo', '回显输入文本', { text: { type: 'string' } }, async ({ text }) => ({
  content: [{ type: 'text', text: `Echo: ${text}` }],
}))

const transport = new StdioServerTransport()
await server.connect(transport)

开发时用 npx @modelcontextprotocol/inspector 连接 Server，验证 tools/list 与 tools/call 是否符合预期。

第 5 步：与 Function Calling 的衔接

Host 侧流程：

1. tools/list 拉取 MCP 工具元数据
2. 转成 OpenAI tools 数组（name、description、parameters）
3. 模型返回 tool_calls 后，Host 调用 MCP tools/call
4. 将返回 content 转为 tool 消息

MCP 的价值在一次实现、多处接入：同一 Server 可服务 Cursor、Claude Desktop 与自研 Agent，而不必为每个 Host 重写集成。

动手练习

1. 画一张序列图：用户提问 → Host → LLM tool_calls → MCP tools/call → 回传答案，标注 JSON-RPC 方法名。
2. 列举你当前项目里 3 个适合做成 Tool 的操作、2 个适合做成 Resource 的只读数据。
3. 查阅 MCP 官方文档，对比 stdio 与 Streamable HTTP transport 的优缺点，写 5 条笔记。
4. 用 Inspector 或等价方式连接一个官方示例 Server，截图或记录 tools/list 返回结构。
5. 思考：为何 Prompts 原语适合「可复用审查模板」，而不适合替代 System Prompt 版本管理？写简短结论。

常见问题

Q：MCP 和 OpenAPI 有什么区别？

OpenAPI 描述 HTTP API 的形状；MCP 描述 AI Host 如何发现与调用能力（含 Resources/Prompts、生命周期、传输）。OpenAPI 可作为一种 Resource 挂到 MCP Server 上，供模型理解 API，但二者层次不同。

Q：每个工具都要单独起一个 MCP Server 吗？

不必。一个 Server 可注册多个 Tool。按领域边界拆分更常见：如 repo-server、db-server。过细拆分增加连接管理成本；过粗则权限难以最小化。

Q：MCP Server 崩溃会影响对话吗？

会影响依赖该 Server 的工具调用。Host 应捕获连接错误，向模型回传结构化失败，并支持降级（跳过该工具或提示用户）。生产环境需健康检查与进程守护。

本节小结

MCP 是工具服务的「USB 接口」：stdio/HTTP 传 JSON-RPC，Tools 执行、Resources 供给上下文、Prompts 复用模板。Host 负责映射到模型 API 并施加安全策略。