Model Context Protocol（MCP）是一项开放标准，使像 Anthropic 的Claude 这样的模型以及像Claude Code 这样的开发者工具能够以安全、标准的方式调用外部工具、数据源和提示。

本指南将带你从零开始构建自己的 MCP 服务器，使 Claude Code 能够访问自定义功能，从而将其能力大幅扩展到内置功能之外。

什么是 Model Context Protocol（MCP）？

MCP（Model Context Protocol）是一份用于标准化语言模型客户端（如 Claude、Claude Code 或其他 LLM 前端）如何连接到工具服务器和数据源的开放规范。你可以将 MCP 看作是“面向 LLM 的 USB-C 接口”：它定义了一个传输层/JSON-RPC 模式，以及服务器用于发布三类能力的通用方式：

• 资源（Resources）—— 客户端可读取的类文件或文档数据（例如数据库行、文本文件、JSON 负载）。
• 工具（Tools）—— 模型可请求宿主执行的可调用函数（需用户批准）。
• 提示（Prompts）—— 可复用的提示模板或工作流，模型/客户端可以调用。

MCP 支持多种传输（stdio、HTTP、SSE），并提供了模式、SDK 和示例服务器，因此你无需自行设计线协议。该协议在公开渠道维护（规范与 SDK），且提供教程与示例服务器库以加速采用。

MCP 是如何架构的？

MCP 的架构有意保持简单与模块化：核心部分是 MCP 服务器、MCP 客户端，以及在它们之间承载 JSON-RPC 分帧消息的传输层。下面是为 Claude Code（或其他 MCP 客户端）构建服务器时你会接触的主要组件。

服务器、客户端与协议

• MCP 服务器 —— 一个用于发布工具、资源与提示的服务。工具可执行副作用或抓取数据；资源暴露只读内容；提示是客户端可让模型调用的可复用提示模板。
• MCP 客户端（宿主）—— 通常是 LLM 宿主的一部分（例如 Claude Code、VS Code 插件或浏览器客户端）。它发现可用服务器，将工具描述呈现给模型，并将模型发起的调用路由给服务器。
• 协议 —— 消息使用 JSON-RPC 编码；规范定义了生命周期事件、工具发现、调用、补全/采样，以及如何将结构化结果传回客户端与模型。

通信模式（使用工具时会发生什么）

1. 客户端将用户消息发送给模型。
2. 模型分析上下文并决定调用由 MCP 暴露的工具（可能是多个）。
3. 客户端通过选定的传输将工具调用转发给 MCP 服务器。
4. 服务器执行该工具并返回结果。
5. 模型接收工具输出并为用户撰写最终答案。

实现基础要素

• JSON-RPC 消息遵循 MCP 模式。
• 工具定义会在服务器的发现响应中发布，便于客户端在 UI 中呈现。
• 客户端通过 @source:path 语法引用资源（例如 @postgres:...），让模型在不把大量数据内嵌到提示中的情况下引用外部内容。

为什么要将 Claude Code 与 MCP 服务器集成？

Claude Code 是 Anthropic 面向代码与开发者场景（编辑器/IDE 集成、代码理解等）的产品。通过 MCP 服务器暴露你的内部工具（源码搜索、CI 运行器、工单系统、私有镜像仓库），可让 Claude Code 在编码对话与代理流程中将它们作为一等工具使用。

将 Claude Code 与 MCP 服务器集成可为编码代理解锁实用且贴近生产的能力：

1. 让模型在真实系统上执行操作

Claude Code 可以请求 MCP 服务器查询问题跟踪器、运行数据库查询、读取大型文档，或创建 GitHub PR——从而在编码会话内实现端到端自动化。这在 Claude Code 文档中有明确支持（示例：查询 Postgres、Sentry，或创建 PR）。

2. 卸载大量数据与专门逻辑

