适用场景与目标

MCP（Model Context Protocol） 是 Anthropic 于 2024 年底开源的 Agent 工具调用协议，旨在解决”大模型如何可靠地调用外部工具和数据”的问题。2026年4月，Pinterest 宣布在生产环境大规模落地 MCP 生态系统，标志着 MCP 从实验走向企业级可用。

MCP 解决的核心问题：

• AI Agent 与企业内部工具（数据库、GitHub、JIRA、Slack）的连接标准化
• 工具描述统一、调用安全、结果可溯源
• 多 Agent 之间共享上下文和工具资源

适用场景：

• 需要让 AI Agent 操作真实业务系统（查库存、读文件、调用内部 API）
• 多工具、多数据源集成的 AI 应用开发
• 企业内部 AI 助手（类 Copilot）扩展到更多业务系统
• 构建多 Agent 协作工作流

目标： 本篇带你从零搭建一个最小可用 MCP Server，并让 Claude Code/Cursor 通过 MCP 协议连接真实工具链，完成一个端到端演示。

---

最小可行方案（MVP）步骤

环境准备

# Node.js ≥ 18
node --version  # ≥ 18.0.0

# Python ≥ 3.10（用于写 MCP Server）
python3 --version  # ≥ 3.10

# MCP SDK
npm install -g @modelcontextprotocol/sdk
pip install mcp

Step 1：用 Node.js 快速编写一个 MCP Server

MCP 的核心是”Server 暴露工具，Client 调用工具”。我们先写一个最简单的文件管理 MCP Server：

// file-mcp-server.mjs
import { MCPServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { readFile, writeFile, readdir } from "fs/promises";
import { join } from "path";

const server = new MCPServer({
  name: "file-manager",
  version: "1.0.0",
  tools: {
    read_file: {
      description: "读取文件内容",
      input: {
        type: "object",
        properties: {
          path: { type: "string", description: "文件路径" }
        },
        required: ["path"]
      },
      handler: async ({ path }) => {
        const content = await readFile(path, "utf-8");
        return { content };
      }
    },
    list_dir: {
      description: "列出目录内容",
      input: {
        type: "object",
        properties: {
          path: { type: "string", description: "目录路径" }
        },
        required: ["path"]
      },
      handler: async ({ path }) => {
        const entries = await readdir(path);
        return { entries };
      }
    }
  }
});

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

Step 2：在 Claude Code 中接入 MCP

Claude Code 通过 claude_code_config.json 配置 MCP Server：

# 查看 Claude Code 配置路径
claude code --version

# 在项目根目录创建配置
cat > .mcp.json << 'EOF'
{
  "mcpServers": {
    "file-manager": {
      "command": "node",
      "args": ["/path/to/file-mcp-server.mjs"],
      "env": {}
    }
  }
}
EOF

⚠️ 注意：Claude Code 的 MCP 配置位置因版本而异，v0.x 在 ~/.claude/ 目录，v1.x 使用项目级 .mcp.json。请运行 claude code --help 确认当前版本配置方式。

Step 3：用 Python 编写一个更实用的 MCP Server（JIRA/Confluence 示例）

# jira_mcp_server.py
from mcp.server import MCPServer
from mcp.types import Tool, CallToolResult
import httpx
import os

JIRA_URL = os.getenv("JIRA_URL", "https://your-org.atlassian.net")
JIRA_TOKEN = os.getenv("JIRA_TOKEN")  # API Token
JIRA_EMAIL = os.getenv("JIRA_EMAIL")

server = MCPServer(name="jira-tools", version="1.0.0")

@server.list_tools()
def list_tools() -> list[Tool]:
    return [
        Tool(
            name="search_jira",
            description="搜索 JIRA Issue",
            input_schema={
                "type": "object",
                "properties": {
                    "jql": {"type": "string", "description": "JQL 查询语句"},
                    "maxResults": {"type": "integer", "default": 10}
                }
            }
        ),
        Tool(
            name="get_issue",
            description="获取单个 JIRA Issue 详情",
            input_schema={
                "type": "object",
                "properties": {
                    "issue_key": {"type": "string"}
                },
                "required": ["issue_key"]
            }
        )
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict) -> CallToolResult:
    headers = {
        "Authorization": f"Basic {JIRA_EMAIL}:{JIRA_TOKEN}",
        "Content-Type": "application/json"
    }
    async with httpx.AsyncClient() as client:
        if name == "search_jira":
            response = await client.get(
                f"{JIRA_URL}/rest/api/3/search",
                params={"jql": arguments["jql"], "maxResults": arguments.get("maxResults", 10)},
                headers=headers
            )
            return CallToolResult(content=str(response.json()))
        elif name == "get_issue":
            response = await client.get(
                f"{JIRA_URL}/rest/api/3/issue/{arguments['issue_key']}",
                headers=headers
            )
            return CallToolResult(content=str(response.json()))
    return CallToolResult(content="Unknown tool")

if __name__ == "__main__":
    import asyncio
    from mcp.server.stdio import StdioServer
    asyncio.run(StdioServer(server).run())

启动并测试：

export JIRA_TOKEN=your_api_token
export JIRA_EMAIL=your_email@example.com
python jira_mcp_server.py

---

关键实现细节

MCP 协议架构

MCP 核心是三层结构：

1. Host（Claude Code / Cursor / 自建应用）：发起工具调用
2. Server：暴露工具集，维护工具 schema
3. Transport：stdio（本地）/ HTTP（SSE，远端）

Host <--(JSON-RPC over stdio/SSE)--> Server <--> 真实系统（DB/API/FS）

让 MCP Server 以 HTTP 方式运行（远端部署）

生产环境中，工具服务器往往需要独立部署。MCP 支持 SSE（Server-Sent Events）传输：

// http-mcp-server.mjs
import { MCPServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";

const transport = new SSEServerTransport("/mcp", res);
server.connect(transport);

工具权限控制

MCP 提供工具级别的权限声明，推荐在 Server 端做细粒度控制：

const server = new MCPServer({
  name: "secure-tools",
  version: "1.0.0",
  tools: {
    delete_file: {
      description: "删除文件（高危操作）",
      inputSchema: { ... },
      annotations: {
        dangerLevel: "high",  // 向 Host 声明危险操作
        requiresApproval: true
      },
      handler: async ({ path }) => { ... }
    }
  }
});

Claude Code 等 Host 会根据 dangerLevel 决定是否自动执行或要求用户确认。

多 Server 并联

在 .mcp.json 中可以同时配置多个 Server，实现工具聚合：

{
  "mcpServers": {
    "file-manager": { "command": "node", "args": ["file-mcp-server.mjs"] },
    "jira-tools": { "command": "python", "args": ["jira_mcp_server.py"] },
    "github-tools": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] }
  }
}

