MCP实战指南：从0到1为你的AI应用接入工具生态

你在 Claude Desktop 里让它查内部工单系统，它说不知道；在 Cursor 里让它读本地 SQLite，你得写一个插件；明天换到通义灵码，又得重写一遍。MCP（Model Context Protocol）解决的就是这类重复适配：工具端按一套协议暴露能力，客户端按同一套协议调用。协议开源，Anthropic 在 2024 年 11 月发布，截至 2026 年已有 Python、TypeScript、Java、Kotlin、C# 等 SDK。

1. MCP 为什么像 USB-C

以前 3 个 AI 客户端接 5 个工具，要写 15 个适配器。客户端实现 MCP Client，工具实现 MCP Server 后，连接数变成 3+5。USB-C 的类比来自这里：接口统一，插拔对象从“某家 AI 的插件”变成“按 MCP 说话的 Server”。

MCP 目前覆盖三类能力：

• tools：模型可调用的函数，比如 query_order、create_ticket。
• resources：只读数据，比如本地文件、数据库表、日志片段。
• prompts：预置提示词模板，用户手动选择后填入客户端。

2. Host、Client、Server 与 JSON-RPC 通信

Host 是用户直接操作的 AI 应用。Client 由 Host 创建，通常一个 Server 对应一个 Client 连接。Server 是独立进程或 HTTP 服务，负责执行工具、读资源。

通信走 JSON-RPC 2.0。常见传输有两种：

• 客户端发 initialize，双方交换协议版本和能力。
• 客户端发 initialized 通知。
• 客户端拉 tools/list，拿到工具名、描述、JSON Schema。
• 模型决定调用工具，客户端发 tools/call，参数按 Schema 校验。
• Server 返回 content 数组；执行失败时用 isError: true 标记。

3. 用 Python 写一个最小 MCP Server

环境：Python 3.10+，安装 SDK：

pip install "mcp[cli]"

新建 server.py：

from mcp.server.fastmcp import FastMCP
mcp = FastMCP("demo-tools")
@mcp.tool()
def add(a: int, b: int) -> int:
    """返回两个整数之和。"""
    return a + b
@mcp.tool()
def search_orders(user_id: str, limit: int = 10) -> str:
    """按用户 ID 查询最近订单。limit 默认 10，最大 50。"""
    limit = min(limit, 50)
    orders = [{"id": "A1001", "amount": 99.0}]
    return str(orders[:limit])
if __name__ == "__main__":
    mcp.run()

工具函数的 docstring 会变成工具描述。模型靠这段文字判断什么时候调用、参数怎么填。写“查询订单”不如写“按用户 ID 查询最近订单，limit 最大 50”有用。

调试用 MCP Inspector：

npx @modelcontextprotocol/inspector python /absolute/path/to/server.py

在 Inspector 里点 tools/list，再调 tools/call。能跑通再挂到客户端，省得在 Claude 日志里猜。

4. TypeScript 版本，适合已有 Node 服务

初始化项目：

npm init -y
npm i @modelcontextprotocol/sdk zod
npm i -D typescript tsx

package.json 加一行 "type": "module"。新建 server.ts：

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: "demo-tools",
  version: "1.0.0",
});
server.tool(
  "add",
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }],
  })
);
const transport = new StdioServerTransport();
await server.connect(transport);

运行：

npx tsx server.ts

TypeScript SDK 的 zod Schema 会转成 JSON Schema 发给客户端。参数校验失败时，SDK 会返回 JSON-RPC 错误，不需要自己在每个工具里写一遍类型检查。

5. 挂到 Claude Desktop、Cursor、通义灵码

Claude Desktop

配置文件位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "demo-tools": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"],
      "env": {
        "ORDER_API_KEY": "你的key"
      }
    }
  }
}

路径用绝对路径。Windows 上 python 不在 PATH 时，写完整路径，比如 C:\\Python312\\python.exe。改完重启 Claude Desktop。工具图标出现在输入框附近，没有出现就查 Claude 日志目录下的 mcp*.log，里面会记录子进程 stderr。

Cursor

Cursor 支持全局配置和项目配置：

• 全局：~/.cursor/mcp.json
• 项目：项目根目录 .cursor/mcp.json

