MCP Server 工程避坑指南：我踩过的 8 个生产级陷阱

本文面向已经了解 MCP 基础概念、准备或正在构建 MCP Server 的工程师。不会重复官方文档——每一节都是我在实际工程中碰过壁的地方。

Model Context Protocol（MCP）自 2024 年底 某海外 AI 公司发布以来，以惊人的速度成为 AI Agent 工具接入的事实标准。到 2025 年底，GitHub 上已有数千个 MCP Server 实现，主流 AI 应用（主流 AI IDE 和桌面助手）都已原生支持。

但"生态繁荣"和"生产可用"之间，有一条很深的沟。

我在过去几个月里构建了 5 个线上运行的 MCP Server，踩过了工具定义爆 token、SSE 连接泄漏、并发安全、版本协商失败等一系列坑。这篇文章把最值得记录的 8 个问题系统梳理一遍，附上可以直接用的修复代码。

---

坑 1：工具定义太详细，token 爆了

问题现场

你连接了 20 个 MCP Server，每个暴露 30 个工具。MCP Client 把所有工具 schema 一起塞进 system prompt——这意味着模型在看用户第一句话之前，就已经消耗了 6 万 token 的工具描述。

官方 benchmark 数据显示：当工具数超过 100 个时，加载时间和推理成本呈超线性增长。

# 反例：过度描述的工具定义
@server.call_tool()
async def handle_query_database(name: str, arguments: dict) -> list[types.TextContent]:
    ...

# tools 列表中这样注册：
types.Tool(
    name="query_database",
    description="""
    这是一个功能强大的数据库查询工具，支持 MySQL、PostgreSQL、SQLite 等多种数据库类型。
    你可以使用标准 SQL 语法进行查询，支持 JOIN、子查询、聚合函数、窗口函数等高级特性。
    查询结果以 JSON 格式返回，包含列名和行数据。支持分页，每次最多返回 1000 行。
    注意事项：请确保 SQL 语句安全，避免 SQL 注入...（以下省略 200 字）
    """,
    inputSchema={...}  # 又是一个复杂 JSON Schema
)

修复方案

原则：工具描述短于 50 字，schema 字段不超过 5 个。把细节移到 resource 里。

# 正例：精简描述
types.Tool(
    name="query_database",
    description="执行 SQL 查询，返回 JSON 格式结果（最多 1000 行）。",
    inputSchema={
        "type": "object",
        "properties": {
            "sql": {
                "type": "string",
                "description": "SQL 查询语句"
            },
            "limit": {
                "type": "integer",
                "description": "最大返回行数，默认 100",
                "default": 100
            }
        },
        "required": ["sql"]
    }
)

同时，如果你的工具真的很复杂，考虑 协议设计文档中提到的「代码执行模式」：让模型写一段调用工具的代码，由 sandbox 执行，中间结果不经过 context window——这在工具数量超过 200 个时能节省 60% 以上的 token 消耗。

---

坑 2：SSE 传输模式下的连接泄漏

问题现场

用 SSE（Server-Sent Events）模式部署 MCP Server 后，运行一周，服务器 fd（文件描述符）耗尽，进程崩溃。

原因：SSE 是长连接，Client 断开后 Server 端不一定能及时感知。加上部分 MCP Client 实现有 bug，会在重连时不关闭旧连接。

# 危险写法：没有连接生命周期管理
from mcp.server.sse import SseServerTransport

app = Starlette()
sse = SseServerTransport("/messages")

@app.route("/sse")
async def handle_sse(request):
    async with sse.connect_sse(request.scope, request.receive, request._send) as streams:
        await server.run(streams[0], streams[1], InitializationOptions(...))
    # 问题：异常时 streams 可能不会被正确清理

修复方案

import asyncio
import weakref
from contextlib import asynccontextmanager
from starlette.applications import Starlette
from starlette.routing import Route

