企业官网建设流程全解析

• 教程
• 文档
• 人工智能

本文以mcp-for-beginners开源课程中「12-mcp-hosts」章节（对应 03-GettingStarted/12-mcp-hosts/README.md）为核心骨架，系统讲解如何把 MCP Server 接入 Claude Desktop、VS Code（GitHub Copilot）、Cursor、Cline、Windsurf 五类主流 AI 主机应用，并深入剖析配置背后的传输协议（stdio 与 Streamable HTTP）、排查方法以及安全最佳实践。读完本文，你将能独立完成任一主机的 MCP 服务注册、连接验证与故障定位，并理解不同传输方式各自的适用场景。

什么是 MCP 主机（Host）

MCP 主机是一个能够连接 MCP Server 以扩展自身能力的 AI 应用。可以把它理解为用户直接交互的「前端界面」，而 MCP Server 则是提供工具与数据的「后端能力」。用户在主机中通过自然语言或界面操作触发请求，主机把请求转换为标准化的 MCP 协议消息，分发给已注册的各个服务器。

每个主机的配置文件格式各不相同，但一旦配置完成，它们都通过标准化的 MCP 协议与服务器通信，因此你只需编写一次服务器，即可被多种主机消费。

前置条件

• 一个可供连接的 MCP Server（参见 03-GettingStarted/01-first-server/README.md 中的「创建第一个服务器」章节）；
• 已安装到本机的主机应用；
• 对 JSON 配置文件的基本了解。

传输方式与协议版本的注意事项

[!NOTE] 本文档中指向/sse的主机配置，属于面向 MCP2025-11-25版本的旧式 HTTP+SSE 示例。对于 MCP2026-07-28，请在支持的主机中选择Streamable HTTP传输，并使用服务器配置的端点。

这一点至关重要：MCP 规范在2026-07-28版本中做了大规模修订，协议层不再有会话（session），initialize握手与Mcp-Session-Id头被移除，每个请求都自带协议版本、方法与客户端信息（详见 01-CoreConcepts/mcp-2026-07-28.md）。因此在配置主机时，优先选择 Streamable HTTP 并核对服务器实际暴露的端点，而不是沿用旧教程里的/sse路径。

1. Claude Desktop

Claude Desktop是 Anthropic 官方桌面应用，原生支持 MCP，适合本地通过 stdio 启动服务器。

安装

1. 从 Anthropic 官网（claude.ai/download）下载 Claude Desktop；
2. 安装并使用 Anthropic 账户登录。

配置

Claude Desktop 使用 JSON 配置文件定义 MCP 服务器。

配置文件位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

示例配置：

