name: mcp-server-orchestrator description: 配置、部署和调试Model Context Protocol (MCP) 服务器，用于AI代理工作流。在设置MCP服务器、调试连接问题、管理多服务器配置、集成Claude Desktop/Code/Cowork或设计自定义工具服务器时使用。触发于MCP配置、工具服务器开发、Claude集成问题或代理基础设施设置。 license: MIT

MCP服务器编排器

管理用于AI驱动开发工作流的MCP服务器基础设施。

MCP架构概述

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   MCP客户端    │────▶│   MCP服务器     │────▶│  外部API       │
│ (Claude等)      │◀────│  (工具提供者)    │◀────│  (服务)         │
└─────────────────┘     └──────────────────┘     └─────────────────┘
         │                       │
         └───── JSON-RPC ────────┘

关键概念：

服务器：通过MCP协议提供工具、资源和提示
客户端：消费服务器能力（Claude Desktop、Claude Code等）
传输：通信层（stdio、SSE、WebSocket）

配置位置

客户端	配置文件	平台
Claude Desktop	`claude_desktop_config.json`	macOS: `~/Library/Application Support/Claude/`
		Windows: `%APPDATA%\Claude\`
Claude Code	`settings.json` 或 MCP配置	项目级或用户设置
Cline	`cline_mcp_settings.json`	VS Code扩展设置

服务器配置模式

{
  "mcpServers": {
    "server-name": {
      "command": "executable",
      "args": ["arg1", "arg2"],
      "env": {
        "API_KEY": "value"
      },
      "disabled": false
    }
  }
}

常见服务器类型

Python服务器 (uvx)：

{
  "my-python-server": {
    "command": "uvx",
    "args": ["--from", "package-name", "server-command"]
  }
}

Node服务器 (npx)：

{
  "my-node-server": {
    "command": "npx",
    "args": ["-y", "@scope/package-name"]
  }
}

本地开发服务器：

{
  "dev-server": {
    "command": "python",
    "args": ["-m", "my_server"],
    "env": {
      "DEBUG": "true"
    }
  }
}

故障排除工作流

连接问题

验证服务器独立启动：

# 测试Python服务器
python -m my_server

# 测试Node服务器
npx -y @scope/package-name

检查日志：
- Claude Desktop: ~/Library/Logs/Claude/mcp*.log
- 查找JSON-RPC错误、连接超时

验证JSON配置：

python -c "import json; json.load(open('config.json'))"

常见修复：
- 使用绝对路径作为命令
- 确保依赖安装在正确的环境中
- 检查API密钥/环境变量是否设置
- 更改配置后重启客户端

认证问题

OAuth流程： 确保重定向URI正确配置
API密钥： 验证环境变量服务器进程可访问
令牌刷新： 检查令牌存储位置和权限

构建自定义服务器

Python服务器 (FastMCP)

from fastmcp import FastMCP

mcp = FastMCP("my-server")

@mcp.tool()
def my_tool(param: str) -> str:
    """为AI提供工具描述。"""
    return f"结果: {param}"

@mcp.resource("resource://my-data")
def get_data() -> str:
    """以资源形式提供数据。"""
    return "资源内容"

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

Node服务器 (MCP SDK)

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({ name: "my-server", version: "1.0.0" }, {
  capabilities: { tools: {} }
});

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{
    name: "my_tool",
    description: "工具描述",
    inputSchema: { type: "object", properties: { param: { type: "string" } } }
  }]
}));

const transport = new StdioServerTransport();
await server.connect(transport);

多服务器编排

模块化架构

按域组织服务器：

{
  "mcpServers": {
    "filesystem": { "command": "...", "args": ["--allowed-dirs", "/projects"] },
    "database": { "command": "...", "env": { "DB_URL": "..." } },
    "api-integrations": { "command": "...", "env": { "API_KEYS": "..." } },
    "custom-tools": { "command": "python", "args": ["-m", "my_tools"] }
  }
}

服务器选择策略

将服务器视为合成器中的模块——根据工作流需求将它们拼接在一起：

开发工作流： 文件系统 + git + 代码分析服务器
研究工作流： 网络搜索 + 文档 + 笔记服务器
数据工作流： 数据库 + 可视化 + 导出服务器

性能优化

延迟加载： 仅启用当前任务所需的服务器
缓存： 为昂贵操作实现响应缓存
超时调整： 调整慢速外部API的超时
连接池： 在数据库服务器中重用连接

参考

references/server-templates.md - 常见服务器类型的模板
references/debugging-guide.md - 详细的故障排除流程