无需把每个数据源都嵌入到提示中（这会消耗 tokens），你可以通过 MCP 发布数据与工具。模型调用工具，获取结构化响应，并据此推理——这样可以减少 token 使用，并让服务器处理繁重工作（数据库查询、长文件读取、鉴权）。

3. 安全性与治理

MCP 将访问控制与审计集中于服务器层，组织可以白名单批准的服务器、控制可用工具并限制输出。Claude Code 也支持企业级 MCP 配置与按作用域授权。

4. 可复用性与生态

MCP 服务器可在不同客户端与团队间复用。一次构建，多种 Claude/LLM 客户端都可使用同一服务（或替换实现）。

开始之前需要准备什么？

最低要求

• 一台安装了 Python 3.10+ 的开发机器（示例将使用 Python）。或者也可使用 MCP SDK 支持的 Node / 其他语言。
• uv（Astral 的工具）或等效运行器，用于运行 MCP stdio 服务器（MCP 教程使用 uv）。安装步骤见下文。
• 已安装 Claude Code 或有权访问 Claude 客户端（桌面或 CLI）以注册并测试你的服务器；或任何支持 MCP 的客户端。Claude Code 支持 HTTP、SSE 和本地 stdio 服务器。
• 安全注意事项：仅在团队或企业环境中将可信的 MCP 服务器添加到 Claude Code——MCP 赋予服务器访问敏感数据的能力，且若服务器返回恶意内容存在提示注入风险。

如何安装并验证 Claude Code CLI

这是《Claude Code 安装与使用指南》。

1) 快速摘要 — 推荐的安装方式

使用原生安装器（推荐）或在 macOS/Linux 上使用 Homebrew。如果你需要基于 Node 的安装方式，也可以使用 NPM。Windows 提供 PowerShell / CMD 安装器。来源：官方 Claude Code 文档与 GitHub。

---

2) 先决条件

• macOS 10.15+、Ubuntu 20.04+/Debian 10+，或 Windows 10+（Windows 上推荐使用 WSL）。
• 仅当使用 NPM 安装方式时才需要 Node.js 18+。

---

3) 安装命令（任选其一）

原生（推荐——无 Node 依赖），macOS / Linux / WSL：

curl -fsSL https://claude.ai/install.sh | bash
# optional: install latest explicitly

curl -fsSL https://claude.ai/install.sh | bash -s latest
# or install a specific version

curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

Windows PowerShell：

irm https://claude.ai/install.ps1 | iex
# or for latest: & (::Create((irm https://claude.ai/install.ps1))) latest

（以上为官方原生安装脚本。）

NPM（如果你希望基于 Node 的全局安装）：

# requires Node.js 18+

npm install -g @anthropic-ai/claude-code

请勿使用 sudo npm install -g——不推荐带 sudo 的全局安装（权限/安全问题）。如果遇到权限错误，请使用 nvm 或修正 npm 全局前缀，而不是使用 sudo。

4) 验证可执行文件已安装（基础检查）

安装完成后立即在本地运行：

# is the command on PATH?

which claude

# version (or -v)

claude --version
# or

claude -v

# help (sanity check)

claude --help

预期：which 会显示一个路径（例如 /usr/local/bin/claude 或 ~/.nvm/.../bin/claude），且 claude --version 会打印一个类似 semver 的版本字符串。文档与 README 都显示 claude 是主要的 CLI 入口命令。

---

5) 验证安装健康与配置（推荐检查）

a) claude doctor，运行：

claude doctor

这个内置诊断会检查你的安装类型、常见问题（如 npm 权限问题）、依赖项（例如 ripgrep），并给出修复建议。文档明确建议在安装后运行 claude doctor。

b) 运行冒烟测试（非交互式）

在你的项目目录中：

cd /path/to/your/project
claude -p "Explain this project in 3 sentences"

这会使用打印模式（-p）发送单次提示后退出；非常适合用于 CI 或快速功能验证。

c) 身份验证检查（确保 CLI 可以访问 Anthropic）

Claude Code 支持多种认证流程（Console OAuth、API Key、供应商集成）。常见检查：

