skip to content

MCP Integration

MCP servers turn trackers, databases and browsers into tools, resources and prompts in a session: adding and scoping them, signing in, and using them. Asked because MCP replaces bespoke glue.

part ofClaude Coderead it →
on this pageshow

explore

questions

12

In Claude Code, how do you add a local stdio MCP server that needs an API key, and why does the `--` separator matter?

level: juniorimportance: must knowfreq 22%

answer

  1. a process Claude Code starts itself
  2. stdio is the default transport
  3. --env before the name, not right before it
  4. everything after -- goes to the server
  5. claude mcp get shows the saved command

basics

~20 s

Run claude mcp add with --env KEY=value, the server name, then -- and the launch command. Everything after -- reaches the server untouched; without it, Claude Code parses the server's flags, such as -y or --port, as its own.

solid answer

~50 s

A stdio server is a program Claude Code launches as a subprocess, so you register the command that starts it: `claude mcp add --env DB_URL=... --transport stdio orders-db -- npx -y @example/db-mcp-server`. `stdio` is the default transport, so `--transport stdio` is optional. The `--` separates Claude's own options (`--transport`, `--env`, `--scope`) from the server's command line; everything after it is passed through untouched, while without it Claude Code tries to read flags like `-y` or `--port 8080` as its own. One more trap: `--env` takes several `KEY=value` pairs, so if the server name comes straight after it the CLI reads the name as another pair and rejects it — put another option between them. The entry lands at local scope by default, and `Added ...` only means it was saved: check it with `claude mcp list` or `claude mcp get`.

code

bash · 7 lines
bash
# stdio is the default transport; --transport stdio also keeps --env away from the name
claude mcp add --env DB_URL=postgres://localhost:5432/orders --transport stdio \
  orders-db -- npx -y @example/db-mcp-server

# 'Added ...' means saved, not running: check the command and the connection
claude mcp get orders-db
claude mcp list

go deeper

for a junior

Recall the shape: claude mcp add, options, the name, then -- and the command that starts the server. Know that stdio is the default transport.

for a middle

Explain why the separator exists: Claude Code's parser would otherwise claim the server's own flags. Mention the --env ordering trap and that local scope is where the entry lands.

for a senior

Show the debugging loop: claude mcp get to compare the stored command, running that command by hand, MCP_TIMEOUT for slow first starts, and keeping credentials in --env at local scope.

for a principal

Frame stdio servers as code you run with your own privileges: decide which launch commands a team standardises on and how credentials reach them without landing in shared files.

## What a stdio server is An **MCP server** gives Claude Code extra tools, resources and prompts. A **stdio server** is one that Claude Code starts itself, as a child process on your machine, and talks to over that process's standard input and output. That makes it the natural choice for anything that needs local access: a database socket, your filesystem, a browser, an internal script. Because Claude Code launches it, what you register is not a URL but **the command that starts the server**. Claude Code also sets `CLAUDE_PROJECT_DIR` in the spawned server's environment, pointing at the project root, so a server can resolve project-relative paths without depending on the working directory it happens to start in. ## The command and its parts The general shape is `claude mcp add [options] <name> -- <command> [args...]`: 1. `claude mcp add` — the subcommand that writes a server entry to configuration. 2. **Options for Claude Code**: `--transport stdio` (optional, because `stdio` is the default transport), `--env KEY=value` for environment variables the server needs, `--scope local|project|user` for where the entry is stored. 3. **The server name** — only letters, numbers, hyphens and underscores. 4. `--` — the separator. 5. **The server's own command line**, passed untouched: `npx -y @example/db-mcp-server`, `python server.py --port 8080`, a binary path. ## Why `--` matters Without the separator, Claude Code's argument parser sees every flag on the line as a candidate option of `claude mcp add`. A server command such as `python server.py --port 8080` or `npx -y some-package` carries flags of its own, and Claude Code would try to interpret `--port` or `-y` itself. With `--`, the parser stops at the separator and stores everything after it as the server's command and arguments. | You type | Claude Code runs | |---|---| | `claude mcp add --transport stdio myserver -- npx server` | `npx server` | | `claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080` | `python server.py --port 8080`, with `KEY=value` in its environment | The same rule applies when you translate setup instructions written for another MCP client: a launch command such as `npx -y @example/mcp-server` goes after `--`, and any environment variables the instructions mention go in `--env`, after the server name and before `--`. ## The `--env` ordering trap `--env` accepts **multiple** `KEY=value` pairs. If you write `claude mcp add --env API_KEY=abc airtable -- npx -y airtable-mcp-server`, the CLI reads `airtable` as another pair and rejects it. The fix is ordering, not a different flag: place at least one other option, such as `--transport stdio`, between `--env` and the name, or put `--env` after the name and before `--`. ## Where the entry goes and how to check it - With no `--scope`, the entry is written at **local scope**: `~/.claude.json`, under the current project's path, private to you. That is the right home for a server whose `--env` value is a credential, because nothing lands in the repository. - The `Added stdio MCP server ...` line means the configuration was **saved**, not that the command runs. - `claude mcp list` shows a health status per server (`✔ Connected`, `✘ Failed to connect`); a first check can fail while `npx` is still downloading the package. - `claude mcp get <name>` shows the stored command. If it differs from what you typed, the usual cause is a missing `--`: remove the server with `claude mcp remove <name>` and add it again. - A slow first start can exceed the 30-second startup timeout; raise it with `MCP_TIMEOUT` (milliseconds). - Inside a session, `/mcp` shows the same status and lets you reconnect. ## Common mistakes - Leaving out `--` and wondering why `-y` or `--port` vanished or caused an error. - Putting the name immediately after an `--env` pair. - Passing a value the server reads from its environment as an argument after `--`, instead of through `--env`. - Adding the server from a different directory and then not finding it: local-scope servers belong to the project (the repository root, or the exact directory outside a repository) where you added them. - Writing the server into a shared file when it carries a personal credential; local scope keeps it out of version control.

  • `claude mcp get orders-db` shows a command without the `-y` you typed. What happened and how do you fix it?
    The `--` separator was missing, so Claude Code parsed `-y` as one of its own options instead of storing it with the server's command. A server's scope and command are fixed once added, so run `claude mcp remove orders-db` and add it again with `--` before the launch command.
  • The first `claude mcp list` after adding an `npx`-launched server shows `✘ Failed to connect`. What do you check before debugging the server?
    Whether `npx` was still downloading the package: the first start can be slow, so wait and run `claude mcp list` again. If it persists, run the stored command yourself in a terminal to see its error, and if startup is merely slow, raise `MCP_TIMEOUT` above its 30-second default.

  • Claude Code passes every flag after the server name to the server automatically
  • A stdio server always needs --transport stdio spelled out
  • The Added line proves the server started and connected
  • --env can sit directly before the server name without problems
  • A local-scope server appears in every project you open