# 用 weakref 跟踪活跃连接，避免内存泄漏
_active_connections: weakref.WeakSet = weakref.WeakSet()

@asynccontextmanager
async def managed_sse_connection(sse_transport, request):
    """带超时和清理的 SSE 连接管理器"""
    connection_id = id(request)
    try:
        async with asyncio.timeout(3600):  # 1小时超时
            async with sse_transport.connect_sse(
                request.scope, request.receive, request._send
            ) as streams:
                _active_connections.add(streams)
                yield streams
    except asyncio.TimeoutError:
        pass  # 正常超时，不报错
    except Exception as e:
        logger.error(f"SSE connection {connection_id} error: {e}")
        raise
    finally:
        logger.info(f"SSE connection {connection_id} cleaned up. "
                    f"Active: {len(_active_connections)}")

async def handle_sse(request):
    async with managed_sse_connection(sse, request) as streams:
        await server.run(
            streams[0], streams[1],
            InitializationOptions(server_name="my-server", server_version="1.0.0")
        )

同时，在 nginx/caddy 层加上连接超时配置：

# nginx.conf
location /sse {
    proxy_pass http://localhost:8080;
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
    # 关键：告诉 nginx 这是 SSE，不要缓冲
    proxy_buffering off;
    proxy_cache off;
    proxy_set_header X-Accel-Buffering no;
}

---

坑 3：并发工具调用的竞态条件

问题现场

MCP 协议本身支持并发请求（同一连接上多个 in-flight 的 JSON-RPC 请求）。当 AI Agent 同时发起 3 个工具调用时，如果你的 Server 代码共享了可变状态，就会出现数据竞争。

# 危险：共享可变状态
class DatabaseServer:
    def __init__(self):
        self.connection = create_db_connection()  # 单个连接
        self.last_query_result = None  # 共享状态
    
    @server.call_tool()
    async def query(self, name, arguments):
        # 危险：多个并发请求共享 self.connection
        cursor = self.connection.cursor()
        cursor.execute(arguments["sql"])
        self.last_query_result = cursor.fetchall()  # 竞态！
        return self.last_query_result

修复方案

使用连接池，彻底消除共享可变状态：

import asyncpg
from contextlib import asynccontextmanager

class DatabaseServer:
    def __init__(self):
        self._pool: asyncpg.Pool | None = None
    
    async def initialize(self):
        self._pool = await asyncpg.create_pool(
            dsn=os.getenv("DATABASE_URL"),
            min_size=2,
            max_size=10,
            command_timeout=30
        )
    
    @asynccontextmanager
    async def get_connection(self):
        """每次调用获取独立连接，用完归还池"""
        async with self._pool.acquire() as conn:
            yield conn
    
    async def handle_query(self, name: str, arguments: dict):
        async with self.get_connection() as conn:
            # 每个并发调用有自己的 conn，无竞态
            rows = await conn.fetch(arguments["sql"])
            return [types.TextContent(
                type="text",
                text=json.dumps([dict(row) for row in rows], ensure_ascii=False)
            )]

对于非数据库场景（如文件操作），使用 asyncio.Lock 或 asyncio.Semaphore 做细粒度控制：

import asyncio

class FileServer:
    def __init__(self):
        self._write_locks: dict[str, asyncio.Lock] = {}
    
    def _get_lock(self, filepath: str) -> asyncio.Lock:
        if filepath not in self._write_locks:
            self._write_locks[filepath] = asyncio.Lock()
        return self._write_locks[filepath]
    
    async def handle_write_file(self, name: str, arguments: dict):
        path = arguments["path"]
        async with self._get_lock(path):  # 同一文件串行写
            async with aiofiles.open(path, "w") as f:
                await f.write(arguments["content"])
        return [types.TextContent(type="text", text=f"写入成功：{path}")]

---

坑 4：协议版本协商失败的沉默错误

问题现场

某次更新 MCP SDK 后，Server 无法与旧版 Client 建立连接，但没有任何错误日志——连接就这样安静地失败了。

