Claude MCP 配置可将 Claude Code 或 Claude Desktop 连接到外部工具，例如数据库、代码运行器、API 和自定义服务器。使用 claude mcp add（适用于 Claude Code）或编辑 Claude Desktop JSON 配置，然后验证传输方式、作用域和工具列表。本指南涵盖两种设置路径、常见故障、工具调用推理以及沙箱执行。
Claude MCP 配置的工作原理
MCP 是 Anthropic 推出的一项开放标准，为语言模型提供了一种统一的调用外部工具的方式。在 MCP 出现之前，每个 AI 应用都需要为每个想要使用的工具编写专门的胶水代码。有了 MCP，任何兼容的服务器都能通过标准的发现和调用协议公开其能力，而任何兼容的主机（包括 Claude）都可以直接使用这些能力，无需为每个工具进行集成开发。
具体来说：当你向 Claude 添加 MCP 服务器时，你是在告诉 Claude 主机在哪里可以找到一组工具。Claude 随后可以在会话期间列出这些工具，并在任务需要时按名称调用它们。服务器负责执行，Claude 负责判断何时以及如何调用。
MCP 的三个核心概念：
| 概念 | 说明 | 示例 |
|---|---|---|
| 工具 | 服务器暴露的可调用函数 | run_python、query_db、list_models |
| 资源 | 服务器作为上下文提供的只读数据 | 文件、数据库行、数据集 |
| 提示 | 服务器内置的预构建指令模板 | 系统级任务描述 |
对于大多数开发者来说，工具是最重要的。在构建更复杂的代理管道时，资源和提示会变得相关。
在 Claude Code 中添加 MCP 服务器
Claude Code 通过 claude mcp 子命令组暴露 MCP 管理功能。你可以无需手动修改任何配置文件，直接添加、删除和列出服务器。
claude mcp add —— 基本形式
claude mcp add <名称> <命令> [参数...]
例如，添加一个本地 Python MCP 服务器：
claude mcp add my-tools python /path/to/mcp_server.py
这将注册一个名为 my-tools 的服务器，该服务器使用 stdio 传输运行 python /path/to/mcp_server.py。Claude Code 会在你启动会话时启动该进程，并在会话期间保持其运行。
传递环境变量
许多 MCP 服务器需要 API 密钥或端点 URL。在注册时使用 --env 传递它们：
claude mcp add my-tools python /path/to/mcp_server.py \
--env API_KEY=your_key_here \
--env BASE_URL=https://api.example.com
这些值会存储在 Claude Code 的配置中，并在服务器启动时注入到进程环境中。不要将密钥硬编码到服务器命令本身中。
claude mcp add json —— 从 JSON 规范注册
如果你已经将服务器规范编写为 JSON（通常在团队间共享配置时使用），可以直接通过管道传入：
echo '{
"command": "python",
"args": ["/path/to/mcp_server.py"],
"env": {
"API_KEY": "your_key"
}
}' | claude mcp add my-tools --json
或者传入一个文件：
claude mcp add my-tools --json < server-spec.json
这等同于位置参数形式，但提供了一个单一的配置工件，你可以进行版本控制并共享。
列出和删除服务器
# 查看所有已注册的服务器
claude mcp list
# 删除服务器
claude mcp remove my-tools
作用域：项目级 vs 用户级
默认情况下，claude mcp add 将服务器注册到用户级配置中，使其在每个 Claude Code 会话中可用。若只想为当前项目注册（存储在 .claude/settings.json 中），请添加 --scope project：
claude mcp add my-tools python /path/to/mcp_server.py --scope project
当不同项目需要不同工具，并且希望保持配置隔离时，项目级作用域的服务器非常有用。
claude mcp serve —— 将 Claude Code 暴露为 MCP 服务器
反向操作同样可行。claude mcp serve 将 Claude Code 本身作为一个 MCP 服务器启动，让其他 MCP 主机可以连接并使用其工具：
claude mcp serve
如果你希望将 Claude Code 的能力组合到更大的代理管道中，由不同的主机来编排工具调用，这将非常有用。
Claude Desktop MCP 服务器配置
Claude Desktop 将 MCP 服务器配置存储在一个 JSON 文件中。文件位置取决于你的操作系统：
- macOS：
~/Library/Application Support/Claude/claude_desktop_config.json - Windows：
%APPDATA%\Claude\claude_desktop_config.json
如果文件不存在，请创建它。结构如下所示：
{
"mcpServers": {
"my-tools": {
"command": "python",
"args": ["/path/to/mcp_server.py"],
"env": {
"API_KEY": "your_key_here"
}
}
}
}
mcpServers 下的每个键都是 Claude 用来标识服务器的名称。你可以注册任意数量的服务器——Claude Desktop 会在启动时加载所有服务器。
编辑文件后，重启 Claude Desktop 以使更改生效。当 MCP 工具成功加载时，你会在聊天输入区域看到一个锤子图标。
通过 SSE 添加远程 MCP 服务器
对于使用服务器发送事件（SSE）传输而非 stdio 的远程服务器，配置格式略有不同：
{
"mcpServers": {
"remote-tools": {
"url": "https://your-mcp-server.example.com/sse"
}
}
}
某些远程服务器需要身份验证。如果服务器期望 Bearer 令牌，可以在 headers 字段中传递：
{
"mcpServers": {
"remote-tools": {
"url": "https://your-mcp-server.example.com/sse",
"headers": {
"Authorization": "Bearer your_token_here"
}
}
}
}
MCP 传输类型：stdio vs SSE
MCP 服务器通过两种传输机制之一与 Claude 主机通信：
stdio —— 服务器作为同一台机器上的子进程运行。主机启动该进程，并通过标准输入/输出读写 JSON-RPC 消息。这是本地服务器的默认方式，也是设置最简单的方式。
SSE（服务器发送事件） —— 服务器远程运行并暴露一个 HTTP 端点。主机连接到 URL 并以流的形式接收工具响应。这种方式可以跨机器工作，是共享团队基础设施或托管工具服务的正确选择。
对于刚开始使用的个人开发者来说，stdio 更简单——无需网络，服务器进程会自动管理。当团队希望共享单个 MCP 服务器，或者工具本身需要在特定网络环境中运行时，SSE 会变得更有价值。
Claude 如何推理 MCP 工具
当会话启动且 MCP 服务器已注册时，Claude 会查询每个服务器以获取其可用工具。这将产生一个工具名称列表和 JSON Schema 描述。Claude 不会投机性地调用工具——它只在对话或任务需要时，根据工具描述的内容来调用工具。
工具调用流程如下：
- 用户发送消息或任务。
- Claude 评估是否有任何已注册的工具可以提供帮助。
- 如果有，Claude 会使用适当的参数构建一个工具调用。
- MCP 主机将调用发送到正确的服务器。
- 服务器执行并返回结果。
- Claude 将结果纳入其推理并继续执行。
这个循环可以在单次交互中多次发生——Claude 可以链式调用工具，使用一个工具的结果来通知另一个工具的参数，并在同一会话中跨多个服务器聚合结果。
工具描述的质量在这里非常重要。模糊的描述会导致遗漏或不正确的调用。精确的描述——包括工具的功能、参数的含义以及返回的内容——能让 Claude 准确路由调用，而无需猜测。
在沙箱中运行工具执行
当 MCP 工具执行代码（如 Python 脚本、Shell 命令、文件操作）时，在本地机器上运行会引发隔离问题。一个具有文件系统访问、进程生成或网络调用能力的工具，在出现异常行为或被引导到意外路径时，会有很大的影响范围。
Novita AI Agent Sandbox 通过提供用于工具执行的隔离云环境来解决这个问题。你无需在本地运行 MCP 服务器，而是将其部署在沙箱实例内部。沙箱拥有自己的文件系统、网络范围和资源限制。代理可以在该边界内写入文件、运行代码和调用内部 API，而不会影响主机。
在沙箱内运行的 MCP 服务器通过 SSE 传输暴露其工具，Claude 远程连接——因此从 Claude 的角度来看，集成方式完全相同。区别完全在于工具实际运行的环境。
适用于 MCP 部署的 Novita Sandbox 的关键特性：
- 快速启动：实例在约 200ms 内启动，保持工具往返延迟较低
- 按秒计费：你只需为实际执行时间付费，无需为空闲预留付费
- 隔离的文件系统：每个沙箱实例都有独立的工作空间，防止跨会话数据泄漏
- 可配置的网络策略：控制工具可以访问哪些外部服务
有关构建由 Novita Sandbox 支持的 MCP 服务器的逐步指南，请参阅使用 Novita Sandbox 和 mcp-use 库构建远程代码执行 MCP 服务器。
使用 Novita LLM API 进行 MCP 工具调用推理
虽然 Claude 自己的模型原生支持工具调用，但你可能会希望将某些 MCP 工具调用推理路由到不同的模型——出于成本、延迟或专业化的考虑。Novita LLM API 提供了一个兼容 OpenAI 的端点，可以访问支持函数调用和结构化工具调用的模型。
这在 MCP 架构中有两种应用方式：
1. 作为自定义 MCP 主机背后的推理模型：如果你正在构建自己的 MCP 主机（而不是使用 Claude Code 或 Claude Desktop），你可以使用 Novita LLM API 来驱动模型层。主机使用工具列表和对话调用 Novita API；模型返回工具调用指令；主机将这些指令分派到 MCP 服务器。
import openai
client = openai.OpenAI(
base_url="https://api.novita.ai/v3/openai",
api_key="your_novita_api_key",
)
response = client.chat.completions.create(
model="meta-llama/llama-3.3-70b-instruct",
messages=[{"role": "user", "content": "列出可用工具并运行一个快速测试"}],
tools=[
{
"type": "function",
"function": {
"name": "list_models",
"description": "列出 API 中所有可用的模型。",
"parameters": {"type": "object", "properties": {}},
}
}
],
tool_choice="auto",
)
2. 作为 MCP 工具内部的 LLM：一个 MCP 工具可以在内部使用 Novita LLM API——例如，一个摘要工具、一个分类工具或一个生成代码的工具。该工具接收来自代理的输入，调用 Novita API，并返回结果。这使模型推理成本与主代理模型成本分离，并让你可以为每个子任务选择正确的模型。
有关构建调用 Novita API 的 MCP 服务器的实际示例，请参阅如何使用 Novita AI 构建你的第一个 MCP 服务器。
常见问题与修复
服务器未出现在 Claude Desktop 中
最常见的原因是 claude_desktop_config.json 中存在 JSON 语法错误。在保存前使用 JSON 验证器。即使是一个尾随逗号也会阻止文件加载。每次编辑后重启 Claude Desktop。
未找到 claude mcp add 命令
这意味着 Claude Code 未安装或未在 PATH 中。通过 npm install -g @anthropic-ai/claude-code 安装 Claude Code，并使用 claude --version 验证。
工具已列出但从未被调用
Claude 只有在认为工具与当前任务相关时才会调用它。如果工具描述过于模糊，Claude 将不会选择它们。添加具体信息：工具的功能、使用时机、输入和输出是什么。
服务器启动后立即退出
检查服务器命令是否正确，以及所有必需的环境变量是否已设置。直接在终端中运行命令以查看实际错误输出——在某些配置中，Claude Code 可能会抑制子进程的 stderr。
SSE 连接被拒绝
验证服务器 URL 是否可以从运行 Claude 的机器上访问，服务器是否确实在预期的端口上监听，以及任何必需的身份验证头是否正确配置。
工具调用失败并出现验证错误
Claude 传递的参数必须与工具声明的 JSON Schema 匹配。检查工具的 inputSchema 定义——如果缺少必需字段或类型不匹配，服务器将拒绝该调用。Claude 根据 Schema 构建参数，因此不完整的 Schema 会导致不完整的调用。
常见问题
Claude Code 支持 MCP 吗？
是的。Claude Code 通过 claude mcp 子命令原生支持 MCP。使用 claude mcp add 注册服务器，claude mcp list 查看已注册的服务器，claude mcp remove 取消注册。运行 claude mcp --help 查看完整的命令参考。
如何向 Claude Code 添加 MCP 服务器？
对于 stdio 服务器，运行 claude mcp add <名称> <命令> [参数...]，或使用 --json 传递 JSON 规范。对于项目级作用域的注册，添加 --scope project。添加后，启动一个新的 Claude Code 会话——工具将立即可用。
什么是 claude mcp serve？
claude mcp serve 将 Claude Code 本身作为 MCP 服务器运行，通过 MCP 协议暴露其能力。其他 MCP 主机可以连接到 Claude Code 并将其用作工具源。这在构建多代理系统时非常有用，其中 Claude 是多个组件之一。
我可以在 Claude Code 和 Claude Desktop 中使用同一个 MCP 服务器吗？
是的。服务器本身不关心哪个主机连接它。对于 stdio 服务器，Claude Code（通过 claude mcp add）和 Claude Desktop（通过 claude_desktop_config.json）都可以启动相同的命令。对于 SSE 服务器，任何能够访问该 URL 的主机都可以连接。
Claude 如何知道调用哪个 MCP 工具？
在会话启动时，Claude 查询所有已注册的服务器以获取其工具列表。每个工具都有一个名称和描述。在处理任务时，Claude 根据工具描述是否匹配需求来选择工具。编写良好的描述（包含清晰的用例）可以确保准确选择工具；模糊的描述会导致遗漏或不正确的调用。
我最多可以注册多少个 MCP 服务器？
MCP 规范没有设置硬性限制，Claude Code 和 Claude Desktop 也没有。实际上，拥有数十个包含数百个工具的服务器可能会减慢会话启动速度（工具发现会在启动时运行），并可能给 Claude 的工具选择增加噪音。保持工具集专注于特定项目或会话实际需要的范围。
stdio 和 SSE 传输有什么区别？
Stdio 将服务器作为本地子进程运行；主机通过 stdin/stdout 通信。SSE 连接到远程 HTTP 端点并以流的形式接收响应。Stdio 对于本地开发更简单；SSE 更适合远程、共享或生产部署。
