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

若你是一名 Python 或 TypeScript 开发者，想让 Claude、GPT、Cursor 里的 AI 真正访问数据库、调用 API、读写文件，却发现大模型本身没有「手脚」——训练数据有截止日、无法执行外部操作——本文将带你从空白项目写出一个可上生产的 MCP Server 🔧。我们会走完 Tools / Resources / Prompts 三大能力、stdio 与 HTTP+SSE 两种传输、调试测试到 Docker 部署的全链路；读完即可在 Cursor 或 Claude Desktop 中接入自研工具链。节点与套餐以 NOVAKVM 定价页为准。

[ SECTION_01 ] // WHAT_IS_MCP MCP 是什么：从 Function Calling 到统一工具协议

AI 工具集成经历了清晰的三段演进：Function Calling（OpenAI 2023）让模型输出结构化 JSON 调用参数；Plugins / GPT Actions 把 HTTP 端点包装成对话插件；MCP（Model Context Protocol） 则由 Anthropic 于 2024 年 11 月开源，把「模型如何发现、描述并调用工具」标准化为开放协议——一次实现，Claude Desktop、Cursor、VS Code Continue 等宿主均可复用。

• LLM 能力边界：无法访问实时数据、无法直接操作文件系统或数据库——必须靠外部工具补上「感官与手脚」。
• 格式碎片化：OpenAI Function Calling、Claude Tool Use、LangChain Agent 各自定义工具 schema，换模型或换 IDE 就要重写适配层。
• 发现机制缺失：传统 REST API 不会主动告诉 AI「我能做什么」；MCP 运行时通过 tools/list 动态暴露能力清单。
• 会话与上下文：MCP 保持持久连接，支持多步 Agent 工作流；REST 无状态请求难以串联复杂任务。
• 安全与权限：Server 端可精细控制哪些工具可写、哪些资源只读，避免模型越权操作生产数据。

Client-Server JSON-RPC 架构可概括为以下链路：

• Host（宿主）：Claude Desktop、Cursor、VS Code —— 承载用户交互界面。
• MCP Client：内嵌于 Host，与每个 Server 维护 1:1 会话。
• MCP Server（你写的）：暴露三大原语 —— Tools（可执行操作）、Resources（只读数据）、Prompts（复用提示模板）。
• 传输层：本地开发用 stdio（子进程 stdin/stdout）；远程部署用 HTTP + SSE（Server-Sent Events 推送）。
• 协议层：全部消息遵循 JSON-RPC 2.0，如 initialize → tools/list → tools/call → notifications/cancelled。
• 生命周期：握手 → 能力协商 → 正常运行 → 优雅关闭；Client 可随时 ping 保活。

MCP 解决的不是「能不能调 API」，而是「AI 如何统一发现、选择并正确调用工具」——这是 Agent 时代的核心命题。

[ SECTION_02 ] // DEV_ENV 开发环境搭建：Python mcp SDK 与 TypeScript SDK 选型

官方提供两套一等 SDK：Python 的 mcp 包（含 FastMCP 高层 API）与 TypeScript 的 @modelcontextprotocol/sdk。Python 适合快速原型与数据/ML 场景；TypeScript 适合 Node.js 生态与前端团队。下文以 Python FastMCP 为主，TypeScript 结构完全对称。

mkdir my-mcp-server && cd my-mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip install "mcp[cli]" httpx pydantic python-dotenv
npm install -g @modelcontextprotocol/inspector

推荐项目结构：

my-mcp-server/
├── server.py
├── tools/
├── resources/
├── prompts/
├── tests/
├── Dockerfile
├── requirements.txt
└── .env

调试与接入三件套：

• MCP Inspector：官方可视化调试器，可列出 tools/resources/prompts 并手动触发调用。
• Claude Desktop：编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）注册 stdio Server。
• Cursor：Settings → MCP → 添加 Server 配置，支持 stdio 与远程 HTTP 端点。