---

常见坑与规避清单

坑	描述	规避方式
stdio 阻塞	stdio 模式下 MCP Server 和 Host 共用 stdin/stdout，任何意外输出都会导致协议解析失败	生产环境换用 SSE/HTTP 传输；调试时加 --verbose
工具 schema 不完整	Claude Code 不会调用它无法理解的工具，schema 缺字段导致工具”看起来注册了但用不了”	严格遵循 JSON Schema；必填字段用 required 声明；加 description
环境变量泄露	MCP Server 进程能看到宿主机的所有环境变量，包括密钥	通过 env 白名单传参，不用全局 process.env；或用 Vault
版本不兼容	MCP SDK 版本更新频繁，0.x 和 1.x 接口差异大	锁定 package.json / requirements.txt 中的 MCP SDK 版本
长连接断连	SSE 远端 MCP Server 超过一定时间无请求会被 Load Balancer 断开	添加心跳/keepalive；Nginx 配置 proxy_read_timeout 300s
工具结果截断	Claude 模型有输出长度限制，超大返回会被截断	在 Server 端做分页；返回摘要而非全文
工具调用死循环	Agent 反复调用同一工具不收敛	在工具 description 中明确”适用条件”；设 maxTokens 或 timeout
路径穿越漏洞	文件操作类工具若不校验路径，可能被用来读敏感文件	使用 path.resolve + 白名单目录，禁止 .. 穿越

---

成本/性能/维护权衡

MCP 部署架构选择

方案	适用规模	延迟	维护成本	安全性
本地 stdio	个人开发、小团队	⭐ 最低	低	低（共享主机环境）
本地 HTTP/SSE	中小团队、预发验证	⭐⭐ 低	中	中
远端托管（SSE）	生产、多租户、企业	⭐⭐⭐ 高	中	⭐⭐⭐ 高（Vault 集成）
云 MCP Gateway	超大规模	取决于网络	低（托管）	高（托管）

成本参考

• 自建 MCP Server（中等规模）： 1 台 2C4G 云主机 ≈ ¥150/月
• MCP Gateway 云服务（如 AWS Bedrock Agent）： 按调用量计费，约 ¥0.002/工具调用
• 维护成本： 每个新增工具需要 0.5PD 更新 Server + schema 文档

性能优化建议

1. 工具结果缓存：相同请求在 5 分钟内直接返回缓存，减少对后端 API 的调用
2. 异步工具：耗时超过 3 秒的工具用 tool_result_async 模式，避免阻塞 Agent 推理
3. 批量查询：将”查询 10 条 JIRA Issue”合并为一次调用，而不是循环 10 次

---

一周内可执行行动清单

Day 1-2：本地跑通 MCP

• 安装 @modelcontextprotocol/sdk
• 跑通上面的 file-mcp-server.mjs 示例
• 用 Claude Code 或支持 MCP 的客户端（如 Cursor）验证工具可用

Day 3-4：接入一个真实系统

• 选择一个业务场景（JIRA/GitHub/数据库/内部 API）
• 用 Python 或 Node.js 编写对应的 MCP Server
• 配置环境变量传参（不要硬编码密钥）
• 验证工具调用成功且返回预期结果

Day 5：生产级加固

• 添加工具 description 和 annotations（危险工具声明）
• 实现错误处理（网络超时、后端报错、schema 不匹配）
• 如果是 HTTP Server，配置 Nginx 代理和超时参数
• 写好工具的 API 文档（Agent 需要知道工具的用途）

Day 6-7：集成到 Agent 工作流

• 在 .mcp.json 配置多 Server 并联
• 测试 Agent 在真实任务中的调用路径（如：“帮我查一下本周未关闭的 Bug”）
• 统计工具调用成功率，识别失败原因
• 将 MCP Server 接入 CI/CD，确保每次发布后工具仍可用

---

参考资源

• MCP 官方文档：https://modelcontextprotocol.io
• Anthropic MCP SDK（Node.js）：https://github.com/modelcontextprotocol/python-sdk
• Pinterest MCP 生产落地案例：https://www.infoq.com/news/2026/04/pinterest-mcp-ecosystem/
• MCP Server 模板仓库：https://github.com/modelcontextprotocol/servers

---

MCP 协议正在快速成为 AI Agent 连接真实世界的”USB 接口”。现在开始投入的团队，将在 2026 年下半年获得显著的效率优势。