MCP Runtime

After an MCP server connects, Claude Code adds its tools, resources, and prompts to the session. The names, the permission rules, and the limits decide what Claude can use and for how long. Claude Code names a tool from a server mcp__<server>__<tool>. For example, mcp__github__create_issue is the create_issue tool of the github server.

This runs by itself once a server connects. Use permissions.deny for tools, ENABLE_TOOL_SEARCH for deferral, and CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS for background moves. Claude Code saves large results under tool-results.

Tools and Names

Source: Connect Claude Code to Tools via MCP, Configure Permissions, and the program for rows marked

Undocumented: Only the program shows this item. It can change without notice.

Item	Status	What It Does	How It Works
`mcp__<server>__<tool>`	Documented: An official docs page names this item.	Names an MCP tool.	Characters outside `A-Z a-z 0-9 _ -` in the server name become `_`. Claude Code leaves out a tool whose full name is over 128 characters. Used in permission rules, hooks, `tools`, and `allowed-tools`.
`mcp__plugin_<plugin>_<server>__<tool>`	Documented: An official docs page names this item.	Names a plugin server tool.	Its server name is `plugin:<plugin>:<server>`. A hook matcher on the bare server key never fires for it.
`mcp__github`, `mcp__github__`, `mcp__`	Documented: An official docs page names this item.	Select tools by server.	The first two match one server. `mcp__*` matches all MCP tools. Used in subagent `tools` and `disallowedTools`.
Hook matcher `mcp__memory__.*`	Documented: An official docs page names this item.	Matches a server in hooks.	A matcher with only exact-match characters, such as `mcp__memory`, matches no tool. You must add `.*`.
`mcp_server` hook input field	Documented: An official docs page names this item.	Gives the origin of the server.	An object with `name` and `source` (`plugin`, `sdk`, `user`, `project`, and more). Sent to tool hooks.
`mcp_tool` hook type	Documented: An official docs page names this item.	Calls an MCP tool as a hook.	The output counts as command stdout. Claude Code skips it on `Setup`, and at `SessionStart` before servers connect.
`updatedMCPToolOutput`	Documented: An official docs page names this item.	Replaces an MCP tool result.	Output of a `PostToolUse` hook. MCP tools only.
`ToolSearch`	Documented: An official docs page names this item.	Finds deferred MCP tools.	On by default. `permissions.deny: ["ToolSearch"]` turns the tool off.
`WaitForMcpServers`	Documented: An official docs page names this item. Gated: Works only behind a flag or a server gate. used when tool search is off	Waits for a connecting server.	Used when tool search is off. With tool search the wait happens inside `ToolSearch`. Works in the main session and subagents.
`SearchMcpRegistry`, `SuggestConnectors`, `ListConnectors`	Undocumented: Only the program shows this item. It can change without notice.	Find and list MCP connectors.	`SearchMcpRegistry` searches the connector registry by keyword. `ListConnectors` lists the connectors of the claude.ai organization.

Resources and Prompts

Item	Status	What It Does	How It Works
`@server:protocol://path`	Documented: An official docs page names this item.	Attaches a resource.	Claude Code fetches it as an attachment. The `@` menu has fuzzy search.
`ListMcpResourcesTool`	Documented: An official docs page names this item.	Lists resources of all servers.	The docs say Claude Code has tools to list and read resources but give no names. Each entry has a `server` field. `ui://` entries are hidden.
`ReadMcpResourceTool`	Documented: An official docs page names this item.	Reads one resource.	Parameters `server` and `uri`, both required.
`ReadMcpResourceDirTool`	Undocumented: Only the program shows this item. It can change without notice.	Lists the children of a directory resource.	Parameters `server` and `uri`. Uses `resources/directory/read`. Not recursive. Only for a server that declares directory support.
Old tool names	Undocumented: Only the program shows this item. It can change without notice.	Map old names to new.	`ListMcpResources`, `ReadMcpResource`, and `ReadMcpResourceDir` map to the `...Tool` names in rules and hooks.
`/server:prompt (MCP)` and `/mcp__server__prompt args`	Documented: An official docs page names this item.	Runs a server prompt.	Arguments split on whitespace. Results go into the conversation. Needs the prompt capability.
MCP Apps resources	Documented: An official docs page names this item.	UI pages for a host.	A `ui://` URI, or the media type `text/html` with the profile parameter `mcp-app`. Reading by URI still works.
`CLAUDE_CODE_MCP_APPS_HOST`	Undocumented: Only the program shows this item. It can change without notice.	Declares MCP Apps support.	Adds the extension `io.modelcontextprotocol/ui` with the MIME type to the client capabilities.

