从零开发一个 MCP Server：完整实战指南

为什么需要自己开发 MCP Server？

现成的 MCP Server 覆盖了文件系统、GitHub、数据库等通用场景。但当你需要让 Agent 访问你自己业务系统的 API时，就必须开发自定义 MCP Server。比如：

• 调用公司内部订单系统
• 读取自建的知识库
• 操作特定硬件设备

MCP（Model Context Protocol）是 Anthropic 提出的 Agent 工具调用标准协议，已成为事实标准。掌握 MCP Server 开发，就是掌握了 Agent 生态的「连接器」能力。

步骤 1：理解 MCP 协议核心

MCP 基于 JSON-RPC 2.0，通信方式有两种：

• stdio：标准输入输出，适合本地进程间通信
• Streamable HTTP：HTTP + SSE，适合远程服务

一个 MCP Server 可以暴露三类能力：

• Tools：Agent 可调用的函数（最常用）
• Resources：Agent 可读取的数据
• Prompts：预定义的提示模板

步骤 2：用 FastMCP 快速搭建

pip install fastmcp

创建 my_server.py：

from fastmcp import FastMCP

mcp = FastMCP("my-business-api")

@mcp.tool()
def get_order(order_id: str) -> dict:
    """查询订单详情
    
    Args:
        order_id: 订单编号
    """
    # 调用你的业务 API
    import httpx
    resp = httpx.get(f"https://api.mycompany.com/orders/{order_id}")
    return resp.json()

@mcp.tool()
def create_order(product: str, quantity: int) -> dict:
    """创建新订单
    
    Args:
        product: 产品名称
        quantity: 订购数量
    """
    import httpx
    resp = httpx.post("https://api.mycompany.com/orders", json={
        "product": product,
        "quantity": quantity
    })
    return resp.json()

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

步骤 3：配置到 AI Agent

{
  "mcpServers": {
    "my-business": {
      "command": "python",
      "args": ["my_server.py"]
    }
  }
}

步骤 4：测试与调试

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

# 使用 fast-agent 测试
uvx fast-agent-mcp@latest -x
/connect python my_server.py

步骤 5：部署为远程服务

# 修改启动方式为 HTTP
mcp.run(transport="streamable-http", port=8000)

注意事项

• 工具描述是关键：Agent 根据描述决定是否调用你的工具，描述要精确、无歧义
• 参数校验：用 Pydantic 模型定义参数类型，FastMCP 会自动生成 JSON Schema
• 错误处理：工具抛出异常时 MCP 会返回 error，Agent 会据此调整策略
• 安全边界：不要在工具中暴露敏感操作，考虑添加权限校验