通义灵码与百炼 MCP

通义灵码在插件设置里提供 MCP 入口，不同版本菜单名可能不同，直接在设置里搜“MCP”。配置项通常也是 command、args、url、headers 这几类。如果你的插件版本没有 MCP 菜单，升级插件，或改用阿里云百炼控制台的 MCP 市场。

百炼控制台创建 MCP 服务后，会给你一个 Streamable HTTP 地址。客户端里用 url 接入：

{
  "mcpServers": {
    "bailian-demo": {
      "url": "<百炼控制台复制的URL>",
      "headers": {
        "Authorization": "Bearer <API_KEY>"
      }
    }
  }
}

远程 Server 的鉴权按服务说明来。把 API Key 放进客户端配置后，注意配置文件权限，别提交到 Git。

6. 云厂商 MCP 市场怎么选

2025 年起，阿里云百炼、腾讯云 MCP 广场、火山引擎扣子、百度千帆都上线了 MCP 相关市场或托管能力。它们卖的不是 MCP 协议本身，而是已经接好的工具后端、鉴权和运维。

• 工具后面是不是敏感数据？涉及内部工单、客户信息时，本地 stdio Server 更容易控制数据边界。
• 调用量是否稳定？低频试用可以用市场，高频最好自己部署 Server，避免被限流。
• 团队能不能维护进程？如果没人管 Python/Node 进程，托管市场的 HTTP 端点更省事。

7. 三个常见坑：鉴权、上下文膨胀、错误重试

鉴权：别把 Key 写进代码

stdio Server 的密钥用环境变量传。Claude Desktop 和 Cursor 的配置都有 env 字段，Server 里用 os.environ["ORDER_API_KEY"] 读取。HTTP Server 至少校验 Authorization 头，并把权限拆到工具级别：查订单和退款不要共用一个全权限 Key。

OAuth 2.1 在 MCP 的 HTTP 传输里有支持，适合面向多用户的远程 Server。内部工具用静态 Bearer Token 也能跑，但记得轮换和审计。

上下文膨胀：工具不是越多越好

tools/list 返回的每个工具都带名称、描述和 JSON Schema，这些会进模型上下文。一个 Server 挂 50 个工具，模型选错概率上升，token 也涨。处理方式：

• 按业务域拆 Server：文件、数据库、工单各一个，客户端只挂当前要用的。
• 合并细碎工具：query_user、query_user_orders、query_user_tickets 可以合成一个带 resource 参数的 query。
• 限制返回大小：列表接口默认 10 条，最大 50 条，超出截断并返回分页游标。
• 返回结构化内容：优先返回 JSON 字段，少返回带大量修饰的 Markdown。

错误重试：先分清能不能重试

网络超时、429 限流可以重试；参数错误、权限不足、资源不存在重试多少次都一样。Server 返回错误时，用 isError: true 加一段人可读的信息，不要把 Python 堆栈直接丢给模型。

客户端侧做重试时，指数退避加随机抖动，设置最大次数。写操作带幂等键，比如 request_id，避免重试两次创建两张工单。给每个工具设超时，长任务返回任务 ID，让模型轮询状态，别让一次 tools/call 卡五分钟。

8. MCP 和 Agent 生态会怎么接

MCP 管工具接入，Agent 框架管规划、记忆和多步执行。LangGraph、AutoGen、OpenAI Agents SDK 这类框架可以调用 MCP Client，把 MCP Server 当成工具来源。2025 年 Google 发布的 A2A 协议解决 Agent 之间的通信，和 MCP 的位置不同：一个连工具，一个连 Agent。

2026 年能落地的方向有几个：

• 企业内网 MCP 网关：统一鉴权、审计、限流，Agent 只能看到被授权的工具。
• MCP Server 托管：云厂商把数据库、支付、地图封装成 HTTP 端点，按调用量计费。
• 工具权限模型：读、写、退款等敏感操作分级，需要人工确认的步骤用 prompts 或客户端审批。

参考：

• MCP 官方文档：https://modelcontextprotocol.io
• MCP 规范：https://spec.modelcontextprotocol.io
• 官方 Server 仓库：https://github.com/modelcontextprotocol/servers