Elicitation and Channels

Elicitation is a server asking you for input. A channel is a way for a server to push messages into your session.

Item	Status	What It Does	How It Works
Elicitation dialog	Documented: An official docs page names this item.	Asks you for input.	`form` mode shows fields. `url` mode asks to open a link. The escaped URL has a cap of about 8000 characters. Claude Code declares `elicitation: {form: {}, url: {}}`.
`Elicitation` hook	Documented: An official docs page names this item.	Answers a request.	Input: `mcp_server_name`, `message`, `mode`, `url`, `elicitation_id`, `requested_schema`. Output action: `accept` (with `content`), `decline`, or `cancel`.
`ElicitationResult` hook	Documented: An official docs page names this item.	Observes or overrides the answer.	Input has `action` and `content`. Runs before the answer goes to the server.
`claude/channel` capability	Documented: An official docs page names this item.	Lets a server push messages.	You opt in with `--channels`. Claude Code does not register it on a v2 connection that agreed on revision 2026-07-28.
`claude/channel/permission`	Documented: An official docs page names this item.	Relays permission prompts over a channel.	Notifications `notifications/claude/channel/permission_request` and `.../permission`.
`channels` plugin key	Documented: An official docs page names this item.	Binds a channel to a plugin server.	Fields `server`, `displayName`, `userConfig`. In `plugin.json`.

Source: Channels Reference and Push Events into a Running Session with Channels.

Limits

Item	Status	What It Does	How It Works
Output warning	Documented: An official docs page names this item.	Warns on large output.	Fixed at 10000 tokens.
`MAX_MCP_OUTPUT_TOKENS`	Documented: An official docs page names this item.	Sets the token limit of a result.	Default 25000. Over the limit, Claude Code saves the result to a file in `tool-results` and shows the path. Images stay under this limit.
50000 characters	Documented: An official docs page names this item.	File threshold for text.	Claude Code saves a successful text result over 50000 characters to a file, whatever the token count.
`ENABLE_MCP_LARGE_OUTPUT_FILES`	Undocumented: Only the program shows this item. It can change without notice.	Switch for the file path.	When `false`, Claude Code truncates instead of saving to a file.
`_meta["anthropic/maxResultSizeChars"]`	Documented: An official docs page names this item.	Raises the threshold for one tool.	Up to 500000 characters. Text only. Set in the `tools/list` entry.
`_meta["anthropic/requiresUserInteraction"]`	Documented: An official docs page names this item.	Always asks.	Only JSON `true` counts. It prompts in all modes. `dontAsk` denies. With `--permission-prompt-tool`, an allow becomes a deny.
`_meta["anthropic/alwaysLoad"]`	Documented: An official docs page names this item.	Loads a tool upfront.	`false` keeps it deferred when the user config sets `alwaysLoad: true` (`2.1.285` and later).
Error text	Documented: An official docs page names this item.	Shortens long errors.	Over about 11000 characters, the first 5000 and last 5000 stay. For `isError: true` results.
16 MiB response	Documented: An official docs page names this item.	Caps one response or message.	HTTP and SSE stop reading. A WebSocket closes the connection.
Description limits	Documented: An official docs page names this item.	Cuts long text.	4096 characters for server instructions and an upfront tool. 16384 for a tool found by tool search. `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH` replaces both.
Schema checks	Documented: An official docs page names this item.	Drops bad tools.	Excludes a tool with a bad top-level property name or an invalid 2020-12 schema. Flattens a root `anyOf`, `oneOf`, or `allOf`.

Timing and Recovery

