适用场景与目标

适用场景：

• 需要让 AI Agent 稳定访问内部工具（数据库、CRM、代码仓库、监控系统）
• 已有 MCP Server，想要从”能跑”升级到”能上线”
• 团队在选型 Agent 工具层协议，MCP vs 自建方案摇摆中

核心目标：

1. 用 MCP 协议将 AI 助手接入真实业务系统
2. 确保传输安全、身份可信、权限最小化
3. 构建可治理、可观测的生产级 MCP 工具访问层

为什么是现在： 2025 年 11 月规范更新后，MCP 已支持异步任务（Tasks）、服务端 Agent 循环增强、采样增强，以及 OAuth 2.1 + PKCE 身份验证。2025 年 12 月 Anthropic 将 MCP 捐赠给 Linux Foundation 下的 Agentic AI Foundation，成为真正的厂商中立标准。2026 年 Q2 生产服务器数量已突破 2000+ 大关，进入大规模验证期。

---

最小可行方案（MVP）步骤

Step 1：选型传输模式

MCP 支持两种传输方式，需根据场景选择：

传输模式	适用场景	特点
STDIO	本地集成，同一机器内通信	零网络开销，单客户端，无需认证
Streamable HTTP	远程服务器，跨机器/多客户端	支持 OAuth 认证、SSE 流式推送，需 HTTPS

MVP 推荐： 开发阶段用 STDIO 快速验证，生产环境全部切 Streamable HTTP + OAuth。

# 安装官方 MCP SDK（Python）
pip install mcp

# 安装 TypeScript SDK
npm install @modelcontextprotocol/sdk

Step 2：搭建一个受控 MCP Server

以连接 GitHub 仓库为例，构建最小可运行 MCP Server：

# server.py
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import Tool, TextContent
import asyncio

server = Server("github-tools")