open as a page

In Claude Code, what does a connected MCP server add to a session, and how are its tools, resources and prompts invoked?

level: juniorimportance: must knowfreq 22%

basics

~10 s

Claude Code exposes a server's tools for Claude to call as mcp__server__tool, its resources as @server:protocol://path mentions you attach, and its prompts as commands listed as /server:prompt (MCP) or typed as /mcp__server__prompt.

open as a page

In Claude Code, how do the local, project and user MCP server scopes differ, and which one is the default?

level: middleimportance: must knowfreq 18%

basics

~20 s

Local, the default, is private to you and one project, stored in ~/.claude.json under that project's path. Project writes .mcp.json at the repository root for everyone who clones it. User is private to you across all projects.

open as a page

In Claude Code, how is a connected MCP server's tool named, and how do you write permission rules for one tool or a whole server?

level: middleimportance: must knowfreq 18%

basics

~20 s

Claude Code names each MCP tool mcp__<server><tool>, using the server name from your configuration. The rule mcp__server or mcp__server* covers every tool on that server, mcp__server__tool covers one, and an allow glob must start with a literal server prefix.

open as a page

How do you share an MCP server through a Claude Code project's `.mcp.json` without committing anyone's token, and where can `${VAR}` expansion fail you?

level: seniorimportance: should knowfreq 8%

basics

~20 s

Reference each developer's own variable as ${VAR} or ${VAR:-default} in command, args, env, url or headers. Unset without a default, it stays literal text with a warning; credential names like ANTHROPIC_API_KEY read as empty in remote url and headers.

open as a page

A teammate commits a `.mcp.json` to a repository — what does Claude Code do before connecting its servers on a fresh clone, and when does that check not apply?

level: seniorimportance: should knowfreq 7%

basics

~20 s

An interactive session asks you to approve each .mcp.json server on first use, and approvals committed in the repository are ignored until you trust the folder. claude -p, SDK and cloud sessions cannot ask, so they load project servers unprompted.

open as a page

In Claude Code, an MCP tool returns a 60,000-token database dump: what do the output warning and limit do, and how do MAX_MCP_OUTPUT_TOKENS and maxResultSizeChars change them?

level: seniorimportance: should knowfreq 8%

basics

~20 s

Claude Code warns when MCP output passes 10,000 tokens and caps it at 25,000 by default, saving an oversized text result to a file and passing its path. MAX_MCP_OUTPUT_TOKENS raises the cap; a tool's anthropic/maxResultSizeChars overrides it for text.

open as a page

A Claude Code session with a dozen MCP servers feels slow and context-heavy: how does tool search defer their definitions, and how does ENABLE_TOOL_SEARCH change it?

level: seniorimportance: should knowfreq 12%

basics

~20 s

By default Claude Code loads only MCP tool names and server instructions, and the ToolSearch tool loads full definitions on demand. ENABLE_TOOL_SEARCH overrides it: true defers even behind a proxy, auto or auto:N defers past a context threshold, false loads everything.

open as a page

When adding a remote MCP server to Claude Code, how do you choose between the http, sse and ws transports?

level: middleimportance: nice to knowfreq 9%

basics

~20 s

Use http, the recommended transport. SSE is deprecated; since 2.1.265 an http add falls back to SSE automatically. WebSocket (ws) is configured only through .mcp.json or claude mcp add-json, authenticates with headers only, and never with OAuth.

open as a page

What does `claude mcp serve` expose to another MCP client, and who must confirm each tool call that client makes through it?

level: middleimportance: nice to knowfreq 3%

basics

~20 s

claude mcp serve runs Claude Code as a stdio MCP server exposing Claude Code's own tools, such as reading and editing files, to the connecting client. It prints nothing on start, and the client must confirm individual tool calls.

open as a page

Your internal MCP server takes short-lived SSO tokens rather than OAuth — how do you authenticate it in Claude Code, and how does that differ from signing in through `/mcp`?

level: seniorimportance: nice to knowfreq 6%

basics

~20 s

Set headersHelper: a command printing a JSON object of headers, run fresh on every connection and re-run once after a 401 or 403. /mcp is for OAuth servers: Claude Code runs a browser sign-in, then stores and refreshes the tokens.

open as a page

How do Claude Code channels push external events into a running session, and what must be true before a channel server's messages actually arrive?

level: seniorimportance: nice to knowfreq 4%

basics

~20 s

A channel is an MCP server declaring the claude/channel capability that pushes events into an open Claude Code session. They arrive only if you name it with --channels at startup, it is allowlisted, and your organization permits channels.

open as a page