协议原理 · FastMCP 实战 · Tools/Resources/Prompts · HTTP 远程部署 · 知识库项目
为什么 AI 模型「不够聪明」？因为它无法访问外部工具与实时数据。若你希望 Claude/GPT 能查数据库、调 API、读写文件，MCP（Model Context Protocol） 正是标准化答案。本文面向有 Python 或 TypeScript 基础的后端 / AI 开发者：从协议原理到环境搭建，覆盖 Tools、Resources、Prompts 注册、MCP Inspector 调试、HTTP+SSE 远程部署与个人知识库实战项目，读完后你将能独立开发并部署生产可用的 MCP Server。
大模型工具调用能力经历了 Function Calling → Plugins → MCP 的演进。Anthropic 设计 MCP 的核心动机，是用开放协议标准化 AI 与外部工具的通信——让「写一次 Server、多 Client 复用」成为现实。
MCP Client（Claude Desktop、Cursor、自定义客户端）与 MCP Server（你开发的部分）通过 JSON-RPC 2.0 通信。Server 向下对接三类核心能力：Tools（可调用函数，如搜索、计算、数据库查询）、Resources（可读取资源，如文件、URL、数据流）、Prompts（预定义提示词模板）。
传输方式分两种：stdio（本地子进程，延迟极低）与 HTTP + SSE（远程服务，支持多客户端）。生命周期为：初始化握手 → 能力协商 → 请求/响应 → 关闭。
模型缺乏实时数据：训练截止导致无法回答「今天股价」或「最新工单状态」，必须接外部 API。
各厂商工具格式不统一：ChatGPT Plugins、OpenAI Function Calling、Claude Tool Use 各自为政，换模型要重写集成层。
IDE 无法复用工具资产：Cursor、VS Code、Claude Desktop 各有一套接入方式，团队沉淀的工具无法跨产品迁移。
Agent 框架绑定：LangChain Tools 无法直接给 CrewAI 用，编排资产锁死在框架而非团队。
N×M 维护成本：N 个模型 × M 个外部系统 = 指数级定制集成，MCP 将其收敛为「一次 Server、处处可用」。
| 对比维度 | MCP | OpenAI Function Calling | LangChain Tools |
|---|---|---|---|
| 标准化程度 | 开放协议标准 | 厂商私有 | 框架绑定 |
| 传输方式 | stdio / HTTP | HTTP | HTTP |
| 跨模型支持 | 是 | 否 | 部分 |
| Resources / Prompts | 原生支持 | 不支持 | 不支持 |
| 生态工具 | 快速增长（10000+ Server） | 成熟 | 成熟 |
读完本节再动手写代码：MCP 不是又一个 SDK，而是 AI 工具化的标准协议——掌握它，是 2026 年 AI 工程师的核心竞争力。
Python（官方 SDK mcp + FastMCP）推荐新手；TypeScript（@modelcontextprotocol/sdk）适合前端 / 全栈。本文以 Python 为主，TypeScript 做对照说明。
python -m venv .venv source .venv/bin/activate pip install mcp npm init -y npm install @modelcontextprotocol/sdk
推荐项目结构：
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
调试工具三件套：MCP Inspector（官方 UI，npx @modelcontextprotocol/inspector）、Claude Desktop 本地联调（claude_desktop_config.json）、Cursor MCP 设置（Settings → MCP Servers）。官方文档见 modelcontextprotocol.io。
以下六步 Runbook 帮你在 30 分钟内跑通第一个可被 AI 调用的工具。
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()
创建虚拟环境并安装 mcp：pip install mcp，确认 Python ≥ 3.10。
编写 server.py：用 @mcp.tool() 装饰器注册 say_hello，docstring 即工具描述。
Inspector 调试：npx @modelcontextprotocol/inspector python server.py，在 UI 中测试 tools/list 与 tools/call。
Cursor 配置：在 MCP 设置中添加 {"command":"python","args":["/path/to/server.py"]}，重启后确认工具出现在 Agent 上下文。
Claude Desktop 配置：编辑 ~/Library/Application Support/Claude/claude_desktop_config.json，格式与 Cursor 相同。
验证调用：在 Cursor 中输入「用 say_hello 向 VpsMesh 打招呼」，确认 Agent 自动选择工具并返回结果。
提示：函数签名即文档——参数类型、返回类型、docstring 会直接暴露给 LLM，决定 Agent 能否正确选用你的工具。
工具是 MCP Server 的核心。命名规范建议动词开头（search_web、query_database）；复杂参数用 Pydantic 建模：
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]:
"""执行网络搜索，返回相关结果列表"""
...
eval 裸调用。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
错误处理最佳实践：对可预期失败返回结构化错误信息（含 error_code 与 message）；网络 IO 必须设超时；写操作前做权限校验与审计日志。
Resource 与 Tool 的区别：Resource 是数据提供者（只读），Tool 是动作执行者。通过 URI 寻址：file://、http://、custom://。
@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:
user = db.query_user(user_id)
return json.dumps(user)
资源类型覆盖文本（text/plain、application/json）、二进制（图片、PDF）与流式实时数据。文件系统资源服务器可实现：列出目录、读取文件、监听变化（资源订阅）。
MCP Prompt 是预定义片段，支持动态参数注入，提升一致性与可维护性。可定义包含 user 与 assistant 的多轮模板，适用于代码审查、面试模拟、调试助手等场景。
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} 代码进行审查，重点关注质量、Bug 与性能。\n```{language}\n{code}\n```"
)
)
]
| 特性 | stdio | HTTP + SSE |
|---|---|---|
| 部署方式 | 本地进程 | 远程服务器 |
| 延迟 | 极低 | 依赖网络 |
| 多客户端 | 不支持 | 支持 |
| 适用场景 | 本地工具 | SaaS / 团队共享 |
mcp = FastMCP("remote-server", transport="streamable-http")
if __name__ == "__main__":
mcp.run(host="0.0.0.0", port=8000)
远程部署安全要点：Bearer Token 认证、API Key 校验中间件、CORS 配置、请求频率限制。生产环境禁止把密钥写进 tool schema。
Inspector 可测试 Tools 调用、查看 JSON-RPC 日志、模拟错误场景。单元测试用官方 Client SDK 启动 stdio 子进程：
@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 result.content[0].text == "4"
| 错误 | 原因 | 解决方案 |
|---|---|---|
| 工具未出现在 AI 中 | 配置路径错误 | 检查 config.json 中 command/args 绝对路径 |
| JSON 序列化失败 | 返回类型不支持 | 转为 str 或 dict |
| 超时断开 | 工具执行太慢 | 改 async + 设 timeout |
| 权限拒绝 | 文件路径受限 | 配置允许访问的目录 allowlist |
FROM python:3.12-slim WORKDIR /app COPY requirements.txt . RUN pip install -r requirements.txt COPY . . EXPOSE 8000 CMD ["python", "server.py"]
部署选项：Railway / Render（个人项目一键部署）、AWS Lambda / Google Cloud Run（Serverless）、自建 VPS（Nginx 反向代理）。监控用结构化日志、Prometheus 指标、Sentry 告警与健康检查接口。版本管理须声明 MCP 协议版本，升级工具时保持向后兼容。
需求：让 AI 搜索本地 Markdown 笔记、语义检索、创建与更新笔记。技术选型：ChromaDB / Qdrant 向量库、text-embedding-3-small 嵌入、watchfiles 监听文件变化。核心实现：笔记索引工具、语义搜索工具、笔记写入工具、文件资源服务。效果：在 Cursor 中问「我上周记录了什么关于 MCP 的笔记？」，Agent 调用搜索工具返回相关片段。
2026 年主流 AI 客户端（Cursor、Claude Desktop、VS Code、OpenAI、Gemini）均已支持 MCP；MCP Marketplace 与企业级安全标准快速发展。下一步：深入学习协议规范、发布公开 Server、探索 MCP + Agent 组合、贡献开源生态。配套资源：Python SDK、TypeScript SDK、MCP Inspector。
tools/list 运行时拉取。笔记本适合 MCP POC，却在合盖休眠、缺少 macOS 原生工具链与长期进程守护上削弱 7×24 体验；纯 Linux VPS 能跑 HTTP+SSE，却难承载 Keychain、Xcode 等 macOS 依赖的 MCP 工具。对要把多个 MCP Server 当「常驻基础设施」、让 Agent 跨周累积工具调用复利的技术团队，VpsMesh Mac Mini M4 云端租赁把 uptime、远程 KVM 与可预期月租打包成生产级 OpEx。套餐见 Mac Mini M4 租赁价格，部署问题见 帮助中心。
Python 官方 SDK mcp 配合 FastMCP 上手最快，适合后端与 AI 工程师。TypeScript SDK @modelcontextprotocol/sdk 适合前端与全栈。二者协议层完全兼容，逻辑可对照迁移。若团队主力是 Node 全栈，选 TS；若以数据 / ML 为主，选 Python。
Tools 是动作执行者——AI 调用后会改变外部状态或触发计算（搜索、写文件、发请求）。Resources 是数据提供者——通过 URI 只读获取内容，如 config://app-settings 或 user://{id}/profile。简单记忆：读数据用 Resource，做动作用 Tool。
HTTP+SSE 模式可部署在 Railway、Cloud Run 或 Linux VPS。若 MCP 工具链依赖 macOS 原生能力、Keychain 或你希望 Cursor Agent 与多个 Server 7×24 不被合盖打断，Mac Mini M4 月租更省心。建议先租 1 个月验证 tools/call 曲线，套餐见 Mac Mini M4 租赁价格，下单见 订购页。