原因：MCP 协议在 initialize 握手阶段有版本协商逻辑，如果 Client 和 Server 的 protocolVersion 不兼容，连接会被拒绝，但默认日志级别不会打印细节。

# 查看握手请求的实际内容（调试用）
import logging
logging.basicConfig(level=logging.DEBUG)

# 在 server 初始化时打印协议版本
@server.list_tools()
async def handle_list_tools() -> list[types.Tool]:
    # 第一个被调用的方法之一，在这里打日志确认连接已建立
    logger.info("list_tools called — connection established successfully")
    return [...]

修复方案

显式处理版本兼容性，并加入结构化日志：

from mcp.server import Server
from mcp.types import InitializeResult, ServerCapabilities
import structlog

logger = structlog.get_logger()

# 显式声明支持的协议版本
SUPPORTED_PROTOCOL_VERSIONS = ["2024-11-05", "2025-03-26"]

async def create_server():
    server = Server("my-mcp-server")
    
    # 监控 initialize 事件
    original_handle = server._handle_initialize
    
    async def logged_initialize(params):
        client_version = params.protocolVersion
        logger.info(
            "mcp_initialize",
            client_version=client_version,
            supported_versions=SUPPORTED_PROTOCOL_VERSIONS,
            compatible=client_version in SUPPORTED_PROTOCOL_VERSIONS
        )
        
        if client_version not in SUPPORTED_PROTOCOL_VERSIONS:
            logger.warning(
                "mcp_version_mismatch",
                client_version=client_version,
                will_attempt="best-effort"
            )
        
        return await original_handle(params)
    
    server._handle_initialize = logged_initialize
    return server

同时在部署时锁定 SDK 版本，避免自动升级破坏生产环境：

# pyproject.toml
[project]
dependencies = [
    "mcp>=1.3.0,<2.0.0",  # 锁定主版本
]

---

坑 5：Resource URI 设计混乱，导致 LLM 无法正确引用

问题现场

把 Resource URI 设计成数据库自增 ID（resource://item/12345），之后数据库迁移后 ID 变了，所有历史对话中的资源引用全部失效。

更严重的问题：LLM 在引用 resource 时，如果 URI 不够语义化，它根本不知道该请求哪个 resource。

修复方案

原则：Resource URI 必须语义化、稳定、人类可读。

# 反例：不透明 URI
"resource://db/12345"           # ID 是什么？
"resource://cache/a3f9b2"       # 哈希是什么？

# 正例：语义化 URI
"resource://github/repos/octocat/hello-world/readme"    # 明确
"resource://local/projects/myapp/src/main.py"           # 明确
"resource://jira/projects/PROJ/issues/PROJ-123"         # 明确

# Python 示例：动态生成语义化 URI
def make_resource_uri(resource_type: str, *path_components: str) -> str:
    """生成稳定的语义化 resource URI"""
    # 规范化路径组件，去掉特殊字符
    clean_parts = [
        re.sub(r'[^\w\-./]', '_', str(p)).strip('/')
        for p in path_components
    ]
    return f"resource://{resource_type}/{'/'.join(clean_parts)}"

# 用法
uri = make_resource_uri("github", "repos", owner, repo, "contents", filepath)
# → "resource://github/repos/octocat/hello-world/contents/README.md"

同时，在 list_resources 返回时加入 mimeType 提示，帮助 LLM 理解资源类型：

@server.list_resources()
async def handle_list_resources() -> list[types.Resource]:
    return [
        types.Resource(
            uri=AnyUrl(make_resource_uri("local", "docs", "api.md")),
            name="API 文档",
            description="项目的 REST API 接口文档",
            mimeType="text/markdown"  # 关键：告诉 LLM 这是什么格式
        ),
        types.Resource(
            uri=AnyUrl(make_resource_uri("local", "data", "config.json")),
            name="配置文件",
            description="应用运行时配置",
            mimeType="application/json"
        ),
    ]

