---
name: deploy-minimal-mcp
description: 部署一个最小可用的 MCP Server 时使用。当需要让 Claude/Agent 连接一个自定义数据源或工具、要演示 MCP 全链路、或准备 FDE 面试作品时，按此步骤执行。目标：半天内跑通 Host→Client→Server。
tags: [mcp, agent, deployment, python]
category: skills
---


# 部署一个最小 MCP Server

目标：半天内跑通 MCP 全链路（Host → Client → Server），让 Claude 查到你自己的数据源。这是 Anthropic 点名的 FDE 交付物之一。

## 第零步：理解三角色

- **Host**：发起对话的 AI 应用（Claude Desktop / Claude Code）
- **Client**：Host 内部维持与 Server 的连接
- **Server**：你写的，暴露 tools（可被调用的函数），每个 tool 要有清晰描述

协议规范：https://modelcontextprotocol.io

## 第一步：安装官方 Python SDK

```bash
pip install "mcp[cli]"
```

## 第二步：写最小 Server（约 40 行）

```python
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("demo-data")

@mcp.tool()
def query_orders(customer_id: str) -> str:
    """按客户 ID 查询订单列表。返回 JSON 字符串。"""
    # 生产里这里换成真实数据源：SQLite / 内部 API / 数据库
    return '{"orders": [{"id": "A1001", "amount": 299}]}'

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

关键：**docstring 就是给模型看的工具说明书**，写清"干什么、参数含义、返回什么"——模型靠它决定何时调用。

## 第三步：接入 Host 验证

Claude Desktop 配置（`claude_desktop_config.json`）：

```json
{
  "mcpServers": {
    "demo-data": {
      "command": "python",
      "args": ["path/to/server.py"]
    }
  }
}
```

重启 Claude Desktop，看到工具图标出现即接入成功。测试问句："帮我查客户 A1001 的订单"。

## 第四步：升级为"作品集级"

1. 换真实数据源（公司测试库 / 公开数据集）
2. 加错误处理：数据源挂了返回可读错误，而不是让 Agent 猜
3. 加只读约束：第一版只给查询工具，不给写工具——现场演示时这是安全加分项
4. 写一份 README：架构图 + 三个角色在哪 + 你踩的坑

## 常见坑

- Windows 下 command 用 `python` 全路径（虚拟环境路径问题）
- 工具没出现：先看 Host 日志，多半是 server 启动即崩（import 错误）
- 描述含糊会导致模型"该调不调"——改 docstring 比改代码更常见效

## 参考

- 官方文档：https://modelcontextprotocol.io
- MCP for Beginners（多语言教程）：https://github.com/microsoft/mcp-for-beginners
- Awesome MCP Servers（找现成轮子）：https://github.com/punkpeye/awesome-mcp-servers