[ SECTION_03 ] // HELLO_WORLD Hello World：10 行代码跑通第一个 MCP Server

用 FastMCP 写一个最小可用 Server，暴露 say_hello 工具：

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("hello-server")

@mcp.tool()
def say_hello(name: str) -> str:
    return f"Hello, {name}! MCP Server is running."

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

用 Inspector 启动验证：

npx @modelcontextprotocol/inspector python server.py

浏览器打开 Inspector UI，在 Tools 面板调用 say_hello，传入 {"name": "NOVAKVM"}，应返回问候语 ✅。

Claude Desktop 配置（claude_desktop_config.json）：

{
  "mcpServers": {
    "hello-server": {
      "command": "/path/to/my-mcp-server/.venv/bin/python",
      "args": ["/path/to/my-mcp-server/server.py"]
    }
  }
}

Cursor MCP 配置：在项目根目录创建 .cursor/mcp.json 或在 Cursor Settings → MCP 中添加等价 JSON，重启 Cursor 后在 Agent 模式即可看到 say_hello 工具。

[ SECTION_04 ] // TOOLS Tools 深度开发：5 类工具与错误处理最佳实践

MCP 工具的函数签名即文档：参数名、类型注解与 docstring 会自动转为 JSON Schema 供模型理解。复杂输入用 Pydantic 模型约束：

from pydantic import BaseModel, Field

class SearchInput(BaseModel):
    query: str = Field(..., description="搜索关键词")
    limit: int = Field(10, ge=1, le=100, description="返回条数上限")

@mcp.tool()
async def search_docs(input: SearchInput) -> list[dict]:
    ...

生产级 Server 通常实现以下五类工具：

• calculator：安全数学表达式求值，禁止 eval 裸执行，用 ast 或专用库解析。
• file_read / file_write：限定根目录（chroot 思路），防止路径穿越；写操作需二次确认或白名单扩展名。
• fetch_url：异步 HTTP 请求，示例如下。
• db_query：只读 SQL（SELECT），参数化查询防注入；写操作单独工具并加审计日志。
• get_current_time：返回 ISO 8601 时间戳，解决模型「不知道现在几点」的常见问题。

import httpx

@mcp.tool()
async def fetch_url(url: str, timeout: int = 30) -> str:
    async with httpx.AsyncClient(timeout=timeout) as client:
        resp = await client.get(url)
        resp.raise_for_status()
        return resp.text[:50000]

错误处理最佳实践：

• 工具内捕获异常，返回结构化错误文本而非让进程崩溃 —— Client 会把返回值交给模型自行 retry 或换策略。
• 对外部 API 设置超时与重试上限；避免模型陷入无限循环调用。
• 敏感信息（API Key、连接串）只读环境变量，绝不写入 tool 返回值或 Resources。
• 写操作工具返回操作摘要（改了什么、影响行数），便于模型向用户确认。

[ SECTION_05 ] // RESOURCES Resources 资源协议：只读数据 vs 可执行工具

Resource 与 Tool 的核心区别：Resource 是只读上下文数据（配置文件、用户档案、日志片段），模型通过 resources/read 拉取；Tool 是可执行操作（查询、写入、发请求）。Resource 适合「AI 需要看但不需要改」的信息。

URI 方案（scheme）约定：

• config://app/settings —— 静态配置资源，启动时注册。
• user://{id}/profile —— 动态模板，Client 传入具体 id 后 Server 实时生成内容。
• file:// —— 映射本地文件系统（需路径沙箱）。

Resource 支持四种 MIME 类型：text/plain、application/json、二进制 blob（Base64 编码返回）、stream（大文件分块推送）。

@mcp.resource("config://app/settings")
def get_app_settings() -> str:
    return json.dumps({"env": "production", "version": "1.2.0"})

@mcp.resource("user://{user_id}/profile")
def get_user_profile(user_id: str) -> str:
    profile = db.fetch_user(user_id)
    return json.dumps(profile)