@server.list_tools()
async def list_tools() -> list[Tool]:
    return [
        Tool(
            name="get_issue",
            description="获取 GitHub Issue 详情",
            inputSchema={
                "type": "object",
                "properties": {
                    "owner": {"type": "string"},
                    "repo": {"type": "string"},
                    "issue_number": {"type": "integer"}
                },
                "required": ["owner", "repo", "issue_number"]
            }
        ),
        Tool(
            name="create_issue",
            description="创建 GitHub Issue（写操作，需审批）",
            inputSchema={
                "type": "object",
                "properties": {
                    "owner": {"type": "string"},
                    "repo": {"type": "string"},
                    "title": {"type": "string"},
                    "body": {"type": "string"}
                },
                "required": ["owner", "repo", "title"]
            }
        )
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
    if name == "get_issue":
        # 实现 GitHub API 调用
        return [TextContent(type="text", text=f"Issue #{arguments['issue_number']}: {arguments}")]
    elif name == "create_issue":
        # 高危操作，打印警告，实际部署需接入审批流程
        print(f"[MCP SECURITY] Write operation triggered: {arguments}")
        return [TextContent(type="text", text=f"Created issue: {arguments}")]
    raise ValueError(f"Unknown tool: {name}")

async def main():
    async with stdio_server() as (read_stream, write_stream):
        await server.run(read_stream, write_stream, server.create_initialization_options())

if __name__ == "__main__":
    asyncio.run(main())

保存并通过 stdio 运行验证：

python server.py
# MCP 客户端连接后测试
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python server.py

Step 3：配置 MCP Client（以 Claude Desktop / Cursor 为例）

// ~/.config/claude-desktop.json（示例）
{
  "mcpServers": {
    "github-tools": {
      "command": "python",
      "args": ["/path/to/server.py"],
      "env": {
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}

Step 4：升级到 HTTPS + OAuth 认证（生产必需）

# server_remote.py - 生产级 HTTP 传输
from mcp.server.fastmcp import FastMCP

mcp = FastMCP(
    "github-tools-prod",
    auth_mode="oauth",          # 启用 OAuth 2.1 + PKCE
    required_scopes=["read"],   # 默认只读
)

@mcp.tool(scope="read")
async def get_issue(owner: str, repo: str, issue_number: int):
    """读操作，自动允许"""
    ...

@mcp.tool(scope="write", require_approval=True)
async def create_issue(owner: str, repo: str, title: str, body: str = ""):
    """写操作，必须人工审批"""
    print("[APPROVAL REQUIRED] Write action paused until human confirms.")
    ...

生产 nginx 反向代理配置（强制 HTTPS）：

server {
    listen 443 ssl;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location /mcp {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        # MCP Streamable HTTP 必须支持 HTTP/2 和 SSE
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_read_timeout 86400;  # MCP 长连接支持数小时
    }
}

---

关键实现细节

1. 异步任务（Tasks Protocol）——长时间操作不阻塞

2025-11-25 规范引入的 Tasks 机制，允许”发起后返回句柄，后台执行，客户端轮询结果”：

from mcp.types import Task, TaskStatus

@mcp.tool()
async def bulk_create_issues(issues: list[dict]) -> str:
    """批量创建 Issue，立即返回 task_id，不阻塞"""
    task_id = f"task_{len(issues)}_{int(time.time())}"
    # 后台队列处理，函数立即返回
    asyncio.create_task(process_issues_async(task_id, issues))
    return task_id  # 客户端用 task_id 轮询状态

# 客户端轮询示例
async def poll_task_result(client, task_id: str, timeout: int = 300):
    start = time.time()
    while time.time() - start < timeout:
        result = await client.tasks.get_status(task_id)
        if result.status == "completed":
            return result.result
        elif result.status == "failed":
            raise RuntimeError(f"Task failed: {result.error}")
        await asyncio.sleep(5)  # 5秒轮询间隔
    raise TimeoutError("Task timed out")

2. 用 MCP Gateway 统一管理多 Server

生产环境不应让 AI 直连每个 MCP Server，应通过 Gateway 集中鉴权、限流、审计：

# Cloudflare MCP Gateway 部署示例
docker run -e GATEWAY_AUTH=oauth \
           -e OAUTH_ISSUER=https://your-auth-provider.com \
           -e TUNNEL_TOKEN=your_tunnel_token \
           cloudflare/mcp-gateway:latest

3. MCP + A2A 双协议协同架构

现代生产 Agent 系统通常同时运行两个协议：

AI Agent
  ├── MCP Client  → MCP Server → 工具层（GitHub, DB, CRM）
  └── A2A Client  → A2A Server → 其他 Agent（调度、协调）

# A2A Agent Card 示例（服务发现）
agent_card = {
    "name": "github-agent",
    "description": "负责 GitHub 仓库管理的 Agent",
    "url": "http://agent.internal:8000",
    "capabilities": {
        "streaming": True,
        "pushNotifications": True
    },
    "skills": [
        {"id": "github-issue-mgmt", "name": "GitHub Issue 管理"},
        {"id": "github-pr-review", "name": "PR 审查"}
    ]
}

---

常见坑与规避清单

🔴 坑 1：STDIO 直连生产服务

问题： STDIO 无任何网络认证，生产服务器暴露在公网。 规避： 生产环境必须使用 Streamable HTTP + OAuth 2.1 + PKCE，永远加 HTTPS。

🔴 坑 2：所有工具权限相同

问题： 读工具和写工具混用同一权限级别。 规避： 按操作风险分级——读操作自动放行，写操作（创建/删除/支付）必须走审批 Gate。

# 错误示例（危险）
@mcp.tool()
async def delete_repo(owner: str, repo: str):
    ...

# 正确示例
@mcp.tool(scope="admin", require_approval=True)
async def delete_repo(owner: str, repo: str):
    """危险操作，需 SSO + 审批双重确认"""
    ...

🔴 坑 3：Token 存储在环境变量或代码中

问题： GitHub Token 等凭证被提交到 Git 或日志泄漏。 规避： 使用 Key Management Service（AWS Secrets Manager / HashiCorp Vault），运行时拉取，内存使用后即弃。

🔴 坑 4：忽略 MCP Server 来源验证

问题： 恶意 MCP Server 注册同名工具进行中间人攻击（Tool Shadowing）。 规避： 维护 Server Allowlist，启动时验证指纹，拒绝未注册 Server。

🔴 坑 5：长连接无超时配置

问题： MCP HTTP 长连接不设超时，Agent 挂起导致系统卡死。 规避： 配置 proxy_read_timeout 86400（nginx），服务端主动发送心跳，超时后优雅降级。

🔴 坑 6：跳过 Gateway 直接集成

问题： 每个 Client 直连每个 Server，网络拓扑混乱，无法集中审计。 规避： 即使小团队也建议引入轻量 Gateway（Cloudflare MCP Gateway 或开源 bypass），集中日志和认证。

🟡 坑 7：MCP Server 配置不可迁移

问题： 在 Cursor 配置的 MCP Server 无法迁移到 Claude Desktop。 规避： 使用 MCP Registry 的 mcp.json 配置文件模板，或使用 MCP Gateway 作为统一入口，Client 侧只需配置 Gateway 地址。

---

成本 / 性能 / 维护权衡

维度	STDIO 模式	HTTP + OAuth 模式
部署复杂度	⭐ 低，开箱即用	⭐⭐⭐ 需要证书、Auth 服务
延迟	极低（<5ms）	10-50ms（受网络影响）
扩展性	单机单进程	水平扩展，需会话亲和
安全合规	依赖主机隔离	完整身份验证与审计
运维成本	低	中高，需要 Gateway 维护
适用规模	<5 Agent	10+ Agent，多团队

成本参考（AWS 估算）：

• 1 个 MCP Gateway（t3.medium）≈ $30/月
• OAuth 服务（轻量）+ RDS 审计存储 ≈ $50/月
• EKS 托管 MCP Server（3 副本）≈ $150/月

---

一周内可执行行动清单

Day 1-2：快速验证

• 在本地用 STDIO 模式跑通一个 MCP Server（参考上方 Step 2 代码）
• 配置 Claude Desktop 或 Cursor 连接该 Server，验证工具调用链路
• 阅读 MCP 官方规范中的 Security Considerations 章节

Day 3-4：生产规划

• 梳理内部需要接入的工具清单（数据库、GitHub、Jira 等），按读/写分类
• 评估是否已有 OAuth 2.1 / OIDC 基础设施（Keycloak、Auth0、AWS Cognito）
• 设计 MCP Gateway 部署方案，选型 Cloudflare MCP Gateway 或自建

Day 5-6：安全加固

• 将所有 MCP Server 从 STDIO 升级到 HTTPS + OAuth
• 实现写操作审批 Gate（人工确认流程）
• 配置 MCP Server Allowlist，拒绝未授权 Server 连接
• 接入日志审计（记录每次工具调用的调用方、工具名、参数、时间）

Day 7：评估 MCP + A2A 路线

• 若 Agent 间需要协同调度，评估 A2A 协议接入时机
• 参考 Linux Foundation A2A 规范，设计多 Agent 通信拓扑
• 记录本次落地经验，更新团队 MCP 接入规范文档

---

参考资源

• MCP 官方规范
• MCP Python SDK
• MCP 2026 Roadmap
• A2A Protocol GitHub
• Linux Foundation Agentic AI Foundation
• MCP 生产安全指南（Qualys）

一句话总结： MCP 是 AI 接入工具的事实标准，但”能用”到”能上线”之间，核心距离是：HTTPS + OAuth 鉴权、最小权限原则、以及集中的 MCP Gateway。