---

坑 6：工具返回值太大，上下文窗口撑爆

问题现场

工具返回了整个数据库表的内容（10MB JSON），MCP Client 把它塞进 context，下一轮对话直接 OOM 或 token 超限报错。

修复方案

分页 + 截断 + 摘要三层防护：

from dataclasses import dataclass
from typing import Any

MAX_TOOL_RESULT_CHARS = 8000  # 约 2000 token

@dataclass
class PaginatedResult:
    data: list[Any]
    total: int
    page: int
    page_size: int
    has_more: bool

def truncate_result(result: Any, max_chars: int = MAX_TOOL_RESULT_CHARS) -> str:
    """智能截断工具结果，保留结构信息"""
    text = json.dumps(result, ensure_ascii=False, indent=2)
    
    if len(text) <= max_chars:
        return text
    
    # 截断并附加提示
    truncated = text[:max_chars]
    # 找到最后一个完整的 JSON 边界
    last_brace = max(truncated.rfind('}'), truncated.rfind(']'))
    if last_brace > max_chars * 0.8:
        truncated = truncated[:last_brace + 1]
    
    char_count = len(text)
    return (
        truncated + 
        f"\n\n... [结果已截断：共 {char_count} 字符，显示前 {len(truncated)} 字符。"
        f"使用 offset 参数获取更多结果。]"
    )

async def handle_query_database(name: str, arguments: dict):
    page = arguments.get("page", 1)
    page_size = min(arguments.get("page_size", 50), 200)  # 上限 200 行
    offset = (page - 1) * page_size
    
    async with db.get_connection() as conn:
        total = await conn.fetchval(
            f"SELECT COUNT(*) FROM ({arguments['sql']}) AS q"
        )
        rows = await conn.fetch(
            f"{arguments['sql']} LIMIT {page_size} OFFSET {offset}"
        )
    
    result = PaginatedResult(
        data=[dict(r) for r in rows],
        total=total,
        page=page,
        page_size=page_size,
        has_more=(offset + page_size) < total
    )
    
    output = truncate_result(dataclasses.asdict(result))
    return [types.TextContent(type="text", text=output)]

---

坑 7：stdio 模式下 print 调试语句破坏协议

问题现场

在 stdio 传输模式下，MCP 通过 stdout 发送 JSON-RPC 消息。如果你在代码里随手加了一句 print("调试信息")，这段文本会混入协议消息流，导致 Client 解析失败，表现为工具调用后没有响应，或者 Client 崩溃。

这个 bug 的坑在于：本地测试时 Client 如果有容错处理，可能正常工作，但换一个 Client 就崩了。

# 致命错误：stdio 模式下禁止向 stdout 打印任何内容
@server.call_tool()
async def handle_search(name: str, arguments: dict):
    print(f"DEBUG: searching for {arguments['query']}")  # 💀 破坏协议！
    results = await do_search(arguments["query"])
    print(f"DEBUG: found {len(results)} results")        # 💀 同上
    return [types.TextContent(type="text", text=str(results))]

修复方案

所有日志必须写 stderr，永远不要用 print。

import logging
import sys

# 在程序入口配置日志到 stderr
logging.basicConfig(
    stream=sys.stderr,          # 关键：输出到 stderr，不是 stdout
    level=logging.DEBUG,
    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s"
)

logger = logging.getLogger(__name__)

@server.call_tool()
async def handle_search(name: str, arguments: dict):
    logger.debug("searching for: %s", arguments["query"])   # ✅ 安全
    results = await do_search(arguments["query"])
    logger.info("found %d results", len(results))           # ✅ 安全
    return [types.TextContent(type="text", text=str(results))]

如果你用的是第三方库，注意检查它们是否有意外的 stdout 输出：

# 重定向整个 stdout，防止第三方库污染
import sys
import io

