MCP开发-03.部署方式与调用配置

发表于 | 分类于
梳理 MCP Server 部署模式（stdio 按需、内网常驻、Docker、Serverless、Registry）与 Streamable HTTP 有/无状态选择，并给出 Host 侧调用配置与生产清单。

本系列：00 什么是 MCP · 01 协议与心智模型 · 02 Python 框架选型 · 03 部署与调用（本文） · 04 重任务与优化 · 05 从 0 开发 · 06 进阶示例 · 07 阿里云案例

1. 核心结论

并非只有「内网服务器常驻」一种部署方式。 MCP 允许的进程模型取决于传输层：

传输 谁启动 Server 典型部署
stdio Host 按需拉起子进程 本地 IDE、个人工具；无独立 URL
Streamable HTTP 独立进程（你部署） 内网服务、容器、Serverless、边缘 Worker

远程访问 必须 Streamable HTTP；stdio 无法跨网络。旧版 HTTP+SSE（2024-11-05）已弃用。

段末注释：Streamable HTTP 是 MCP 规范定义的远程标准传输，使用单一 HTTP 端点承载 JSON-RPC 与可选 SSE 流。

2. 部署模式矩阵

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
flowchart TB
  subgraph local [本机]
    Stdio["stdio\nHost 子进程"]
  end
  subgraph remote [远程]
    VPS["内网/VPS 常驻"]
    Docker["Docker / K8s / Cloud Run"]
    Serverless["Lambda / Workers\n无状态 HTTP"]
    Registry["Registry 元数据分发"]
  end
  Host["MCP Host"] --> Stdio
  Host --> VPS
  Host --> Docker
  Host --> Serverless
  Registry -.->|安装命令或 URL| Host
部署模式 传输 进程模型 Host 调用方式 适用
Host 按需拉起 stdio 随 Host 启停 command + args Cursor、Claude Desktop 本地开发
内网常驻服务 Streamable HTTP 单进程或多实例 url 指向 MCP 端点 团队内网、API 网关后
Docker / K8s / Cloud Run Streamable HTTP 容器编排、水平扩展 HTTPS URL + 认证 生产、可观测、滚动发布
Serverless Streamable HTTP 无状态 按请求冷启动 API Gateway URL 低频工具、无会话
Registry 发布 元数据 + 上述任一 分发描述 客户端发现安装命令或 URL 开源、团队工具目录

选型关键：是否有会话状态、调用频率、是否长任务（长任务见 04）。

3. 模式一：stdio（Host 按需拉起）

3.1 Server 侧

1
2
3
4
5
6
7
8
9
10
11
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my_tool")

@mcp.tool()
def hello(name: str) -> str:
    """问候。"""
    return f"Hello, {name}"

if __name__ == "__main__":
    mcp.run(transport="stdio")
  • 无 host/port；日志写 stderr，勿污染 stdout。
  • 重计算 不建议 绑在 stdio 单进程上（阻塞 Host、难扩展）。

3.2 Host 侧（结构示例）

字段名因产品而异（mcpServers / servers 等），以下为常见形态：

Cursor（.cursor/mcp.json 或用户设置，示例）：

1
2
3
4
5
6
7
8
{
  "mcpServers": {
    "my_tool": {
      "command": "/abs/path/to/project/.venv/bin/python",
      "args": ["/abs/path/to/server.py"]
    }
  }
}

Claude Desktop（claude_desktop_config.json，示例）：

1
2
3
4
5
6
7
8
{
  "mcpServers": {
    "my_tool": {
      "command": "/abs/path/to/project/.venv/bin/python",
      "args": ["/abs/path/to/server.py"]
    }
  }
}

要点：command 用 虚拟环境 Python 绝对路径；args 用脚本绝对路径。

4. 模式二：Streamable HTTP（远程）

4.1 Server 侧（开发机快速启动）

1
2
3
if __name__ == "__main__":
    mcp.run(transport="streamable-http")
    # 默认常监听 http://127.0.0.1:8000/mcp，以 SDK 日志为准

生产还可关注 SDK 参数（名称以当前版本为准）：

参数 / 模式 含义
stateless_http=True 不签发 Session ID；每请求独立，Serverless 必选
有 Session（默认部分场景） MCP-Session-Id 粘性；多实例需粘性负载或 Redis
json_response 部分场景用单 JSON 响应代替 SSE 流

2026 演进：协议趋向无会话；新部署建议优先无状态（见 01 §8）。

4.2 Host 侧（HTTP URL）