1. 如果使用 API Key（CI/无头/本地环境变量）：

export ANTHROPIC_API_KEY="sk-..."
# then

claude auth status
claude auth whoami    # or `claude auth whoami` / `claude whoami` depending on version

你可以使用 CometAPI 的 API Key 来使用 Claude Code，通过 CometAPI 调用 Claude 的 API 可享受 20% 折扣。

2. 如果通过控制台使用 OAuth —— 运行：

claude auth status
claude auth whoami

你应能看到账号/套餐信息或已认证的确认信息。

逐步环境准备

下面给出两套常见开发栈（TypeScript 与 Python）的具体准备步骤，并附有快速检查以确保一切正常。

H3 — A. TypeScript / Node 设置（最快路径）

1. 创建项目并安装 SDK：

mkdir mcp-demo && cd mcp-demo
npm init -y
npm install @modelcontextprotocol/sdk express zod
npm install --save-dev typescript tsx @types/node @types/express

2. 创建 server.ts。（完整示例见“如何快速构建……”章节。）
3. 运行：

npx -y tsx server.ts

4. 使用 MCP Inspector 在本地测试，或添加到 Claude Code：

npx @modelcontextprotocol/inspector
# or (for Claude Code)

claude mcp add --transport http my-server http://localhost:3000/mcp

（Inspector 与 Claude 命令可帮助你验证发现与调用工具。）

如何快速为 Claude Code 构建一个 MCP 服务器？

快速清单

1. 启动你的服务器（推荐可流式 HTTP）：node server.ts 或 uvicorn server:app。

2. 在开发机器上，二选一：

• 使用 MCP Inspector 验证（npx @modelcontextprotocol/inspector），确认 tools/list 与 resources/list；或
• 将服务器添加到 Claude Code：claude mcp add --transport http <name> http://<host>:<port>/mcp（如果你的客户端支持远程 MCP，也可以按照网页 UI 流程操作）。

如果你计划在 Anthropic 的 Messages API 中使用远程 MCP 连接器（无需单独客户端），请阅读 Claude 文档——可能需要一个 beta 头部（请查阅文档获取确切的头部与当前支持状态）。

下面提供两个完整但精简的服务器示例，你可以直接复制、运行，并连接到 Claude Code（或 MCP Inspector）。TypeScript 示例使用 Express + TypeScript SDK；Python 示例展示了 FastAPI 挂载方式。

注：以下代码遵循公共 SDK 示例，并为清晰起见进行了最小化。生产环境请增加认证、日志、限流以及超出 SDK 默认的输入验证。

---

示例 1：TypeScript + Express（可流式 HTTP）

创建 server.ts（完整）：

// server.ts
import express from "express";
import * as z from "zod/v4";
import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";

const server = new McpServer({ name: "claude-code-demo", version: "0.1.0" });

// Register a simple tool: add two numbers
server.registerTool(
  "add",
  {
    title: "Add",
    description: "Add two numbers a and b",
    inputSchema: { a: z.number(), b: z.number() },
    outputSchema: { result: z.number() }
  },
  async ({ a, b }) => {
    const output = { result: a + b };
    return {
      content: ,
      structuredContent: output
    };
  }
);

// Register a resource: greet user (dynamic)
server.registerResource(
  "greeting",
  new ResourceTemplate("greeting://{name}", { list: undefined }),
  { title: "Greeting", description: "Return a greeting for the name" },
  async (uri, params) => {
    return {
      contents: 
    };
  }
);

// Express + Streamable HTTP transport
const app = express();
app.use(express.json());