{ "mcpServers": { "calculator": { "command": "python", "args": ["-m", "mcp_calculator_server"], "env": { "PYTHONPATH": "/path/to/your/server" } }, "weather": { "command": "node", "args": ["/path/to/weather-server/build/index.js"] }, "database": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-postgres"], "env": { "DATABASE_URL": "postgresql://user:pass@localhost/mydb" } } } }

上述配置注册了三个 stdio 服务器：Python 计算器、Node 天气服务，以及通过npx拉取的 PostgreSQL 官方 MCP 服务器。npx -y会自动下载并运行包，无需手动安装，是注册 npm 生态服务器的常见方式。

配置字段说明

从底层实现看，这些字段对应 stdio 传输的核心机制：主机把command作为子进程启动，通过标准输入（stdin）写入 JSON-RPC 消息、从标准输出（stdout）读取响应，env与cwd则用于控制子进程的运行环境（详见 03-GettingStarted/05-stdio-server/README.md 中关于 stdio 传输如何工作的说明）。

测试你的配置

1. 保存配置文件；
2. 完全重启 Claude Desktop（退出后重新打开）；
3. 打开一个新对话；
4. 查找 🔌 图标，确认服务器已连接；
5. 用自然语言请求 Claude 调用其中一个工具（例如「Calculate 25 * 48」）。

Claude Desktop 常见问题排查

服务器没有出现在列表中：

• 用 JSON 校验器检查配置语法；
• 确认command的路径正确（建议使用绝对路径）；
• 查看 Claude Desktop 日志：Help → Show Logs。

服务器启动即崩溃：

• 先在终端手动运行服务器命令，确认其能独立工作；
• 检查env中的环境变量是否正确设置；
• 确认所有依赖已安装（如pip list | grep mcp或npm list @modelcontextprotocol/sdk）。

2. VS Code + GitHub Copilot

VS Code 通过 GitHub Copilot Chat 扩展支持 MCP，是目前开发场景中最常用的主机之一。本仓库的 03-GettingStarted/04-vscode/README.md 提供了完整的逐步演练，这里结合官方课程作系统讲解。

前置条件

1. VS Code 1.99+；
2. 已安装 GitHub Copilot 扩展；
3. 已安装 GitHub Copilot Chat 扩展。

配置

VS Code 使用工作区内的.vscode/mcp.json或用户级settings.json管理服务器。

工作区配置（.vscode/mcp.json）：

{ "servers": { "my-calculator": { "type": "stdio", "command": "python", "args": ["-m", "mcp_calculator_server"] }, "my-database": { "type": "sse", "url": "http://localhost:8080/sse" } } }

用户级配置（settings.json）：

{ "mcp.servers": { "global-server": { "type": "stdio", "command": "npx", "args": ["-y", "@anthropic/mcp-server-memory"] } }, "mcp.enableLogging": true }

[!NOTE] 上面示例中的"type": "sse"属于 MCP2025-11-25时代的 HTTP+SSE 旧式写法。在 MCP2026-07-28规范下应改用 Streamable HTTP，并确认 VS Code 版本与服务器端点支持该传输（参见 01-CoreConcepts/mcp-2026-07-28.md）。

通过命令行添加服务器

除了图形界面，你还可以用 VS Code 的code可执行文件从终端控制 MCP 服务器。向用户级配置添加服务器的命令是--add-mcp，后跟 JSON 形式的服务器配置：

code --add-mcp "{\"name\":\"my-server\",\"command\": \"uvx\",\"args\": [\"mcp-server-fetch\"]}"

这种方式适合脚本化、可重复的工作流，例如在初始化项目时批量注册服务器。

在 VS Code 中使用 MCP

1. 打开 Copilot Chat 面板（Ctrl+Shift+I / Cmd+Shift+I）；
2. 输入@查看可用的 MCP 工具列表；
3. 用自然语言调用工具，例如「Calculate 25 * 48 using the calculator」。

一个完整的实操流程如下：先在项目根目录创建.vscode/mcp.json并写入服务器条目（如command: "node", args: ["build/index.js"]），点击条目旁的「播放」图标启动服务器；此时 Copilot Chat 的工具图标会显示可用工具数量增长，点击可查看并勾选工具；最后通过描述性提示词（如「add 22 to 1」）触发工具，得到结果 23。

VS Code 常见问题排查

MCP 服务器无法加载：

• 打开 Output 面板，选择「MCP」通道查看错误日志（mcp.enableLogging: true可提供更多日志）；
• 执行 Ctrl+Shift+P → 「Developer: Reload Window」重载窗口；
• 先用 MCP Inspector 或直接运行命令，确认服务器本身能独立启动。

3. Cursor

Cursor是 AI 优先的代码编辑器，内置 MCP 支持，配置格式与 Claude Desktop 类似。

安装

1. 从 Cursor 官网（cursor.sh）下载并安装；
2. 安装完成后登录账号。

配置

配置文件位置：

• macOS：~/.cursor/mcp.json
• Windows：%USERPROFILE%\.cursor\mcp.json
• Linux：~/.cursor/mcp.json

示例配置：

{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"] }, "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "ghp_your_token_here" } } } }

注意filesystem服务器的最后一个参数用于限定服务器可访问的目录（白名单），这对应 02-Security 中「最小权限」的实践；GITHUB_TOKEN这类敏感信息不建议直接写死，应使用环境变量或密钥管理方案（详见下文安全最佳实践）。

在 Cursor 中使用 MCP

1. 打开 Cursor 的 AI 对话（Ctrl+L / Cmd+L）；
2. MCP 工具会自动出现在建议列表中；
3. 用自然语言请求 AI 完成涉及已连接服务器的任务。

4. Cline（终端客户端）

Cline是终端形态的 MCP 客户端，适合命令行工作流。文档中同时演示了环境变量、命令行参数与配置文件三种接入方式。

安装

npm install -g @anthropic/cline

配置

使用环境变量：

export ANTHROPIC_API_KEY="your-api-key" export MCP_SERVER_CALCULATOR="python -m mcp_calculator_server"

使用命令行参数：

cline --mcp-server "calculator:python -m mcp_calculator_server" \ --mcp-server "weather:node /path/to/weather/index.js"

配置文件（~/.clinerc）：

{ "apiKey": "your-api-key", "mcpServers": { "calculator": { "command": "python", "args": ["-m", "mcp_calculator_server"] } } }

使用 Cline

# 启动交互式会话 cline # 单次查询并调用 MCP 工具 cline "Calculate the square root of 144 using the calculator" # 列出可用工具 cline --list-tools

--list-tools会枚举服务器注册的全部工具，方便在脚本化调用前确认工具名称与参数，其作用相当于在代码客户端中调用listTools（参见 03-GettingStarted/02-client/README.md 中「列出服务器功能」一节）。

