从 0 开发一个 MCP Server：2026 手把手构建 AI 工具调用能力

大模型再聪明，没有「手脚」也查不了数据库、调不了 API、读不了你的本地笔记。Model Context Protocol（MCP） 用 JSON-RPC 把 AI 客户端与外部能力标准化对接——2026 年生态已超 13,000 个 Server，OpenAI、Google、Microsoft 全面支持。痛点：Function Calling 各写一套、换模型就要推倒重来。结论：读完本文你能独立开发、调试并部署生产可用的 MCP Server。结构：协议原理 → 环境搭建 → Hello World → Tools/Resources/Prompts → HTTP 远程 → 调试测试 → Docker 部署 → 个人知识库实战 → 生态展望。

1. 什么是 MCP？先搞懂协议再写代码

1.1 MCP 的诞生背景

工具调用能力经历了三代演进：Function Calling（OpenAI 私有格式）→ Plugins（ChatGPT 插件生态，已式微）→ MCP（开放标准）。Anthropic 于 2024 年 11 月开源 MCP，核心动机是：每换一个 AI 客户端就要重写一遍工具集成，形成 N×M 爆炸。MCP 解决的是标准化 AI 与外部工具的通信协议——写一次 Server，Cursor、Claude Desktop、VS Code 都能用。2026 年治理权已移交 Linux Foundation 旗下 AAIF。

1.2 MCP 协议架构概览

┌────────────────────┐         ┌─────────────────────┐
│   MCP Client       │ ◄─────► │   MCP Server        │
│  (Claude / Cursor) │  JSON   │  (你要开发的部分)    │
│                    │  -RPC   │                     │
└────────────────────┘         └─────────────────────┘
                                        │
                          ┌─────────────┼─────────────┐
                          ▼             ▼             ▼
                       Tools       Resources      Prompts
                    (工具调用)    (资源读取)    (提示词模板)

Client：AI 模型侧宿主（Claude Desktop、Cursor、自定义 Agent）。Server：你开发的能力提供方。三大核心能力：Tools 是 AI 可调用的函数（搜索、计算、SQL）；Resources 是 AI 可读取的数据（文件、配置、URL）；Prompts 是预定义提示词模板，支持参数注入。

1.3 MCP 通信机制

底层基于 JSON-RPC 2.0。传输方式：stdio（本地子进程，零网络配置）与 Streamable HTTP（2025-06-18 规范取代旧版 HTTP+SSE，适合远程/多客户端）。生命周期：初始化握手 → 能力协商（tools/list）→ 请求/响应 → 关闭。⚠️ 本地 stdio 模式禁止向 stdout 打印非协议日志，否则 JSON-RPC 解析会失败。

1.4 MCP vs 其他方案对比

对比维度	MCP	OpenAI Function Calling	LangChain Tools
标准化程度	开放协议标准	厂商私有	框架绑定
传输方式	stdio / Streamable HTTP	HTTP	HTTP
跨模型支持	是	否	部分
资源/提示词	原生支持	不支持	不支持
生态工具	13,000+ Server（2026）	成熟	成熟

2. 开发环境准备

2.1 选择开发语言

Python（推荐新手）：官方 SDK mcp + FastMCP 装饰器，简洁易上手。TypeScript（推荐前端/全栈）：@modelcontextprotocol/sdk + Zod 校验，npm 下载量已超 150M。本文以 Python 为主，TypeScript 做对照说明。

2.2 环境搭建

# Python 环境
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install "mcp[cli]"

# TypeScript 环境（对照）
npm init -y
npm install @modelcontextprotocol/sdk zod

2.3 项目结构设计

my-mcp-server/
├── server.py            # 主服务入口
├── tools/               # 工具模块
│   ├── calculator.py
│   └── web_search.py
├── resources/           # 资源模块
│   └── file_reader.py
├── prompts/             # 提示词模板
│   └── templates.py
├── tests/
│   └── test_tools.py
├── pyproject.toml
└── README.md

2.4 调试工具安装