文件系统 Resource Server 可递归注册目录下文件，让 AI 在编码时直接「看到」项目结构与关键配置，而无需逐文件调用 read tool。

[ SECTION_06 ] // PROMPTS Prompts 提示模板：可复用的多轮对话脚手架

MCP Prompt 是预定义的提示模板，Host 可列出并一键注入对话上下文 —— 适合代码审查、事故复盘、API 设计评审等重复性工作流。Prompt 可含占位参数，支持多轮 message 结构。

from mcp.types import PromptMessage, TextContent

@mcp.prompt()
def code_review_prompt(language: str, focus: str = "security") -> list[PromptMessage]:
    return [
        PromptMessage(
            role="user",
            content=TextContent(
                type="text",
                text=f"请对以下 {language} 代码做 {focus} 维度审查，列出问题与改进建议：\n\n"
            )
        )
    ]

多轮模板示例：第一轮注入角色与约束，第二轮注入待审代码占位符，第三轮要求输出结构化 JSON（severity / file / line / suggestion）。团队可将最佳实践固化为 Prompt，新成员无需重复编写 system prompt。

[ SECTION_07 ] // HTTP_TRANSPORT HTTP 传输部署：从 stdio 到 Streamable HTTP 远程服务

FastMCP 支持 streamable-http 传输，一行切换：

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

生产 HTTP 部署须补齐：

• Bearer Token / API Key：在反向代理或 middleware 层校验 Authorization 头。
• CORS：若浏览器端 Inspector 跨域访问，配置允许的来源域名。
• Rate Limiting：按 IP 或 API Key 限流，防止模型循环调用打爆后端。
• TLS：公网暴露必须 HTTPS，推荐 Caddy / Nginx 终止 SSL。

[ SECTION_08 ] // DEBUG_TEST 调试测试与排错：Inspector、pytest 与六步部署清单

MCP Inspector 用法：启动后左侧列出 Server 能力树；Tools 面板可填 JSON 参数手动触发；Notifications 面板观察 Server 推送；Logs 面板查看 stderr 输出。改代码后 Inspector 会自动重启子进程。

import pytest
from server import say_hello

def test_say_hello():
    result = say_hello("World")
    assert "Hello, World!" in result

@pytest.mark.asyncio
async def test_fetch_url():
    result = await fetch_url("https://httpbin.org/get")
    assert "origin" in result

六步生产部署清单：

1. 锁定依赖版本：pip freeze > requirements.txt，在 CI 中固定 Python 与 mcp SDK 版本，避免上游 breaking change。
2. 编写 Dockerfile：多阶段构建，最终镜像只含运行时依赖；非 root 用户运行 Server 进程。
3. 配置环境变量：API Key、DB 连接串、ALLOWED_PATHS 全部走 secrets 管理，禁止硬编码。
4. 选择托管平台：Railway / Render 适合快速验证；AWS Lambda + HTTP adapter 适合低频调用；Cloud Run / VPS 适合 7×24 常驻。
5. 接入监控：结构化日志（JSON）、/health 端点、Prometheus metrics 或 Sentry 异常上报。
6. Cursor / Claude 接入验证：远程 URL + Bearer Token 写入 MCP 配置，调用 tools/list 确认工具清单完整后放量。

[ SECTION_09 ] // PRODUCTION 生产环境上线：Docker、托管平台与可观测性

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

托管平台选型：

• Railway / Render：Git push 自动部署，免费 tier 适合 MVP；注意冷启动对 SSE 长连接的影响。
• AWS Lambda：按调用计费，需 HTTP-to-stdio 适配层；适合低频内部工具。
• Google Cloud Run：容器原生、自动扩缩；SSE 需配置 min-instances ≥ 1 保活。
• VPS / 裸金属：完全控制网络与磁盘，适合敏感数据不出内网的 MCP Server。

可观测性三件套：