5. Windsurf

Windsurf是另一款支持 MCP 的 AI 代码编辑器。

安装

1. 从 Windsurf 官网（codeium.com/windsurf）下载并安装；
2. 创建账号并登录。

配置

Windsurf 通过设置界面管理配置：

1. 打开设置（Ctrl+, / Cmd+,）；
2. 搜索「MCP」；
3. 点击「Edit in settings.json」编辑配置文件。

示例配置：

{ "windsurf.mcp.servers": { "my-tools": { "command": "python", "args": ["/path/to/server.py"], "env": {} } }, "windsurf.mcp.enabled": true }

windsurf.mcp.enabled是总开关，置为true后上述服务器才会被加载。

传输类型对比

不同主机支持的传输机制不同，这直接决定了你能用本地子进程服务器还是远程 HTTP 服务器：

• stdio（标准输入/输出）：最适合由主机启动的本地服务器。主机将服务器作为子进程拉起，通过 stdin/stdout 交换换行分隔的 JSON-RPC 消息；服务器只能把日志写到 stderr，绝不能污染 stdout（这是 stdio 传输的硬性约束，详见 03-GettingStarted/05-stdio-server/README.md）。
• SSE/HTTP：适合远程服务器，或需要被多个客户端共享的服务器。注意：当前规范中独立 SSE 传输已被弃用，被Streamable HTTP取代——后者支持通知机制、更好的扩展性，且被 03-GettingStarted/06-http-streaming/README.md 推荐用于生产与云端场景。

常见问题与解决方案

服务器无法启动

1. 先在终端手动测试服务器：

   # Python python -m your_server_module # Node.js node /path/to/server/index.js

2. 检查命令路径：尽量使用绝对路径；确认可执行文件在PATH中（Windows 下尤其常见）。

3. 检查依赖：

   # Python pip list | grep mcp # Node.js npm list @modelcontextprotocol/sdk

服务器已连接但工具不工作

1. 检查服务器日志：多数主机提供日志开关（如 VS Code 的mcp.enableLogging）；
2. 用 MCP Inspector 验证工具注册：Inspector 会列出全部工具、输入模式并显示完整 JSON 响应，是定位「工具未注册/参数不匹配」的利器（参见 03-GettingStarted/13-mcp-inspector/README.md）；
3. 检查权限：部分工具需要文件或网络访问权限，确认主机是否授予了相应访问范围。

环境变量未传递

• 部分主机会「清洗」进程环境变量，避免把宿主机全部环境泄露给服务器子进程；
• 请显式使用配置中的env字段声明需要传递的变量；
• 不要在配置文件中存放敏感信息，改用密钥管理服务或环境变量间接引用。

安全最佳实践

无论使用哪种主机，以下原则都应遵守：

1. 绝不把 API 密钥提交进配置文件（如 Git 仓库中的mcp.json）；
2. 使用环境变量或密钥管理承载敏感数据；
3. 把服务器权限限制到最小必要范围（如server-filesystem只授权指定目录）；
4. 授予系统访问权限前先审查服务器代码（npx -y拉取的第三方包尤其需要留意）；
5. 对文件系统与网络访问使用 allowlist（白名单）。

这些原则与本仓库 02-Security/README.md 中的安全章节一脉相承：面对不可信的工具结果与服务器内容，主机应用需要额外的防御纵深。

深入原理：主机背后的协议与验证工具

理解了上述配置，再看几处底层机制，会有助于排查问题：

• stdio 是「进程即传输」：客户端负责以command+args启动服务器子进程，双方只在 stdin/stdout 上交换换行分隔的 JSON-RPC 消息。因此配置中的command/args/env/cwd本质上就是在定义子进程的启动方式。
• 远程传输正在换代：/sse是 MCP2025-11-25的遗留配置；2026-07-28规范要求使用 Streamable HTTP，并以MCP-Protocol-Version、Mcp-Method、Mcp-Name等头部描述每次自包含的请求（见 01-CoreConcepts/mcp-2026-07-28.md）。配置新主机时优先选择 Streamable HTTP。
• 用 MCP Inspector 做独立验证：不需要完整主机应用即可测试服务器——npx @modelcontextprotocol/inspector python server.py会启动本地 Web 界面，展示已注册的工具、资源、提示词以及完整的 JSON-RPC 消息流，是连接主机前的「第一道质检」（详见 03-GettingStarted/13-mcp-inspector/README.md）。

下一步

• 3.13 - 使用 MCP Inspector 调试
• 3.1 - 创建你的第一个 MCP 服务器
• 模块 5 - 高级主题

• 教程
• 文档
• 人工智能