class StdoutGuard:
    """在 stdio MCP 模式下保护 stdout 不被意外写入"""
    
    def __init__(self, real_stdout):
        self._real_stdout = real_stdout
        self._buffer = io.StringIO()
    
    def write(self, text):
        # 只有 JSON-RPC 消息（以 {" 开头）才允许写 stdout
        if text.strip().startswith('{"'):
            self._real_stdout.write(text)
        else:
            # 重定向到 stderr 并报警
            sys.stderr.write(f"[STDOUT_GUARD] Intercepted: {repr(text[:100])}\n")
    
    def flush(self):
        self._real_stdout.flush()

# 在 main 函数顶部安装 guard
if os.getenv("MCP_TRANSPORT") == "stdio":
    sys.stdout = StdoutGuard(sys.stdout)

---

坑 8：没有健康检查和 Graceful Shutdown，部署出问题

问题现场

Kubernetes 中部署 SSE 模式的 MCP Server，Pod 重启时正在处理的工具调用直接被杀掉，Client 端报 "connection reset"。同时，没有 /health 端点，负载均衡器无法判断 Server 是否就绪。

修复方案

加入健康检查端点 + 优雅关闭逻辑：

import asyncio
import signal
from starlette.applications import Starlette
from starlette.responses import JSONResponse
from starlette.routing import Route

# 全局状态
_is_shutting_down = False
_active_request_count = 0

async def health_check(request):
    """Kubernetes liveness + readiness probe"""
    if _is_shutting_down:
        return JSONResponse(
            {"status": "shutting_down", "active_requests": _active_request_count},
            status_code=503
        )
    
    # 检查依赖项（数据库、外部 API 等）
    try:
        async with db.get_connection() as conn:
            await conn.fetchval("SELECT 1")
        db_healthy = True
    except Exception as e:
        db_healthy = False
        logger.error("health check db failed: %s", e)
    
    status = "healthy" if db_healthy else "degraded"
    code = 200 if db_healthy else 503
    
    return JSONResponse({
        "status": status,
        "active_requests": _active_request_count,
        "version": "1.0.0"
    }, status_code=code)

async def handle_sse_with_tracking(request):
    global _active_request_count
    
    if _is_shutting_down:
        return JSONResponse({"error": "server shutting down"}, status_code=503)
    
    _active_request_count += 1
    try:
        async with managed_sse_connection(sse, request) as streams:
            await server.run(streams[0], streams[1], init_options)
    finally:
        _active_request_count -= 1

def setup_graceful_shutdown(app):
    """设置优雅关闭：等待活跃请求完成"""
    
    async def shutdown_handler():
        global _is_shutting_down
        _is_shutting_down = True
        logger.info("Shutdown signal received, waiting for active requests...")
        
        # 最多等待 30 秒
        timeout = 30
        while _active_request_count > 0 and timeout > 0:
            logger.info("Waiting... active requests: %d", _active_request_count)
            await asyncio.sleep(1)
            timeout -= 1
        
        logger.info("Graceful shutdown complete")
    
    loop = asyncio.get_event_loop()
    
    def handle_signal(sig):
        logger.info("Received signal: %s", sig)
        loop.create_task(shutdown_handler())
    
    loop.add_signal_handler(signal.SIGTERM, handle_signal, signal.SIGTERM)
    loop.add_signal_handler(signal.SIGINT, handle_signal, signal.SIGINT)

app = Starlette(routes=[
    Route("/health", health_check),
    Route("/sse", handle_sse_with_tracking),
    Route("/messages", sse.handle_post_message, methods=["POST"]),
])

对应的 Kubernetes 配置：

# deployment.yaml
spec:
  containers:
  - name: mcp-server
    livenessProbe:
      httpGet:
        path: /health
        port: 8080
      initialDelaySeconds: 10
      periodSeconds: 30
    readinessProbe:
      httpGet:
        path: /health
        port: 8080
      initialDelaySeconds: 5
      periodSeconds: 10
    lifecycle:
      preStop:
        exec:
          command: ["/bin/sh", "-c", "sleep 5"]  # 给负载均衡摘流时间
  terminationGracePeriodSeconds: 40  # > preStop + shutdown 时间