• Logging：structlog 或 python-json-logger，每条 tool call 记录 name、duration_ms、status。
• Prometheus：暴露 mcp_tool_calls_total、mcp_tool_duration_seconds 等指标。
• Sentry：捕获未处理异常，关联 Server 版本 tag 便于回滚。

版本兼容性：MCP 规范 2025-03-26 引入 Streamable HTTP；部署前核对 Client（Cursor 版本、Claude Desktop 版本）与 Server SDK 是否支持同一传输。建议在 README 中标注 mcp>=1.2.0 等最低版本要求。

[ SECTION_10 ] // ECOSYSTEM 实战：ChromaDB 知识库 MCP + 2026 生态与学习路径

综合实战项目 —— 知识库 MCP Server：用 ChromaDB 或 Qdrant 存储文档向量，watchfiles 监听目录变更自动 re-index，暴露 search_knowledge 与 write_note 两个工具。在 Cursor 中接入后，Agent 编码时可检索团队内部文档，而非仅依赖训练数据 📚。

@mcp.tool()
async def search_knowledge(query: str, top_k: int = 5) -> list[dict]:
    embedding = await embed(query)
    results = collection.query(query_embeddings=[embedding], n_results=top_k)
    return [{"text": doc, "score": score} for doc, score in zip(...)]

@mcp.tool()
async def write_note(title: str, content: str) -> str:
    doc_id = collection.add(documents=[content], metadatas=[{"title": title}])
    return f"Note saved: {doc_id}"

推荐复用的社区 MCP Server：

• @modelcontextprotocol/server-filesystem —— 安全沙箱文件读写
• server-github —— Issue、PR、代码搜索
• server-brave-search —— 联网实时搜索
• server-postgres —— 只读 SQL 查询
• server-slack —— 频道消息与通知

2026 年 MCP 生态关键数据：

• 生态规模：截至 2026 年，公开 MCP Server 已超过 10,000 个，GitHub 上 modelcontextprotocol 组织仓库 Star 合计超 50,000。
• 厂商 adoption：2026 年 Q1 OpenAI、Q2 Google Gemini 与 Microsoft Copilot 均已宣布原生 MCP 支持；治理权移交 Linux Foundation 旗下 AAIF。
• 企业集成成本：采用 MCP 标准化接口后，企业 AI 工具链集成开发成本降幅约 38–55%（行业调研口径）。

学习路径建议：

1. 阅读官方规范，理解 JSON-RPC 消息流
2. 用 FastMCP 完成 Hello World + Inspector 调试
3. 实现 3 个以上真实 Tools（文件、HTTP、DB）
4. 添加 Resources 与 Prompts，体验三大原语差异
5. 切换 HTTP 传输，Docker 部署到云端
6. 接入 Cursor，完成知识库或 GitHub 集成实战

以下公开资料可作为规范与 SDK 的核验入口；若上游仓库更新，请以链接为准。

Model Context Protocol — 官方规范与文档

modelcontextprotocol/python-sdk — Python MCP SDK

modelcontextprotocol/typescript-sdk — TypeScript MCP SDK

modelcontextprotocol/inspector — MCP Inspector 调试工具

把 MCP Server 跑在会休眠的笔记本上，常见故障是：tools/list 会话中断、OAuth 过期、磁盘满导致向量库损坏、网络切换后 SSE 断连 —— 比「选哪个模型」更影响日常开发体验。Docker on laptop 仍有宿主机休眠问题；免费 tier PaaS 冷启动让长连接频繁断开；Lambda 不适合 SSE 常驻场景。

若你需要 7×24 常驻 MCP 工具链、稳定 SSH 与可预期的 Apple Silicon 算力，把 Cursor Agent 与自研 Server 迁到独占裸金属通常更划算：NOVAKVM 提供多区域 Mac Mini M4 / M4 Pro 弹性租期，适合 Cursor MCP、Claude Desktop 远程开发与向量库同机部署。套餐见 定价页，下单见 订购页，部署问题见 帮助中心 🚀。