Claude supports the Model Context Protocol (MCP) natively, letting you connect external tools — databases, code runners, APIs, and custom servers — directly into your workflow. Whether you’re using Claude Code in the terminal or Claude Desktop on your machine, MCP configuration works the same way at the protocol level, with a few differences in how you register servers. This guide covers both paths: the claude mcp add CLI commands for Claude Code, and the JSON config file for Claude Desktop, along with how tool-use reasoning and sandbox execution fit into the picture.
What MCP Does in Claude
MCP is an open standard from Anthropic that gives language models a uniform way to call external tools. Before MCP, every AI app needed bespoke glue code for each tool it wanted to use. With MCP, any compliant server exposes its capabilities through a standard discovery and invocation protocol, and any compliant host — including Claude — can use them without per-tool integration work.
In practical terms: when you add an MCP server to Claude, you’re telling the Claude host where to find a set of tools. Claude can then list those tools during a session and call them by name when the task warrants it. The server handles execution; Claude handles reasoning about when and how to call.
Three core concepts underpin MCP:
| Concept | What it is | Example |
|---|---|---|
| Tool | A callable function exposed by the server | run_python, query_db, list_models |
| Resource | Read-only data the server makes available as context | A file, a database row, a dataset |
| Prompt | Pre-built instruction templates bundled with the server | A system-level task description |
For most developers, tools are what matter most. Resources and prompts become relevant when you’re building a more structured agent pipeline.
Adding MCP Servers in Claude Code
Claude Code exposes MCP management through the claude mcp subcommand group. You can add, remove, and list servers without touching any config file manually.
claude mcp add — the basic form
claude mcp add <name> <command> [args...]For example, to add a local Python MCP server:
claude mcp add my-tools python /path/to/mcp_server.pyThis registers a server named my-tools that runs python /path/to/mcp_server.py using stdio transport. Claude Code launches the process when you start a session and keeps it alive for the duration.
Passing environment variables
Many MCP servers need API keys or endpoint URLs. Use --env to pass them at registration time:
claude mcp add my-tools python /path/to/mcp_server.py \
--env API_KEY=your_key_here \
--env BASE_URL=https://api.example.comThe values are stored in Claude Code’s configuration and injected into the server process at startup. Do not hard-code secrets into the server command itself.
claude mcp add json — registering from a JSON spec
If you have a server spec already written as JSON (common when sharing configs across a team), you can pipe it directly:
echo '{
"command": "python",
"args": ["/path/to/mcp_server.py"],
"env": {
"API_KEY": "your_key"
}
}' | claude mcp add my-tools --jsonOr pass a file:
claude mcp add my-tools --json < server-spec.jsonThis is equivalent to the positional form but gives you a single config artifact you can version-control and share.
Listing and removing servers
# See all registered servers
claude mcp list
# Remove a server
claude mcp remove my-toolsScope: project vs user
By default, claude mcp add registers the server in your user-level configuration, making it available in every Claude Code session. To register it only for the current project (stored in .claude/settings.json), add --scope project:
claude mcp add my-tools python /path/to/mcp_server.py --scope projectProject-scoped servers are useful when different projects need different tools and you want to keep configurations isolated.
claude mcp serve — exposing Claude Code as an MCP server
The direction also works in reverse. claude mcp serve starts Claude Code itself as an MCP server, letting another MCP host connect to it and use its tools:
claude mcp serveThis is useful if you want to compose Claude Code capabilities into a larger agent pipeline where a different host is orchestrating tool calls.
Claude Desktop MCP Servers Configuration
Claude Desktop stores MCP server configuration in a JSON file. The location depends on your OS:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
If the file doesn’t exist, create it. The structure looks like this:
{
"mcpServers": {
"my-tools": {
"command": "python",
"args": ["/path/to/mcp_server.py"],
"env": {
"API_KEY": "your_key_here"
}
}
}
}Each key under mcpServers is the server name Claude will use to identify it. You can register as many servers as you need — Claude Desktop loads all of them at startup.
After editing the file, restart Claude Desktop for the changes to take effect. You’ll see a hammer icon in the chat input area when MCP tools are successfully loaded.
Adding a remote MCP server via SSE
For remote servers that use Server-Sent Events (SSE) transport instead of stdio, the config shape is slightly different:
{
"mcpServers": {
"remote-tools": {
"url": "https://your-mcp-server.example.com/sse"
}
}
}Some remote servers require authentication. Pass a bearer token in the headers field if the server expects it:
{
"mcpServers": {
"remote-tools": {
"url": "https://your-mcp-server.example.com/sse",
"headers": {
"Authorization": "Bearer your_token_here"
}
}
}
}MCP Transport Types: stdio vs SSE
MCP servers communicate with the Claude host over one of two transport mechanisms:
stdio — The server runs as a subprocess on the same machine. The host launches the process and reads/writes JSON-RPC messages over standard input/output. This is the default for local servers and is the simplest to set up.
SSE (Server-Sent Events) — The server runs remotely and exposes an HTTP endpoint. The host connects to a URL and receives tool responses as a stream. This works across machines and is the right choice for shared team infrastructure or hosted tool services.
For most individual developers starting out, stdio is easier — no networking required, and the server process is managed for you. SSE becomes valuable when you want a team to share a single MCP server, or when the tool itself needs to run in a specific network environment.
How Claude Reasons Over MCP Tools
When a session starts and MCP servers are registered, Claude queries each server for its available tools. This produces a list of tool names and JSON Schema descriptions. Claude doesn’t call tools speculatively — it only invokes a tool when the conversation or task requires it, based on what the tool description says it does.
The tool-calling flow works like this:
- User sends a message or task.
- Claude evaluates whether any registered tool can help.
- If yes, Claude constructs a tool call with the appropriate arguments.
- The MCP host sends the call to the correct server.
- The server executes and returns a result.
- Claude incorporates the result into its reasoning and continues.
This loop can happen multiple times in a single turn — Claude can chain tool calls, use results from one tool to inform arguments to another, and aggregate across multiple servers in the same session.
The quality of tool descriptions matters a lot here. Vague descriptions lead to missed or incorrect invocations. Precise descriptions that include what the tool does, what its arguments mean, and what it returns let Claude route calls accurately without guessing.
Running Tool Execution in a Sandbox
When MCP tools execute code — Python scripts, shell commands, file operations — running them on your local machine raises questions about isolation. A tool with file system access, process spawning, or network calls has a broad reach if it misbehaves or is prompted into an unexpected path.
Novita AI Agent Sandbox addresses this by providing isolated cloud environments for tool execution. Instead of running your MCP server locally, you deploy it inside a sandbox instance. The sandbox gets its own file system, network scope, and resource limits. The agent can write files, run code, and call internal APIs inside that boundary without touching the host machine.
The MCP server running inside the sandbox exposes its tools through SSE transport, and Claude connects to it remotely — so from Claude’s perspective, the integration is identical. The difference is entirely in what the tool is actually running on.
Key characteristics of the Novita Sandbox for MCP deployments:
- Fast startup: instances launch in under ~200ms, keeping tool round-trip latency low
- Per-second billing: you pay only for active execution time, not idle reservation
- Isolated filesystem: each sandbox instance has a separate workspace, preventing cross-session data leakage
- Configurable network policy: control which external services the tool can reach
For a step-by-step guide to building an MCP server backed by a Novita Sandbox, see Build a Remote Code Execution MCP Server with Novita Sandbox and mcp-use Library.
Using Novita LLM API for MCP Tool-Use Reasoning
While Claude’s own models handle tool-use natively, you may want to route some MCP tool-use reasoning through a different model — for cost, latency, or specialization reasons. The Novita LLM API provides an OpenAI-compatible endpoint with access to models that support function calling and structured tool invocation.
This fits into MCP architectures in two ways:
1. As the reasoning model behind a custom MCP host: If you’re building your own MCP host (rather than using Claude Code or Claude Desktop), you can use the Novita LLM API to power the model layer. The host calls the Novita API with the tool list and conversation; the model returns tool call instructions; the host dispatches them to the MCP server.
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": "List the available tools and run a quick test"}],
tools=[
{
"type": "function",
"function": {
"name": "list_models",
"description": "List all available models from the API.",
"parameters": {"type": "object", "properties": {}},
}
}
],
tool_choice="auto",
)2. As the LLM inside an MCP tool itself: An MCP tool can use the Novita LLM API internally — for example, a summarization tool, a classification tool, or a tool that generates code. The tool accepts inputs from the agent, calls the Novita API, and returns the result. This keeps model inference costs separated from the main agent model costs and lets you choose the right model for each sub-task.
For a practical example of building an MCP server that calls Novita’s API, see How to Build Your First MCP Server with Novita AI.
Common Issues and Fixes
Server not appearing in Claude Desktop
The most common cause is a JSON syntax error in claude_desktop_config.json. Use a JSON validator before saving. Even a trailing comma will prevent the file from loading. Restart Claude Desktop after every edit.
claude mcp add command not found
This means Claude Code is either not installed or not in your PATH. Install Claude Code via npm install -g @anthropic-ai/claude-code and verify with claude --version.
Tools listed but never called
Claude only calls a tool when it believes the tool is relevant to the current task. If your tool descriptions are too vague, Claude won’t select them. Add specifics: what the tool does, when to use it, what its inputs and outputs look like.
Server exits immediately after launch
Check that the server command is correct and that all required environment variables are set. Run the command directly in a terminal to see the actual error output — Claude Code may suppress subprocess stderr in some configurations.
SSE connection refused
Verify that the server URL is reachable from the machine running Claude, that the server is actually listening on the expected port, and that any required auth headers are correctly configured.
Tool calls fail with validation errors
The arguments Claude passes must match the JSON Schema the tool declares. Review your tool’s inputSchema definition — if required fields are missing or types don’t match, the server will reject the call. Claude constructs arguments based on the schema, so an incomplete schema leads to incomplete calls.
FAQ
Does Claude Code support MCP?
Yes. Claude Code has native MCP support via the claude mcp subcommand. Use claude mcp add to register servers, claude mcp list to see what’s registered, and claude mcp remove to deregister. Run claude mcp --help for the full command reference.
How do I add an MCP server to Claude Code?
Run claude mcp add <name> <command> [args...] for a stdio server, or use --json to pass a JSON spec. For project-scoped registration, add --scope project. After adding, start a new Claude Code session — the tools will be available immediately.
What is claude mcp serve?
claude mcp serve runs Claude Code as an MCP server itself, exposing its capabilities through the MCP protocol. Another MCP host can then connect to Claude Code and use it as a tool source. This is useful when building multi-agent systems where Claude is one component among several.
Can I use the same MCP server in both Claude Code and Claude Desktop?
Yes. The server itself doesn’t care which host connects to it. For stdio servers, both Claude Code (via claude mcp add) and Claude Desktop (via claude_desktop_config.json) can launch the same command. For SSE servers, any host that can reach the URL can connect.
How does Claude know which MCP tool to call?
At session start, Claude queries all registered servers for their tool lists. Each tool has a name and a description. When processing a task, Claude selects tools based on whether their descriptions match what’s needed. Well-written descriptions with clear use cases lead to accurate tool selection; vague descriptions lead to missed or incorrect calls.
Is there a limit on how many MCP servers I can register?
The MCP spec doesn’t impose a hard limit, and neither does Claude Code or Claude Desktop. In practice, having dozens of servers with hundreds of tools can slow session startup (tool discovery runs at launch) and may add noise to Claude’s tool selection. Keep the tool set focused on what a given project or session actually needs.
What’s the difference between stdio and SSE transport?
Stdio runs the server as a local subprocess; the host communicates over stdin/stdout. SSE connects to a remote HTTP endpoint and receives responses as a stream. Stdio is simpler for local development; SSE is better for remote, shared, or production deployments.