---

总结：MCP Server 生产就绪检查清单

把上面 8 个坑浓缩成一张可操作的清单：

检查项	验证方式
✅ 工具描述 < 50 字，schema 字段 ≤ 5 个	统计工具定义 token 数
✅ SSE 连接有超时和清理逻辑	压测 + 72h 连接观察
✅ 共享状态使用连接池或 Lock	asyncio 并发测试
✅ 协议版本有结构化日志	查 initialize 握手日志
✅ Resource URI 语义化且稳定	人工 review URI 设计
✅ 工具返回值有截断和分页	测试大结果集返回
✅ stdio 模式下无 print 语句	grep -r "print(" src/
✅ 有 /health 端点 + Graceful Shutdown	Kubernetes 探针测试

MCP 的协议设计是优雅的，但"优雅"和"生产可用"之间永远有工程债。希望这份踩坑记录能帮你少走一些弯路。

---

延伸思考：MCP 的边界在哪里？

在讨论生产坑之余，有一个架构层面的问题值得单独说：MCP 不是 Agent 的全部，别把它当银弹。

MCP vs Function Calling：不是竞争关系

很多工程师上手 MCP 后的第一个疑问：我原来用 Function Calling 好好的，为什么要换？

答案是：不需要换，两者解决的问题层次不同。

• Function Calling 是 LLM 推理层的能力，决定「调什么工具、传什么参数」。这是各家大模型厂商各自实现的推理接口，API 格式不同。
• MCP 是应用层的网络协议，决定「工具怎么被发现、怎么被连接、怎么被调用」。它标准化的是 Agent 宿主和工具服务器之间的通信方式。

两者的关系：Agent 执行任务 → LLM 通过 Function Calling 输出工具调用意图 → 宿主拿到意图后，通过 MCP 路由到对应的 Server → Server 执行并返回结果。

什么时候不该用 MCP？

以下场景用 MCP 是过度工程：

1. 单应用、单模型：如果你的工具只给一个内部应用用，直接写函数就够了，引入 MCP Server 增加了网络跳转和维护成本。
2. 高频低延迟场景：MCP 的 JSON-RPC 通信引入了序列化/反序列化开销。如果一个工具调用需要 < 10ms，本地函数调用比 MCP Server 快 10-100 倍。
3. 工具逻辑高度耦合业务：如果工具需要访问大量内部状态，抽成独立 Server 反而带来状态同步的复杂性。

MCP 真正发光的场景是：工具被多个 AI 应用复用（一份 MCP Server 让主流 AI IDE（Cursor、Windsurf 等）和自研 Agent 都能用），或者团队希望统一管理工具生命周期（版本、权限、日志集中在 Server 侧）。

2026 年的 MCP 生态现状

截至 2026 年上半年，MCP 生态已经相当成熟：

• SDK：Python、TypeScript、Java、Go、Rust 均有官方或社区维护的 SDK
• 客户端支持：Cursor、VS Code Copilot、Windsurf、Zed 等 AI IDE 均原生支持
• 服务器数量：GitHub 上公开的 MCP Server 超过 5000 个，覆盖数据库、文件系统、SaaS API、代码工具等主流场景
• 企业采纳：Cloudflare、Stripe、Atlassian 等已发布官方 MCP Server

这意味着大量「基础设施级」的 MCP Server 已经由社区打磨完善，你自己需要写的更多是「业务逻辑层」的工具——这正是本文 8 个坑聚焦的区域。

---

关联阅读：

• LLM 网关的优雅降级设计：5 层 fallback chain 工程实践
• AI Agent 开发中的模型调度策略
• Prompt Caching 工程实践：把 LLM 调用成本砍掉 80%