1）MCP Inspector：npx @modelcontextprotocol/inspector python server.py，浏览器 UI 在 localhost:6274 调试 Tools/Resources/Prompts。2）Claude Desktop：编辑 ~/Library/Application Support/Claude/claude_desktop_config.json。3）Cursor：Settings → MCP → 添加 mcpServers 配置。详见本站 MCP 协议深度解读。

3. 第一个 MCP Server：Hello World

3.1 最简单的 MCP Server

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-first-server")

@mcp.tool()
def say_hello(name: str) -> str:
    """向指定的人打招呼"""
    return f"Hello, {name}! 这是你的第一个 MCP 工具。"

if __name__ == "__main__":
    mcp.run()

3.2 运行与验证

python server.py
# 或使用 MCP Inspector 调试
npx @modelcontextprotocol/inspector python server.py

3.3 在 Cursor / Claude Desktop 中接入

// claude_desktop_config.json 或 Cursor MCP 设置
{
  "mcpServers": {
    "my-first-server": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

⚠️ 必须使用绝对路径指向 Python 解释器与脚本。重启客户端后，在对话中应能看到 say_hello 工具出现在上下文中。

4. Tools：开发可被 AI 调用的工具

4.1 工具的基本结构

函数签名即文档：参数类型、返回类型、docstring 会被 SDK 自动转为 JSON Schema 供 LLM 理解。命名规范：小写+下划线，语义清晰（web_search 优于 ws）。错误处理：返回结构化错误字符串优于直接抛未捕获异常，避免整个 Server 崩溃。

4.2 输入参数类型支持

from pydantic import BaseModel, Field

class SearchInput(BaseModel):
    query: str = Field(description="搜索关键词")
    max_results: int = Field(default=5, description="最多返回结果数")
    language: str = Field(default="zh", description="结果语言")

@mcp.tool()
def web_search(input: SearchInput) -> list[dict]:
    """执行网络搜索，返回相关结果列表"""
  # 实现搜索逻辑
    return [{"title": "示例", "url": "https://example.com"}]

4.3 实战案例：5 个实用工具

工具	用途	关键实现
计算器	数学表达式求值	`eval` 需沙箱或 `ast` 安全解析
文件读写	读/写本地文件	限制允许目录，防路径穿越
HTTP 请求	调用外部 API	`httpx` + 超时 30s
数据库查询	执行只读 SQL	参数化查询，禁 DDL
时间工具	当前时间/时区转换	`zoneinfo` 标准库

4.4 异步工具开发

import httpx

@mcp.tool()
async def fetch_url(url: str) -> str:
    """获取指定 URL 的内容"""
    async with httpx.AsyncClient(timeout=30.0) as client:
        response = await client.get(url)
        return response.text[:10000]  # 截断防 token 爆炸

4.5 工具错误处理最佳实践

1）结构化错误：返回 {"error": "...", "code": "TIMEOUT"} 字符串。2）超时：所有 I/O 操作设 30s 上限。3）权限校验：在 Tool 层白名单目录/API，不要依赖 LLM「自觉」。

5. Resources：让 AI 读取动态内容

5.1 Resource 与 Tool 的区别

Resource 是数据提供者（只读为主），Tool 是动作执行者。URI 寻址：file://、http://、custom:// 自定义 scheme。

5.2 静态资源 vs 动态资源

import json

@mcp.resource("config://app-settings")
def get_app_settings() -> str:
    """返回应用配置"""
    return json.dumps({"version": "1.0", "env": "production"})

@mcp.resource("user://{user_id}/profile")
def get_user_profile(user_id: str) -> str:
    """根据用户 ID 返回用户资料"""
    return json.dumps({"user_id": user_id, "name": "Demo"})

5.3 资源类型

文本资源（text/plain、application/json）、二进制资源（图片/PDF，返回 base64）、流式资源（实时行情，需 Streamable HTTP）。

5.4 实战：文件系统资源服务器

列出目录、读取文件内容、可选订阅文件变化（resources/subscribe）。生产环境务必限制根目录，参考官方 mcp-server-filesystem 的 allowlist 设计。

6. Prompts：定义可复用的提示词模板

6.1 什么是 MCP Prompt？

预定义提示词片段，AI 可直接复用；支持动态参数注入；提升团队 Prompt 一致性与可维护性。与 Cursor Agent Skills 互补：MCP Prompt = 协议层模板，Skill = 操作手册。

6.2 创建提示词模板

from mcp.types import PromptMessage, TextContent

@mcp.prompt()
def code_review_prompt(language: str, code: str) -> list[PromptMessage]:
    """代码审查提示词模板"""
    return [
        PromptMessage(
            role="user",
            content=TextContent(
                type="text",
                text=f"""请对以下 {language} 代码进行审查：
1. 代码质量和可读性
2. 潜在 Bug 和安全隐患
3. 性能优化建议

```{language}
{code}
```"""
            )
        )
    ]

6.3 多轮对话提示词

可定义包含 user 和 assistant 的多轮模板。场景：面试模拟（assistant 扮演面试官）、代码调试助手（assistant 先问澄清问题）。

7. 进阶：HTTP 传输模式（远程 MCP Server）

7.1 stdio vs Streamable HTTP

特性	stdio	Streamable HTTP
部署方式	本地进程	远程服务器
延迟	极低（<5ms）	依赖网络（50–200ms）
多客户端	不支持	支持
适用场景	本地工具、IDE 插件	SaaS/团队共享/7×24

⚠️ 旧版 HTTP+SSE 已在 2025-06-18 规范中废弃，新项目请用 Streamable HTTP。

7.2 实现 HTTP 传输

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("remote-server")

if __name__ == "__main__":
    mcp.run(transport="streamable-http", host="127.0.0.1", port=8000)

生产部署可用 uvicorn/gunicorn 反代。Serverless（Cloud Run/Lambda）需 stateless_http=True，因内存 session 会在冷启动时丢失。

7.3 认证与安全

Bearer Token 认证、API Key 中间件、CORS 白名单、请求频率限制（建议 100 req/min/IP）。本地开发绑定 127.0.0.1，禁止 0.0.0.0 无认证暴露。2026 年已披露 30+ MCP 相关 CVE，含 CVSS 9.6 的 mcp-remote RCE。

8. 调试与测试

8.1 使用 MCP Inspector 调试

启动后可在 UI 中：列出 Tools → 手动调用 → 查看 JSON-RPC 原始报文 → 模拟超时/错误场景。比直接连 LLM 调试效率高 10×。

8.2 编写单元测试

import pytest
from mcp.client.session import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client

@pytest.mark.asyncio
async def test_calculator_tool():
    server_params = StdioServerParameters(
        command="python", args=["server.py"]
    )
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool("calculate", {"expression": "2 + 2"})
            assert "4" in result.content[0].text

8.3 常见错误排查

错误	原因	解决方案
工具未出现在 AI 中	配置路径错误	检查 config.json 绝对路径
JSON 序列化失败	返回类型不支持	转为 str 或 dict
超时断开	工具执行太慢	异步 + 30s 超时
权限拒绝	文件路径受限	配置 allowlist 目录

9. 生产部署

9.1 Docker 容器化

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["python", "server.py"]

9.2 部署到云服务

Railway / Render：一键部署，适合个人项目（月费约 $5–20）。AWS Lambda / Google Cloud Run：Serverless，按调用计费。自建 VPS：Nginx 反代 + Let's Encrypt + systemd/launchd 保活。

9.3 监控与可观测性

结构化日志（JSON Lines）、Prometheus 指标（mcp_tool_calls_total）、Sentry 错误告警、/health 健康检查端点。建议 P99 延迟告警阈值 5s。

9.4 版本管理与兼容性

在握手时声明 MCP 协议版本；工具升级保持向后兼容（新增可选参数而非改必填项）；利用 capabilities 协商避免 Client 调用不存在的 Tool。

10. 实战项目：个人知识库 MCP Server

10.1 项目需求

让 AI 能搜索本地 Markdown 笔记、语义检索、创建/更新笔记。在 Cursor 中问：「我上周记录了什么关于 MCP 的笔记？」

10.2 技术选型

组件	选型	理由
向量数据库	ChromaDB / Qdrant	本地轻量、零运维
嵌入模型	text-embedding-3-small	1536 维、成本低
文件监听	watchfiles	笔记变更自动重索引

10.3 核心代码实现

四个模块：index_notes 工具（扫描目录建索引）、semantic_search 工具（向量检索 Top-K）、write_note 工具（创建/追加 Markdown）、notes://{path} 资源（直接读取单文件）。索引约 1000 篇笔记耗时 2–5 分钟（M4 Pro）。

10.4 效果演示

用户在 Cursor 输入：「我上周关于 MCP 部署的笔记说了什么？」→ Agent 调用 semantic_search(query="MCP 部署", days=7) → 返回 3 条相关片段（相似度 0.82–0.91）→ LLM 综合回答并引用原文。全程无需把整库笔记塞进 Context Window。

11. MCP 生态与未来展望

11.1 优质 MCP Server 推荐

mcp-server-filesystem（文件系统）、mcp-server-github（仓库操作）、mcp-server-brave-search（网络搜索）、mcp-server-postgres（数据库）、mcp-server-slack（消息）。官方注册表已追踪 13,000+ Server。

11.2 MCP 生态趋势（2026）

四大厂商全面支持；MCP Marketplace 兴起；企业级 OAuth 2.1 身份验证列入路线图；与 Google A2A 协议互补（MCP = 垂直工具层，A2A = Agent 横向编排）。

11.3 下一步学习路径

① 精读 modelcontextprotocol.io 规范；② 发布第一个公开 MCP Server；③ 探索 MCP + Agent 组合；④ 贡献开源生态（Python/TS SDK）。

12. 五步落地清单

Step 1 — 用 FastMCP 写 Hello World，Inspector 验证。Step 2 — 注册 3 个业务 Tool + 1 个 Resource。Step 3 — 接入 Cursor / Claude Desktop（绝对路径配置）。Step 4 — 按需切 Streamable HTTP 远程部署。Step 5 — Docker + 监控 + 安全审计上线。

13. 可引用数字

指标	数值
MCP Server 生态（2026）	13,000+
18 个月增长倍数	7.8×（1,200 → 9,400+）
TS SDK 累计下载	150M+
2026 年 MCP 相关 CVE	30+
推荐 Tool I/O 超时	30s
知识库索引（1000 篇）	2–5 min（M4 Pro）

14. 深度案例：从本机 stdio 到 Mac 远程算力节点

某 AI 工程师在 MacBook Air 上同时跑 Cursor + 5 个 stdio MCP Server（filesystem、postgres、brave-search、自定义知识库、浏览器工具）。统一内存 24GB 常驻占用 19GB，笔记本发热降频、合盖即断连。迁移方案：本机仅保留 Cursor Host；5 个 Server 以 Streamable HTTP 部署到远程 Mac mini（64GB 统一内存），launchd 保活；本机通过 url: http://node.macgpu.local:8000/mcp 连接。工具调用 P99 延迟从本地 180ms 升至 95ms（远程节点无降频）——反而更稳。

Windows/Linux VPS 能跑 MCP Server，但在与 Xcode、ComfyUI、Final Cut 并行的图形/多媒体 + AI 工具链场景，macOS 仍更顺滑。本地 stdio 适合开发与验证；7×24 生产常驻更适合远程 Apple Silicon 节点：统一内存留给并发 Tool 调用，笔记本只做编排。

若你需要稳定、可租用的环境托管 MCP Server 集群与 Agent Gateway，可考虑 MACGPU 远程 Mac 节点：7×24 常驻、HTTP 反代已配、统一内存不被多子进程占满——从「能跑」到「稳跑」只差一个节点。