# MCP Reference Course: [Model Context Protocol](https://www.devtutorials.ai/learn/mcp) ยท Section: Production Source: https://www.devtutorials.ai/learn/mcp/production/reference > A quick-reference page for MCP 2026-07-28: MCP vs alternatives, roles, methods, error codes, HTTP statuses, headers, result fields, auth and security checklists, deprecations and a glossary. This page is a quick reference for the **2026-07-28** version of the MCP specification. Use it to look up a method, code, header, or checklist while you build. For a step-by-step explanation, use the lesson for that topic. ## MCP and the Alternatives | Approach | What it is | When it fits | | --- | --- | --- | | **MCP** | An open protocol that lets different hosts use the same servers through tools, resources, and prompts | Many apps or models need the same tools and data | | **Model API function calling** | Tools defined in one app's request to one model API | One app needs a few tools, with no need to reuse them elsewhere | | **Plain REST or GraphQL API** | Web APIs called directly by your code | Your code, rather than a model, chooses the calls | | **Plugins tied to one product** | Add-ons that work in only one host | You only target that one host | MCP does not replace function calling. A host still uses its model's function-calling feature under the hood. MCP standardizes **where the tools come from**, so the same server can be used by different hosts. ## Roles and Primitives These roles describe who offers a feature and who uses it. Keeping them straight helps when you look up which side sends a method or owns a capability. | Term | Meaning | | --- | --- | | **Host** | The app the user talks to, such as an IDE or chat app. It runs the model and one or more clients. | | **Client** | The part of the host that talks to one server. A host can run one client for each server it connects to. | | **Server** | A program that offers tools, resources, or prompts. | | **Tool** | An action the **model** can choose to call. | | **Resource** | Data the **app** can read by URI. | | **Prompt** | A reusable template the **user** can choose. | ## Methods The method list shows who sends each request or notification and what it does. This is useful when tracing a message between a client and a server. ```js runnable title="Methods at a glance" // Quick lookup: which side sends each method, and what it is for. const methods = { "server/discover": ["client", "ask for versions, capabilities and server info"], "tools/list": ["client", "list tools"], "tools/call": ["client", "run a tool"], "resources/list": ["client", "list resources"], "resources/templates/list": ["client", "list resource templates"], "resources/read": ["client", "read a resource by URI"], "prompts/list": ["client", "list prompts"], "prompts/get": ["client", "fill in a prompt"], "subscriptions/listen": ["client", "open a stream for change notices"], "notifications/tools/list_changed": ["server", "tools changed"], "notifications/resources/updated": ["server", "one resource changed"], }; for (const [m, [from, what]] of Object.entries(methods)) { console.log(m.padEnd(34), from.padEnd(7), what); } ``` Expected output: ```text server/discover client ask for versions, capabilities and server info tools/list client list tools tools/call client run a tool resources/list client list resources resources/templates/list client list resource templates resources/read client read a resource by URI prompts/list client list prompts prompts/get client fill in a prompt subscriptions/listen client open a stream for change notices notifications/tools/list_changed server tools changed notifications/resources/updated server one resource changed ``` Other client requests you may meet: `resources/subscribe` and `resources/unsubscribe` start and stop updates for one resource; `completion/complete` suggests values for an argument; and `ping` checks whether the connection is responsive. Elicitation uses **multi round-trip requests (MRTR)**: the server returns `input_required` with `inputRequests`, and the client retries with answers in `inputResponses`. ## Error Codes JSON-RPC errors describe problems with the request or protocol. A tool can also run and fail; that is reported separately with `isError: true` in a normal tool result. ```js runnable title="Error codes" // Error codes you will meet, with what to do about each. const codes = { "-32700": "Parse error: the JSON is broken", "-32600": "Invalid request: not a valid JSON-RPC message", "-32601": "Method not found: check capabilities first", "-32602": "Invalid params: unknown tool, missing resource or broken request", "-32603": "Internal error: a bug on the server", "-32020": "Header mismatch: Mcp-Method or Mcp-Name differs from the body", "-32021": "Missing required client capability", "-32022": "Unsupported protocol version", }; const explain = (code) => codes[String(code)] ?? "Not a standard MCP or JSON-RPC code"; for (const c of [-32602, -32022, -32020, 404]) { console.log(String(c).padEnd(7), explain(c)); } ``` Expected output: ```text -32602 Invalid params: unknown tool, missing resource or broken request -32022 Unsupported protocol version -32020 Header mismatch: Mcp-Method or Mcp-Name differs from the body 404 Not a standard MCP or JSON-RPC code ``` Tool failures are not protocol error codes. The server returns a normal tool result with **`isError: true`**, so the client can distinguish a failed action from a broken request. ## HTTP Status Codes HTTP status codes describe the transport-level response. For MCP over HTTP, read the status first, then inspect the JSON-RPC body or authentication headers as needed. ```js runnable title="HTTP status codes" // HTTP status codes from a remote MCP server, and the client's next step. const http = { 200: "OK: read the JSON-RPC result or error", 400: "Bad request: check headers and body", 401: "Sign in: follow resource_metadata in WWW-Authenticate", 403: "Need more scope: step up with the scope in WWW-Authenticate", 404: "Wrong URL", 429: "Too many requests: wait, then retry", 503: "Server busy or down: retry with backoff", }; for (const s of [401, 403, 429, 503]) { console.log(s, http[s]); } ``` Expected output: ```text 401 Sign in: follow resource_metadata in WWW-Authenticate 403 Need more scope: step up with the scope in WWW-Authenticate 429 Too many requests: wait, then retry 503 Server busy or down: retry with backoff ``` ## Headers These headers carry routing information or authentication details alongside the JSON-RPC message. They help an HTTP server or gateway handle a request without guessing what the message means. | Header | Sent by | Purpose | | --- | --- | --- | | `Mcp-Method` | Client | The JSON-RPC method, so gateways can route without reading the body | | `Mcp-Name` | Client | The tool, prompt, or resource name for the request | | `Authorization: Bearer ...` | Client | The access token, on every request, never in the URL | | `WWW-Authenticate` | Server | On 401, points to `resource_metadata`; on 403, can report `scope` and `error` | | `Accept` | Client | `application/json` and `text/event-stream` | If `Mcp-Method` or `Mcp-Name` doesn't match the method or name in the request body, the server answers `-32020` (header mismatch). ## Result Fields These fields help the client interpret a response, page through lists, and decide whether a cached copy is still fresh. | Field | Where | Meaning | | --- | --- | --- | | `content` | Tool results | Content blocks, such as `text`, `image`, `audio`, `resource_link`, or `resource` | | `structuredContent` | Tool results | JSON data that matches the declared `outputSchema` | | `isError` | Tool results | `true` when the tool ran but failed | | `nextCursor` | List results | Opaque value the client sends back to request the next page | | `ttlMs` | List results, `resources/read` | How long the result stays fresh, in milliseconds | | `cacheScope` | List results, `resources/read` | `"private"` or `"public"`, describing who may share a cached copy | | `_meta` | Many messages | Extra metadata, such as trace context | ## Authorization Checklist Use this checklist when a remote server asks for a token: 1. Call the server and read the **401** `WWW-Authenticate` header. 2. Fetch **protected resource metadata**. Choose an entry from `authorization_servers`. 3. Fetch **authorization server metadata**. Check that its `issuer` matches the issuer you requested. 4. Register the client: use a **pre-registered** client or a **Client ID Metadata Document**. Use Dynamic Client Registration only with older authorization servers that still support it. 5. Sign in with **PKCE (S256)**, the **`resource`** parameter, and minimal **scopes**. Check **`iss`** on the redirect. 6. Send **`Authorization: Bearer`** on every request. On **403** `insufficient_scope`, request the additional permission through step-up authorization. ## Security Checklist These checks help keep untrusted content, credentials, and network access within the intended boundaries. The host, client, server, and deployment each have responsibilities here; MCP does not enforce every item by itself. - Treat tool descriptions, resources, and results as **untrusted data**. - Use narrow tools, **least privilege**, **sandboxing**, and **human approval** for risky actions. - Match redirect URIs exactly, get consent for each client, and use single-use `state` values. - **No token passthrough.** Check that each token's audience is this server. - Block **SSRF**: allow only intended HTTPS destinations, reject private addresses, and use an egress proxy where appropriate. - Use random state handles and bind them to the user or session. - Show the **full command** before running a local server. Open only **http(s)** URLs. ## Deprecated in 2026-07-28 A deprecated feature still works for at least **12 months**, but new implementations should use the recommended alternative. | Feature | Use instead | | --- | --- | | HTTP+SSE transport | Streamable HTTP | | Roots | Tool arguments and server-side path checks | | Sampling | The host's own model, or your own model API | | Logging (`notifications/message` by default) | stderr and OpenTelemetry | | `includeContext` values `thisServer` and `allServers` | Pass context in arguments | | Dynamic Client Registration | Client ID Metadata Documents or pre-registration | ## Glossary | Word | Meaning | | --- | --- | | **Capability** | A feature a side says it supports, such as `tools` or `extensions` | | **Extension** | An optional feature with an identifier like `io.modelcontextprotocol/tasks` | | **JSON-RPC** | The message format MCP uses: `method`, `params`, `id`, `result`, and `error` | | **stdio** | A transport where the host runs the server and communicates through standard input and output | | **Streamable HTTP** | The transport for remote servers: one POST per request, with optional streams | | **MRTR** | Multi round-trip request: the server asks for input, and the client retries with answers | | **PKCE** | A sign-in safety step: the client keeps a secret verifier and sends its hash | | **Audience** | The resource a token was issued for. For an MCP request, it must match this server. | | **Scope** | A named permission inside a token, such as `orders:read` | | **SSRF** | Tricking a server into fetching an internal address | | **Tool poisoning** | Hidden instructions inside a tool description | | **TTL** | Time to live: how long a cached copy stays fresh | ## Common mistakes - **Mixing up tools, resources and prompts.** The model chooses tools, the app reads resources, and the user selects prompts. - **Reading cursors.** Pass `nextCursor` back as is. - **Forgetting `isError`.** A failed tool still returns a result, not a protocol error. ## Where to Go Next - The official specification at **modelcontextprotocol.io**, version 2026-07-28. - The **TypeScript** and **Python** SDK documentation. - Start with the **MCP Inspector** when debugging a server. - Use the **MCP Registry** to find existing servers or publish one.