app.post("/mcp", async (req, res) => {
  const transport = new StreamableHTTPServerTransport({ enableJsonResponse: true });
  // Close transport when connection closes
  res.on("close", () => transport.close());
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

const port = parseInt(process.env.PORT || "3000", 10);
app.listen(port, () => console.log(`MCP server listening: http://localhost:${port}/mcp`));

运行：

npm install
npx -y tsx server.ts

然后在 Claude Code 中连接（示例）：

# Add the remote server to your Claude Code MCP list (local dev)

claude mcp add --transport http my-demo http://localhost:3000/mcp

此示例改编自官方 TypeScript SDK 快速入门，演示了如何注册工具与资源，并通过可流式 HTTP 暴露它们。

---

示例 2：Python + FastAPI（FastMCP + 可流式 HTTP）

创建 server.py（完整）：

# server.py

from fastapi import FastAPI
from mcp.server.fastmcp import FastMCP

app = FastAPI()
mcp = FastMCP("claude-python-demo", stateless_http=True)

# tool: simple sum

@mcp.tool()
def add(a: int, b: int) -> dict:
    """Add two integers"""
    return {"result": a + b}

# resource: simple greeting resource template

@mcp.resource("greeting://{name}")
def greeting(name: str):
    return {"contents": }

# mount the streamable-http MCP endpoint (FastMCP exposes an ASGI app)

app.mount("/mcp", mcp.streamable_http_app())

# optional endpoint to demonstrate other API routes

@app.get("/")
async def root():
    return {"status": "OK"}

运行：

uvicorn server:app --reload --port 8000

使用 Inspector 连接：

npx @modelcontextprotocol/inspector
# In Inspector select Streamable HTTP and enter http://localhost:8000/mcp

Python SDK 示例与 FastMCP 工具让你可以轻松注册 @mcp.tool() 与 @mcp.resource() 装饰的函数，供 LLM 发现与调用。

---

Claude Code 实际上如何调用你的工具？

当 LLM 决定使用某个工具时，客户端会向 MCP 服务器发送 JSON-RPC 调用。服务器执行所请求的工具（例如查询数据库、运行测试或调用外部 API），并返回结构化内容与可呈现内容。客户端（Claude Code）随后可以将结构化输出纳入模型上下文，使模型基于可靠数据继续推理，而不仅仅依赖服务器的文本输出。TypeScript SDK 支持注册 inputSchema 与 outputSchema（使用 zod），从而对参数与输出进行验证并提供机器可读的类型。

---

应该使用哪些测试与调试工具？

MCP Inspector

MCP Inspector 是用于测试 MCP 服务器的官方可视化开发工具。它允许你连接到服务器（stdio、SSE 或可流式 HTTP）、列出工具、手动调用它们，并检查 JSON-RPC 消息的生命周期——在开发过程中不可或缺。通过 npx @modelcontextprotocol/inspector 启动。

本地 vs 远程测试

• 本地（stdio）—— 为桌面应用与离线调试提供快速迭代周期。
• 可流式 HTTP —— 使用 Inspector 测试，或通过 claude mcp add CLI 或 Messages API 中的 MCP 连接器将其连接到 Claude Code 进行远程测试。请确保提供服务器所需的任何鉴权头。

结论

MCP 是连接现代 LLM 与实际掌握数据并执行操作的系统之间的实用桥梁。对于代码工作流，将 Claude Code 与 MCP 服务器集成为模型提供对代码库、CI、问题跟踪器与自定义工具的结构化、可审计访问——从而带来更精准的自动化与更安全的副作用。借助 TypeScript 与 Python 的官方 SDK、用于远程托管的可流式 HTTP，以及 MCP Inspector 等工具，你可以在几分钟内构建一个最小可用服务器，并持续迭代直至生产部署。

开发者可以通过 CometAPI 使用 Claude Sonnet 4.5 API 与 Claude Opus 4.1 API 等，且最新模型版本会与官网同步更新。开始之前，可在Playground 中探索模型能力，并查阅API 指南获取详细使用说明。访问前，请确保你已登录 CometAPI 并获取 API Key。CometAPI 提供远低于官网的价格，助你集成落地。

准备好开始了吗？→ 立即注册 CometAPI！

想获取更多技巧、指南与 AI 新闻，欢迎关注我们的 VK、X 与 Discord！