Item	Status	What It Does	How It Works
Auto background	Documented: An official docs page names this item.	Moves a long call to a task.	After 120000 ms in the main conversation. Not for subagents, IDE servers, or `-p` unless `CLAUDE_AUTO_BACKGROUND_TASKS=1`.
Idle timeout	Documented: An official docs page names this item.	Aborts a silent call.	5 minutes for remote servers, 30 minutes for stdio. `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` changes it. `0` turns it off. Not for IDE and `sdk` servers.
Reconnection	Documented: An official docs page names this item.	Retries a dropped remote server.	Five tries with backoff from 1 s. Claude Code does not reconnect stdio. The first connect retries 3 times, except `ws` and auth errors.
`list_changed`	Documented: An official docs page names this item.	Refreshes tools, prompts, and resources.	Interactive sessions refresh all three. `-p` refreshes tools only. A failed refresh keeps the old lists.
Stdio shutdown	Documented: An official docs page names this item.	Stops a stdio server.	On macOS and Linux: `SIGINT`, then `SIGTERM` after 100 ms, then `SIGKILL` after 400 ms more.
`roots/list`	Documented: An official docs page names this item.	Tells servers which folders Claude Code allows.	Answers with the launch folder and added folders.
Tool search modes	Documented: An official docs page names this item.	Controls deferral.	`ENABLE_TOOL_SEARCH`: not set, `true`, `auto`, `auto:N`, or `false`. Since 2.1.304 tool search is on by default behind a custom `ANTHROPIC_BASE_URL`, and a 400 or 422 from the gateway is retried without it. Since 2.1.305 the retry also covers an endpoint or gateway that rejects tool search, and a `ToolSearch` that is disallowed or left out of `--tools` (v2.1.305 release). After a refusal the program says `Tool search is off for this conversation: the endpoint refused it earlier in this process.` `ENABLE_TOOL_SEARCH=true` overrides a conversation that ran without `ToolSearch`, which stays that way until it is compacted or cleared (the program).

Example

Settings: allow one server's tools, deny another's
{
  "permissions": {
    "allow": ["mcp__github__*"],
    "deny": ["mcp__untrusted"]
  }
}

Hook matcher for every tool of the memory server
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__memory__.*",
        "hooks": [{ "type": "command", "command": "./audit.sh" }]
      }
    ]
  }
}

How It Works

Errors

Rows with a start of a message are families. The backticked text is the start that every message in the family shares.

Start of Message	Status	What It Means	Cases
`.mcp.json is malformed (not valid JSON, or mcpServers is not an object)`	Undocumented: Only the program shows this item. It can change without notice.	Claude Code could not read the project `.mcp.json`.	The file is not valid JSON, or `mcpServers` is not an object.
`MCP server "`	Undocumented: Only the program shows this item. It can change without notice.	A tool call or command named a server that cannot be used.	Managed policy blocks the server, the server is disabled (re-enable it with `/mcp`), or Claude Code did not find it.
`Server "`	Undocumented: Only the program shows this item. It can change without notice.	A server operation failed.	The server does not support resources, is not connected, or was not found. The last case lists the available servers.
`No MCP server named`	Undocumented: Only the program shows this item. It can change without notice.	A server name is not in the scope that the command searched.	The scope is `.mcp.json`, local, or user.
`StdioClientTransport already started`, `MCP tool call to server`, `Missing required ${…}: ${…}. Usage: /mcp__`, `The tool call was interrupted`, `Unsupported server type`, `claude.ai MCP proxy is not available`, `No claude.ai OAuth token`, `The "${…}" connector`, `"${…}" was disabled while reconnecting`, `Connection failed`, `Server status:`, `The result of MCP tool`	Undocumented: Only the program shows this item. It can change without notice.	An MCP server or tool call failed.	One of these causes applies. The server or client does not support a capability that the call needs (roots, sampling, elicitation, tasks, resources). The tool call was interrupted or aborted because the account changed. A required argument is missing. The server type is not supported.

MCP
MCP Env Vars
Plugin Manifest for the channels key
Agent Loop for how tool calls run

Tools and Names​

Resources and Prompts​

Elicitation and Channels​

Limits​

Timing and Recovery​

Example​

How It Works​

Errors​

Related Pages​