Claude Code（示例）：

1
claude mcp add --transport http my-remote https://mcp.example.com/mcp

Cursor（示例，部分版本支持 url）：

1
2
3
4
5
6
7
{
  "mcpServers": {
    "my_remote": {
      "url": "https://mcp.example.com/mcp"
    }
  }
}

需认证时在 Host 或网关配置 Bearer Token / OAuth（视产品支持而定）。

4.3 安全基线

  • 生产 HTTPS + 认证。
  • 校验 Origin 头（规范要求，防 DNS rebinding）。
  • 本地开发绑定 127.0.0.1，避免无意暴露局域网。

5. 模式三：Docker / 容器编排

5.1 典型 Dockerfile 要点

1
2
3
4
5
6
7
FROM python:3.12-slim
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN pip install uv && uv sync --frozen
COPY . .
EXPOSE 8000
CMD ["uv", "run", "python", "server.py"]

server.py 入口使用 streamable-http，监听 0.0.0.0（容器内）时需在 SDK 或反向代理中显式配置 host。

5.2 有状态 vs 无状态

场景 建议
单副本 Cloud Run / VM 可有 Session
K8s 多副本、无粘性 stateless_http 或 Redis 共享 Session
长任务 + Worker 池 HTTP 入口无状态 + 后台队列（见 04）

5.3 生产清单

  • TLS 终止（Ingress / 负载均衡）
  • /health 健康检查（非 MCP 标准，但运维需要）
  • 结构化日志 + 请求 ID
  • 资源 limit（CPU / 内存）
  • 重任务与 MCP 进程分离

6. 模式四：Serverless

Serverless（AWS Lambda、Cloudflare Workers 等）执行环境 按请求重置，内存 Session 无法跨调用保留。

必须：

  1. transport="streamable-http" + stateless_http=True（或 SDK 等价：不生成 sessionId）。
  2. 工具逻辑 无会话依赖；状态放外部存储（S3、DynamoDB、Redis）。
  3. 注意平台 超时（如 Lambda 15 分钟上限、Workers CPU 限制）；超长任务用 Tasks + 外部队列。

架构示意：

1
2
3
4
5
6
7
8
9
10
11
sequenceDiagram
    participant Client as MCP_Client
    participant GW as API_Gateway
    participant Fn as Lambda_MCP
    participant Store as External_Store

    Client->>GW: POST /mcp tools/call
    GW->>Fn: 无状态 invocation
    Fn->>Store: 读/写（如需）
    Fn->>GW: JSON / SSE 响应
    GW->>Client: 结果

7. 模式五：Registry 发布

MCP Registry 用于分发 Server 元数据（名称、描述、安装方式、传输类型），不替代实际托管。

典型条目包含：

  • stdio：command / args 模板（如 uvx、npx 包装）
  • HTTP：服务 url 与认证说明

适合开源工具、团队内部目录；与 Docker 镜像或 PyPI 包配合使用。

8. 自检与调试

8.1 MCP Inspector

HTTP 服务启动后：

1
npx -y @modelcontextprotocol/inspector

在 UI 填入 MCP 端点 URL，测试 tools/list 与 tools/call。

8.2 curl 探测（Streamable HTTP）

具体 JSON-RPC body 与头以 spec 为准；可用于确认端点是否可达、是否返回 403 Origin 错误等。

8.3 stdio 排错顺序

  1. 进程是否被 Host 拉起？
  2. initialize 是否成功？
  3. tools/list 是否含预期工具？
  4. 单次 tools/call 参数与返回是否正常？

更多现象见 05 排错表。

9. 部署 × 传输 × 调用对照表

你想… 传输 Server 部署 Host 配置关键字
只在 Cursor 本机用 stdio 无需部署，Host 拉起 command, args
团队共享同一 URL Streamable HTTP VPS / Docker url
自动扩缩、按量计费 Streamable HTTP 无状态 Lambda / Workers url + 网关认证
发布给社区安装 元数据 + stdio 或 HTTP Registry + 包管理器 依 Registry 文档

10. 小结

  • 本地个人：stdio，零运维。
  • 远程共享 / 生产：Streamable HTTP + HTTPS + 认证。
  • Serverless：无状态 HTTP，状态外置，注意超时。
  • 长任务：HTTP 入口 + Tasks / 队列，勿在 stdio 单进程硬扛。

上一篇：02 Python 框架选型 · 下一篇：04 重服务与长任务 · 实践：05 从 0 开发

-------------本文结束感谢您的阅读-------------