MCP (Model Context Protocol) Commands & Prompt Reference
Two layers of the Model Context Protocol: the JSON-RPC methods, notifications, metadata keys, HTTP headers and error codes of the 2026-07-28 MCP specification, checked against its schema.ts, and client setup in Claude Code v2.1.296 (the claude mcp commands, .mcp.json fields and environment variables). The 2026-07-28 revision is stateless: there is no initialize handshake, so every request carries its protocol version and client capabilities. Methods removed in that revision, the tasks extension and OAuth internals are left out.
All Commands
Server requests (10)
| Command / Syntax | What it does | Notes |
|---|---|---|
| server/discover | Discover versions and capabilities | Returns supportedVersions, server capabilities and optional instructions; clients may skip it because each request states its version. |
| tools/list | List the server's tools | Paginated with cursor and nextCursor; the result also carries ttlMs and cacheScope so clients can cache it. |
| tools/call | Call a tool | Params are the tool name and an arguments object; a failing tool reports isError in its result rather than a protocol error. |
| resources/list | List readable resources | Returns concrete resources by URI, paginated and cacheable; URI patterns come from resources/templates/list instead. |
| resources/templates/list | List resource templates | Templates describe parameterised URIs, and completion/complete can suggest values for their variables. |
| resources/read | Read a resource | Takes a single uri whose scheme the server interprets; the result carries the same caching hints as list results. |
| prompts/list | List prompt templates | Paginated and cacheable; each prompt entry names the arguments that its template accepts. |
| prompts/get | Fetch a filled-in prompt | Send the prompt name plus string arguments; the reply is the list of messages built from that template. |
| completion/complete | Suggest argument values | Gives completion candidates for a prompt or resource-template argument from its name, the partial value and earlier arguments. |
| subscriptions/listen | Open a notification stream | The client opts in to list-change types or resource URIs; replaces the HTTP GET stream and resources/subscribe of earlier revisions. |
Notifications (8)
| Command / Syntax | What it does | Notes |
|---|---|---|
| notifications/progress | Report progress | Sent only for a request whose _meta carried a progressToken; fields are progress, an optional total and a message. |
| notifications/cancelled | Cancel a request | Names the requestId plus an optional reason; on stdio a server sends it only to close a subscriptions/listen stream. |
| notifications/message | Send a log message | Deprecated with Logging in this revision; servers emit it only for requests that set io.modelcontextprotocol/logLevel. |
| notifications/tools/list_changed | Tool list changed | Arrives on a listen stream only if the client asked for toolsListChanged; fetch tools/list again afterwards. |
| notifications/prompts/list_changed | Prompt list changed | Delivered when the listen request set promptsListChanged, telling the client to call prompts/list again. |
| notifications/resources/list_changed | Resource list changed | Opt in with resourcesListChanged on subscriptions/listen; resources/list would now return a different set. |
| notifications/resources/updated | Resource content updated | Sent for URIs the client named in resourceSubscriptions; read the resource again to get the new content. |
| notifications/subscriptions/acknowledged | Confirm a subscription | First message on a new listen stream; it echoes only the notification types this server will really send. |
Multi round-trip input (7)
| Command / Syntax | What it does | Notes |
|---|---|---|
| input_required | Result that needs more input | Marks an interim result holding inputRequests; final results use complete, and results from older servers count as complete. |
| inputRequests | Server's questions for the client | A map of elicitation, sampling or roots requests that the client answers before it repeats the call. |
| inputResponses | Answers sent on the retry | Uses the same keys as inputRequests and rides in the params of the repeated request. |
| requestState | Opaque state for the retry | The client copies it back unmodified; a server may return only this field, with no input requests at all. |
| elicitation/create | Ask the user for input | Form-mode elicitation collects fields from a flat JSON schema; URL mode sends the user to a web page for sensitive data. |
| sampling/createMessage | Request an LLM completion | Deprecated in this revision but kept for at least a year; needs the sampling client capability, and the client picks the model. |
| roots/list | List client roots | Deprecated; the client replies with file:// URIs of directories or files the server may operate on. |
Request metadata keys (9)
| Command / Syntax | What it does | Notes |
|---|---|---|
| io.modelcontextprotocol/protocolVersion | Protocol version per request | Required in every request's _meta; on HTTP it must equal the version header, or the server rejects the call with 400. |
| io.modelcontextprotocol/clientCapabilities | Client capabilities per request | Required; an empty object declares no optional features, and servers may not carry capabilities over from earlier calls. |
| io.modelcontextprotocol/clientInfo | Client name and version | Recommended on each request for display and logs; servers should neither change behaviour nor base security on it. |
| io.modelcontextprotocol/serverInfo | Server name and version | Goes in each result's _meta in place of a handshake reply; clients treat it as unverified display data. |
| io.modelcontextprotocol/logLevel | Per-request log level | Deprecated; without it the server sends no log notifications for that request. It replaces the removed logging/setLevel call. |
| io.modelcontextprotocol/subscriptionId | Tag a stream notification | Set to the ID of the originating listen call; progress and other request-bound notifications go without it. |
| progressToken | Request progress updates | An opaque value echoed in each notifications/progress message; the receiver is free to send none. |
| cursor | Fetch the next page | Send back the nextCursor value of the previous list result to continue after its last item. |
| ttlMs | Cache lifetime hint | Milliseconds a list or read result stays fresh; 0 means stale at once, and cacheScope says whether shared caches may keep it. |
HTTP headers and error codes (9)
| Command / Syntax | What it does | Notes |
|---|---|---|
| MCP-Protocol-Version | Protocol version header | Mandatory on each POST and must match the version in the body, otherwise the server answers 400 Bad Request. |
| Mcp-Method | Method name header | Mirrors the JSON-RPC method on every request so gateways and load balancers can route without reading the body. |
| Mcp-Name | Tool, prompt or resource name header | Required on tools/call, prompts/get and resources/read; values that are not plain ASCII use the Base64 sentinel form. |
| x-mcp-header | Tool parameter header mapping | A server marks an inputSchema property with it, and HTTP clients must then send that argument as an Mcp-Param- header. |
| -32601 | Method not found | Over HTTP it comes with a 404 status; the JSON-RPC body tells it apart from a legacy HTTP+SSE server's 404. |
| -32602 | Invalid params or unknown resource | Since this revision it also reports a missing resource, which earlier revisions signalled with -32002. |
| -32020 | Header mismatch | Comes with HTTP 400 when a mirrored header disagrees with the body or a required header is absent. |
| -32021 | Missing client capability | Its data lists requiredCapabilities, so the client can retry after declaring what the server needs. |
| -32022 | Unsupported protocol version | Its data holds the supported versions and the requested one; choose a shared version and send the request again. |
Claude Code server commands (12)
| Command / Syntax | What it does | Notes |
|---|---|---|
| claude mcp add --transport http <name> <url> | Add a remote HTTP server | The recommended remote transport; from v2.1.265 Claude Code falls back to SSE when a server rejects HTTP. |
| claude mcp add [options] <name> -- <command> [args...] | Add a local stdio server | Everything after the double dash goes to the server untouched, so its own flags are not read as Claude options. |
| claude mcp add --transport sse <name> <url> | Add a legacy SSE server | Deprecated transport; needed only before v2.1.265, or to skip the HTTP attempt and connect over SSE directly. |
| claude mcp add-json <name> '<json>' | Add a server from JSON | Pass the entry itself, not the mcpServers wrapper; this is also how WebSocket (ws) servers are added. |
| claude mcp add-from-claude-desktop | Import Claude Desktop servers | macOS and WSL only; a picker selects servers, and names containing spaces or other symbols are skipped. |
| claude mcp list | List configured servers | Prints a health status per server, such as Connected, Needs authentication, Pending approval or Failed to connect. |
| claude mcp get <name> | Show one server's details | Adds an Issue line with the HTTP status or server error text when the connection failed. |
| claude mcp remove <name> | Remove a server | Add --scope when one name is defined in several scopes, to choose which definition is deleted. |
| claude mcp login <name> | Sign in to a server | Works for HTTP, SSE and claude.ai connector servers without opening the in-session panel. |
| claude mcp logout <name> | Clear a saved sign-in | Deletes the OAuth tokens kept for that server; sign in again with claude mcp login when needed. |
| claude mcp reset-project-choices | Reset .mcp.json approvals | Interactive sessions then ask again before starting project servers; claude -p and SDK runs never show that prompt. |
| claude mcp serve | Run Claude Code as a server | Prints nothing while it waits on stdin; register it in Claude Desktop or another client as a stdio server. |
Claude Code add and login flags (7)
| Command / Syntax | What it does | Notes |
|---|---|---|
| --scope | Choose where the server is saved | local is the default and private to this project, project writes .mcp.json for the team, user covers all projects. |
| --env KEY=value | Pass an environment variable | For stdio servers; several pairs are allowed, but put another option between the last pair and the server name. |
| --header | Send an HTTP header | Short form -H; the usual way to hand an API key or bearer token to an HTTP or SSE server. |
| --callback-port | Fix the OAuth callback port | Without it a random port is used; works alone with dynamic registration or together with --client-id. |
| --client-id | Use a pre-registered OAuth app | For servers that lack dynamic client registration; a public client without a secret needs only this flag. |
| --client-secret | Store an OAuth client secret | Asks for the secret with hidden input or reads MCP_CLIENT_SECRET; it can be set only when the server is added. |
| --no-browser | Print the sign-in URL instead | For SSH sessions: open the printed URL on your own machine, then paste the full redirect URL back at the prompt. |
Claude Code .mcp.json fields (7)
| Command / Syntax | What it does | Notes |
|---|---|---|
| .mcp.json | Project-scope server file | Lives at the repository root and is meant for version control; Claude Code asks before using its servers. |
| mcpServers | Top-level server map | Each key is a server name; claude mcp add-json takes one inner entry rather than this wrapper. |
| command / args | Launch command for stdio | An entry without type is treated as stdio, and both fields accept ${VAR} expansion. |
| env | Server environment variables | An object of name-value pairs for a stdio server; Claude Code warns about stray whitespace in its keys or values. |
| type / url | Transport and endpoint | type is stdio, http (alias streamable-http), sse or ws; a url with no type is reported as a configuration error. |
| headers | Request headers for remote servers | Holds static API keys or bearer tokens; headersHelper can generate them at connect time instead. |
| ${VAR:-default} | Expand a variable with fallback | Plain ${VAR} has no fallback; both forms work in command, args, env, url and headers. |
Claude Code environment variables (8)
| Command / Syntax | What it does | Notes |
|---|---|---|
| MAX_MCP_OUTPUT_TOKENS | Cap MCP tool output | Default 25,000 tokens with a fixed warning at 10,000; text over 50,000 characters is saved to a file anyway. |
| MCP_TIMEOUT | Server startup timeout | Set it on the launch line, for example MCP_TIMEOUT=10000 claude, to give servers ten seconds. |
| MCP_TOOL_TIMEOUT | Tool call time limit | A per-server timeout field in .mcp.json overrides it; remote servers also have a separate 60-second request timer. |
| CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT | Abort silent tool calls | Defaults to 5 minutes for network servers and 30 for stdio; 0 switches the idle check off. |
| CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS | Background long tool calls | Only main-conversation calls move; 0 turns this off, and the result arrives later as a task notification. |
| CLAUDE_CODE_DISABLE_BACKGROUND_TASKS | Turn off background tasks | Set to 1 to stop MCP auto-backgrounding along with every other background feature. |
| MCP_CLIENT_SECRET | OAuth client secret | Read only while a server is added with --client-secret; later sign-ins reuse the stored secret. |
| MCP_PROTOCOL_NEGOTIATION | Probe for the 2026-07-28 revision | v2 runtime only: auto checks HTTP, connector and stdio servers, while legacy keeps every server on the older handshake. |
Using servers in a Claude Code session (5)
| Command / Syntax | What it does | Notes |
|---|---|---|
| /mcp | Open the MCP panel | The in-session command for server status, OAuth sign-in or Clear authentication, and per-project on/off toggles. |
| @server:protocol://resource/path | Mention an MCP resource | Type @ to browse resources from connected servers next to files; several can go in one prompt. |
| /mcp__servername__promptname | Run a server prompt | Arguments follow, separated by spaces, one token each; the menu lists it as /servername:promptname (MCP). |
| --mcp-config | Load servers from a JSON file | A claude startup flag, not a claude mcp subcommand; with -p it waits for pending servers up to MCP_TIMEOUT. |
| --strict-mcp-config | Use only the passed config | Ignores every other server definition; since v2.1.246 it also skips the approval prompt for unused .mcp.json servers. |
Recipes
Our own notes on combining the entries above. Each method, key and command used here appears in the tables on this page; names such as get_weather are examples.
Call a tool over Streamable HTTP
POST → MCP-Protocol-Version: 2026-07-28, Mcp-Method: tools/call, Mcp-Name: get_weather
The version header must match io.modelcontextprotocol/protocolVersion in the body's _meta, and the method and tool name are mirrored from the body so gateways can route the call. A server that does not speak that version answers 400 with -32022 and lists the versions it accepts.
Ask the user for a value in the middle of a tool call
tools/call → input_required with inputRequests (elicitation/create) → tools/call with inputResponses and requestState
The server does not send its own request to the client any more. It returns an interim result; the client shows the form, then repeats the original tools/call with the answers under the same keys and the requestState copied back unchanged.
Expose Claude Code itself as a server to another MCP client
claude mcp serve → register as a local stdio server in the other client
claude mcp serve runs Claude Code as a stdio MCP server and prints nothing on start. In the consuming client, add it the same way as any local stdio server - in Claude Code's own syntax that shape is claude mcp add with a launch command after the double dash.
Share one server list with your whole team
claude mcp add --scope project → .mcp.json → claude mcp reset-project-choices
With project scope the definition is stored in the .mcp.json file in the root of the repository, so the server ships with the checkout. Interactive sessions ask each teammate to approve it before first use, and reset-project-choices clears those answers so Claude Code asks again. claude -p runs load project servers without asking.
Connect a remote server that needs an API key
claude mcp add --transport http <name> <url> --header "Authorization: Bearer ..."
--header (short form -H) is the documented way to pass a static key or token to an HTTP or SSE server. For OAuth servers use claude mcp login instead, with --no-browser on headless machines.
Frequently Asked Questions
How do I add a remote MCP server to Claude Code?
Run claude mcp add --transport http <name> <url> and attach a static key with --header if the server needs one. From v2.1.265 Claude Code falls back to SSE by itself when a server does not accept HTTP. For OAuth servers, sign in with claude mcp login <name> or from /mcp.
What is the difference between local, project, and user scope?
local (the default) is private to you in the current project. project saves the server to .mcp.json in the root of the repository, where the whole team picks it up. user applies across all your projects. When one name is defined in several scopes, local wins over project and project over user.
Why is my MCP tool output being cut off?
Claude Code warns when tool output exceeds 10,000 tokens and truncates it at 25,000 by default. Raise the ceiling with MAX_MCP_OUTPUT_TOKENS; the warning threshold stays fixed, and a text result over 50,000 characters is saved to a file instead.
Where did initialize and ping go in the 2026-07-28 specification?
That revision removed the initialize handshake, ping and logging/setLevel. Every request now carries io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities in its _meta, and a client that wants the server's versions and capabilities up front calls server/discover.
How does a server ask the user for input under the 2026-07-28 revision?
It returns a result of type input_required whose inputRequests hold, for example, an elicitation/create form. The client collects the answers and repeats the original request with inputResponses and the unchanged requestState.
Does Claude Code speak the 2026-07-28 revision?
On its v2 client runtime it asks HTTP, stdio and claude.ai connector servers whether they support 2026-07-28 and uses it with those that do; other servers stay on the earlier handshake. Setting MCP_PROTOCOL_NEGOTIATION to legacy keeps every server on the older protocol.
Sources and checks
- Model Context Protocol specification 2026-07-28: schema.ts (modelcontextprotocol/modelcontextprotocol, tag 2026-07-28) JSON-RPC methods, notifications, multi round-trip fields, _meta keys and error codes
- MCP specification 2026-07-28: Streamable HTTP transport HTTP request headers and the 404 / -32601 rule
- MCP specification 2026-07-28: Key Changes Changes since 2025-11-25 (resource-not-found error code)
- Claude Code Docs: Connect Claude Code to tools via MCP (checked with Claude Code v2.1.296) claude mcp commands, add and login flags, .mcp.json fields, in-session syntax
- Claude Code Docs: Environment variables (v2.1.296) MCP limits, timeouts and protocol negotiation variables
- Claude Code Docs: CLI reference (v2.1.296) claude mcp login / logout, --mcp-config, --strict-mcp-config
Every row on this page was matched to a line in the documentation above on . A command or parameter that could not be found there is not listed.
AI tools change their commands, parameters and model names between releases: the vendor's current documentation and the version you run have the last word. Found a wrong or missing entry? Tell us and it gets checked against the source. How we verify describes the process and its limits.
Related prompt references
Claude Code (157) · OpenClaw (116) · LM Studio (114) · All AI prompt references