若你有 Python 或 TypeScript 基础，却苦于 Claude / Cursor 无法查数据库、调内部 API、读写项目文件——本文给出可独立部署的生产级 MCP Server 全流程。① 先搞懂 MCP 协议（Function Calling → Plugins → MCP 演进、JSON-RPC、三大原语）；② 用 FastMCP 从 Hello World 到 Tools / Resources / Prompts 全栈实现；③ 经 MCP Inspector 调试、HTTP+SSE 远程部署、Docker 上线，并完成 ChromaDB 个人知识库实战。协议层「为何是 AI 时代 HTTP」见MCP 协议解读；与Agent Skill 指南互补。
tools/list 与 JSON-RPC 生命周期，「工具不出现」排错动辄数小时。大模型「不够聪明」的根因之一：缺乏访问外部工具与实时数据的能力。你希望让 AI 查库、调 API、操作文件——这正是 MCP（Model Context Protocol）要标准化的通信层。
工具调用能力演进路径：Function Calling → Plugins → MCP。Anthropic 于 2024 年 11 月开源 MCP，解决 AI 与外部工具之间缺乏统一协议的问题。2026 年 OpenAI、Google、Microsoft 全面入局，生态已超 10,000 个 Server（详见协议深度文）。
Client（Claude Desktop、Cursor、自定义客户端）与 Server（你开发的部分）经 JSON-RPC 2.0 通信。Server 向下对接三大核心能力：
stdio（本地进程）、HTTP + SSE（远程服务）| 对比维度 | MCP | OpenAI Function Calling | LangChain Tools |
|---|---|---|---|
| 标准化 | 开放协议标准 | 厂商私有 | 框架绑定 |
| 传输 | stdio / HTTP | HTTP | HTTP |
| 跨模型 | 是 | 否 | 部分 |
| Resources / Prompts | 原生支持 | 不支持 | 不支持 |
| 生态 | 快速增长（2026 万级 Server） | 成熟 | 成熟 |
mcp / FastMCP，简洁易上手@modelcontextprotocol/sdk本文以 Python FastMCP 为主，TypeScript 做对照说明。
# Python python -m venv .venv && source .venv/bin/activate pip install "mcp[cli]" fastmcp httpx pydantic uvicorn # TypeScript（对照） npm init -y && npm install @modelcontextprotocol/sdk
my-mcp-server/ ├── server.py # 主入口 ├── tools/ # 计算器、搜索、HTTP 等 ├── resources/ # 文件读取 ├── prompts/ # 提示词模板 ├── tests/test_tools.py ├── pyproject.toml └── README.md
npx @modelcontextprotocol/inspector 官方调试 UIclaude_desktop_config.json 联调~/.cursor/mcp.json 或项目级 .cursor/mcp.jsonfrom 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()
python server.py # 或 Inspector 调试 npx @modelcontextprotocol/inspector python server.py
{
"mcpServers": {
"my-first-server": {
"command": "/path/to/.venv/bin/python",
"args": ["/path/to/server.py"]
}
}
}
函数签名即文档：参数类型、返回类型、docstring 会生成 JSON Schema 供模型阅读。支持 Pydantic 复杂入参：
from pydantic import BaseModel, Field
class SearchInput(BaseModel):
query: str = Field(description="搜索关键词")
max_results: int = Field(default=5, description="最多返回结果数")
@mcp.tool()
def web_search(input: SearchInput) -> list[dict]:
"""执行网络搜索，返回相关结果列表"""
...
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
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）、流式实时数据。文件系统实战：列出目录、读取内容、可选订阅文件变化。
预定义片段，支持动态参数注入，提升一致性与可维护性。多轮模板可包含 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```"
)
)
]
| 原语 | RPC 方法 | 典型场景 |
|---|---|---|
| Tools | tools/list, tools/call | 查库、发 Webhook、写文件 |
| Resources | resources/list, resources/read | 只读文档、配置快照 |
| Prompts | prompts/list, prompts/get | 代码审查、事故复盘模板 |
| 特性 | stdio | HTTP + SSE |
|---|---|---|
| 部署 | 本地进程 | 远程服务器 |
| 延迟 | 极低 | 依赖网络 |
| 多客户端 | 不支持 | 支持 |
| 适用 | 本地 Cursor / Claude | SaaS / 团队共享 |
mcp = FastMCP("remote-server")
if __name__ == "__main__":
mcp.run(transport="streamable-http", host="0.0.0.0", port=8000)
生产安全：Bearer Token、API Key 中间件、CORS、请求频率限制。2026 年初调研显示约 1,000 个 MCP Server 公网暴露且未鉴权——切勿裸奔上线。
MCP Inspector 流程：启动 → 测试 tools/call → 查看请求/响应日志 → 模拟错误场景。单元测试示例：
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 result.content[0].text == "4"
| 错误 | 原因 | 解决方案 |
|---|---|---|
| 工具未出现在 AI 中 | 配置路径错误 | 检查 mcp.json / config.json 路径 |
| JSON 序列化失败 | 返回类型不支持 | 转为 str 或 dict |
| 超时断开 | 工具执行太慢 | 异步 + 超时控制 |
| 权限拒绝 | 文件路径受限 | 配置允许访问目录白名单 |
Docker 容器化、Railway / Render 一键部署、AWS Lambda / Cloud Run Serverless、自建 VPS + Nginx 反向代理。监控：结构化日志、Prometheus 工具调用指标、Sentry 错误告警、健康检查接口。版本管理：声明 MCP 协议版本、向后兼容的工具升级、能力协商。
FROM python:3.12-slim WORKDIR /app COPY requirements.txt . RUN pip install -r requirements.txt COPY . . EXPOSE 8000 CMD ["python", "server.py"]
需求：让 AI 搜索本地 Markdown 笔记、语义检索、创建/更新笔记。
技术选型：ChromaDB / Qdrant 向量库、text-embedding-3-small 嵌入、watchfiles 监听文件变化。
~/notes/**/*.md 写入向量库note://{slug} 经 resources/read 暴露效果：在 Cursor 中问「我上周关于 MCP 记了什么？」——AI 调用搜索工具返回笔记片段。官方资源：modelcontextprotocol.io、Python SDK、MCP Inspector。
mcp-server-filesystem、mcp-server-github、mcp-server-brave-search、mcp-server-postgres、mcp-server-slackMCP 与 Agent Skill（SKILL.md） 互补：Skill 是宿主内能力包；MCP 是跨宿主工具协议。
tools/list。本地 STDIO 适合 Hello World；生产会在三处翻车：合盖杀子进程与 SSE、共享开发机 Python 漂移、多步 Agent 需数小时不间断在线。笔记本与 Docker Desktop 混跑 HTTP Server 长期稳定性不足；团队共用的开发机权限边界模糊，也不适合承载生产级 MCP 会话。
对需要稳定 MCP 长连接与 Agent 编排的环境，把 Server 落在 MACCOME Mac mini（M4 / M4 Pro）独占云主机上，通常比在本地与睡眠策略搏斗更省总成本。公开档位见租赁价格说明，接入见帮助中心。
掌握 MCP Server 开发，是 2026 年 AI 工程师的核心竞争力之一。你打算用 MCP 开发什么工具？从本篇的 Hello World 开始，下周就能在 Cursor 里用上自己的第一个 Server。
常见问题
Python FastMCP 和 TypeScript MCP SDK 该选哪个？
后端优先 FastMCP：装饰器注册三大原语、内置 STDIO/HTTP+SSE、Cursor 兼容好。Node 团队用 @modelcontextprotocol/sdk 封装现有 API。
MCP Tools、Resources、Prompts 有什么区别？
Tools 执行有副作用的操作；Resources 提供只读 URI 内容；Prompts 返回可注入对话的模板——见上文第四至六节。
和 Agent Skill（SKILL.md）什么关系？
Skill 是 Cursor 内能力包；MCP 是跨宿主工具标准。详见Agent Skill 指南。
生产环境 MCP Server 该跑在哪？
避免笔记本合盖断连。MACCOME M4/M4 Pro 云 Mac 适合 7×24 MCP 与 Agent。报价见租赁价格页。