7. Connecting tools

• For stdio, everything after -- is the server's command, passed through untouched. Without it, Claude Code would try to read the server's flags as its own.
• A JSON entry with a url and no type is an error, because no type means stdio. Add "type": "http".
• A connected server can offer more than tools: resources you @-mention (@github:issue://123), prompts that become commands (/mcp__github__pr_review 456), and elicitation, where the server asks you to fill a form or open a sign-in link.

• MCP local scope is not .claude/settings.local.json. It lives in your home directory, inside ~/.claude.json.
• When the same server appears in several places, one whole definition wins, with no merging of fields: local, then project, then user, then plugin servers, then claude.ai connectors. A server your organization provides through managedMcpServers beats all of them (v2.1.259 or later).
• Project servers ask first. In an interactive session you approve each .mcp.json server before it connects; claude mcp reset-project-choices clears your answers. A cloned repo can't approve its own servers until you trust the folder.
• Except where nobody can be asked: claude -p, Agent SDK, and cloud sessions load project servers without the prompt. disabledMcpjsonServers keeps a server out in every mode, and --strict-mcp-config uses only the servers you pass with --mcp-config.
• .mcp.json can use ${VAR} and ${VAR:-default} in command, args, env, url, and headers, so the file can be shared without secrets in it.
• Your own credentials stay home. In a remote server's url or headers, names like ANTHROPIC_API_KEY and AWS_BEARER_TOKEN_BEDROCK read as empty, so a repo can't send your keys to a server it names.

Tool definitions are big. With tool search, on by default, Claude Code loads only each tool's name and each server's instructions at the start, and pulls in a tool's full definition when Claude searches for it. There's no fixed cap on tools per server; the practical limit is your context window.

• "alwaysLoad": true on a server puts its tools in context every turn, and startup waits for them, up to the 5-second connect timeout. Use it for a handful of tools Claude needs constantly.
• Server instructions matter more with tool search on: they're how Claude knows when to search for a server's tools. They're cut at 4,096 characters, the same as the description of a tool that loads upfront; a deferred tool's description gets 16,384.
• /context shows tools labeled deferred, which is how you prove tool search is doing its job.

• 10,000 tokens: a tool result that big shows a warning.
• 25,000 tokens: the default maximum, raised with MAX_MCP_OUTPUT_TOKENS. A bigger result is saved to a file Claude can read when it needs to, not dropped.
• 50,000 characters: a text result longer than this goes to a file too, whatever its token count. A server author can raise one tool's threshold with anthropic/maxResultSizeChars, up to 500,000.
• 16 MiB: the largest single response Claude Code reads from an HTTP or SSE server.
• 2 minutes: a main-conversation call still running moves to a background task you can see in /tasks.
• Idle timeout: 5 minutes with no response or progress for remote servers, 30 for stdio.
• 128 characters: a tool whose full name, mcp__server__tool, runs longer is left out so the server's other tools still work.

• A remote server that answers 401 or 403 is flagged; Claude Code shows a startup notice. Run /mcp, pick the server, and sign in in your browser. Tokens are stored securely and refreshed automatically.
• claude mcp login <name> signs in from your shell; --no-browser prints the URL instead, for SSH sessions. claude mcp logout <name> or Clear authentication in /mcp revokes it.
• Static tokens go in --header "Authorization: Bearer ...". If the server rejects that header, the connection fails; it doesn't fall back to OAuth.
• Headless runs can't sign in. claude -p and the Agent SDK have no /mcp panel, so sign in from an interactive session first.
• claude mcp remove also deletes the server's stored OAuth tokens.

• Anthropic reviews Directory connectors against listing criteria, but doesn't security-audit or manage any MCP server. Write your own, or use servers from providers you trust.
• Prompt injection is the main risk: a server that fetches web pages, issues, or email hands Claude text an attacker could have written.
• .mcp.json isn't the whole list. User and local scope, plugins, and claude.ai connectors all add servers from outside the repo.
• The controls stack: permission rules on mcp__server__tool names (Module 5), hooks matching mcp__.* (Module 6), requiresUserInteraction on a tool so every call prompts even in auto mode, and least-privilege credentials, such as a read-only database user.

• Every server is checked in three steps: merge the allow and deny lists from every scope, check the denylist (a match always blocks), then check the allowlist (remote servers match by serverUrl, stdio servers by serverCommand).
• serverName is a label, not a control. A user can call any server github. Enforce with URL or command entries.
• allowedMcpServers: [] allows nothing; leaving it out allows everything.
• Without allowManagedMcpServersOnly, a user's own allowlist entries merge in and can widen yours. Denylists always merge, so anyone can block servers for themselves.
• managed-mcp.json lives at a system path: /Library/Application Support/ClaudeCode/ on macOS, /etc/claude-code/ on Linux and WSL, C:\Program Files\ClaudeCode\ on Windows. It can't come through server-managed settings, so it travels by MDM.

Opens the server list: each server's status, its tool count, and sign-in. From a server's menu you can authenticate, reconnect, disable it for this project, or clear its authentication. /mcp reconnect <server> or reconnect all, /mcp enable, and /mcp disable change state without opening the list. In a -p run, /mcp prints a text summary instead.