MCP Setup 是一份围绕 Model Context Protocol（MCP）的配置与开发指南，帮助用户在 Claude Code、Claude Desktop、Cursor 和 VS Code 等客户端中接入 MCP 服务器，并自行开发自定义服务器。
一、协议概述 MCP 是一种开放标准，通过 JSON-RPC 2.0 将 AI 模型连接到外部工具、数据和服务。其架构为：Host（运行模型的应用）创建 Client，Client 与 Server 建立 1:1 连接。服务器可暴露三类原语：Tools（模型可调用的函数，类似 API 端点）、Resources（模型可读取的数据，如文件、数据库记录、配置）、Prompts（带参数的可复用提示模板）。
二、各客户端配置方式 Claude Desktop 的配置文件位于 macOS 的 ~/Library/Application Support/Claude/claude_desktop_config.json、Windows 的 %APPDATA%\Claude\claude_desktop_config.json、Linux 的 ~/.config/Claude/claude_desktop_config.json，使用 mcpServers 字段配置 command、args 与 env。 Claude Code 使用项目根目录的 .mcp.json，也可通过 CLI 管理：claude mcp add my-server npx -y @some/mcp-server、claude mcp add db-server -e DATABASE_URL=postgresql://... -- npx -y @modelcontextprotocol/server-postgres、claude mcp list、claude mcp remove my-server。 Cursor 使用项目根目录的 .cursor/mcp.json 或全局的 ~/.cursor/mcp.json，格式与 Claude Desktop 相同。 VS Code（Copilot）使用 .vscode/mcp.json，支持通过 inputs 定义输入变量来传入密钥。
三、常用 MCP 服务器 资料列出了 Filesystem（工具：read_file、write_file、list_directory、search_files、move_file）、Git（git_log、git_diff、git_status、git_commit、git_branch）、PostgreSQL（只读查询工具，将表结构暴露为资源）、SQLite（read_query、write_query、create_table、list_tables、describe_table）、Brave Search（brave_web_search、brave_local_search）、Puppeteer（puppeteer_navigate、puppeteer_screenshot、puppeteer_click、puppeteer_fill、puppeteer_evaluate）、Sequential Thinking（提供 sequentialthinking 工具用于结构化多步推理）、GitHub、Slack，并给出各自的配置 JSON 示例。
四、构建自定义服务器 TypeScript 方式：npm init -y && npm install @modelcontextprotocol/sdk zod，使用 McpServer、StdioServerTransport 与 zod 定义 tool、resource、prompt，最后 server.connect(new StdioServerTransport())。 Python 方式：pip install mcp（或 uv add mcp），使用 FastMCP，通过 @mcp.tool()、@mcp.resource()、@mcp.prompt() 装饰器定义能力，mcp.run() 默认 stdio，mcp.run(transport="sse") 使用 SSE。 工具定义需包含 name、description 与 JSON Schema 输入，建议说明何时/为何使用该工具、对受限取值使用 enum、返回结构化 JSON。
五、传输机制 stdio（默认）：服务器作为子进程运行，客户端通过 stdin/stdout 读写 JSON-RPC，适合本地工具，无网络暴露面。 SSE（Server-Sent Events）：服务器运行 HTTP，客户端 GET /sse 获取事件、POST /messages 发送请求，适合远程服务器。 Streamable HTTP：较新的传输方式，取代 SSE，单一 HTTP 端点，同时支持请求-响应与流式，推荐用于新的远程部署。
六、认证方式 本地 stdio 服务器通过环境变量传递密钥；远程服务器使用 OAuth 2.1 with PKCE，Host 在 /.well-known/oauth-authorization-server 发现服务器元数据并发起授权码流程；SSE/HTTP 可使用 API key，在服务端校验 x-api-key 或 Authorization: Bearer 头。
七、调试 可使用 MCP Inspector：npx @modelcontextprotocol/inspector 后接服务器启动命令，打开浏览器 UI 交互式列出并调用 tools/resources/prompts。日志方面，Claude Desktop（macOS）可查看 ~/Library/Logs/Claude/mcp*.log。自定义服务器必须将日志写入 stderr（stdout 是传输通道），可使用 console.error 或 server.sendLoggingMessage，Python 使用 logging.basicConfig(stream=sys.stderr)。还可用 echo 构造 initialize 请求进行手动 stdio 测试。
八、CI/CD 与安全 Claude Code 可无头运行并加载 .mcp.json 中的 MCP 服务器，如 claude -p "Run all database migrations and report status"；也可用 Docker 运行隔离的 MCP 服务器。安全建议包括：文件系统仅授权特定目录，绝不授权 / 或 ~；数据库尽量使用只读凭据；密钥不硬编码进版本控制配置，使用环境变量或密钥管理器并加入 .gitignore；服务端校验所有工具输入并使用参数化查询；stdio 无网络暴露面，SSE/HTTP 应绑定 localhost，远程使用 TLS 并限流；以最小权限账户运行服务器，对不可信代码使用 Docker。
九、常见问题与注册表 资料列出常见问题及修复：服务器未找到（使用绝对路径、确保二进制在 PATH 中）、启动崩溃（npx -y 自动安装依赖、检查 pip install）、认证错误（核对环境变量、刷新过期令牌）、连接超时（减少初始化工作、检查阻塞调用）、工具不出现（检查 capabilities 与 list_tools 处理器）、"Transport closed"（查看 stderr 未处理异常）、JSON 解析错误（日志必须写 stderr）、协议不匹配（更新 SDK 匹配客户端协议版本）。服务器注册表方面，官方为 @modelcontextprotocol npm scope，社区有 mcp.so、smithery.ai、awesome-mcp-servers；发布自己的服务器可命名为 mcp-server-yourname 发布到 npm 或 PyPI，并记录暴露的 tools/resources/prompts、所需环境变量与示例配置 JSON。