MCP — Model Context Protocol

The open standard for connecting an AI assistant to an external system. Released by Anthropic in November 2024 and moved to neutral governance under the Linux Foundation in December 2025; OpenAI, Google and Microsoft have all adopted it. A server implements the protocol once and any conforming client can use it, which is the whole point — one endpoint instead of one integration per vendor.

In commerce it is the layer that lets an assistant read a live catalogue rather than a feed. See MCP for Magento.

Tool

A named, callable function a server exposes, with a JSON Schema describing its arguments. search_products and place_order are tools. The model decides which to call and with what arguments; the server decides what a call is permitted to do.

Tool annotations

Declarative hints on a tool: readOnlyHint, destructiveHint, idempotentHint, openWorldHint, and a human-readable title. Clients use them to group tools by risk and decide which need explicit approval — a catalogue search runs freely while an order placement stops and asks.

They do not influence which tool a model picks. They shape the permission UI, not the selection.

Prompts MCP capability

Server-supplied conversation starters a client can offer the user — ready-made requests with the store’s own name already in the text. Distinct from tools in two ways: a prompt is chosen by the user, not the model, and it inserts a message rather than performing an action. No MCP server can begin a conversation turn on its own.

Instructions

A free-text field in the initialize response describing what the server is and when to use it. The first thing a client reads about a connector, before any tool name or description — which makes it the highest-leverage string in the whole integration, and the easiest one to leave stale.

Capabilities

What a server declares it supports in its initialize response: tools, prompts, resources. A client that sees no tools capability concludes there are none and never asks for the list — which surfaces as an empty connector with no error anywhere.

JSON-RPC 2.0

The message format MCP rides on. A request carries method, params and an id; a notification carries no id and expects no result. Batching — several messages in one array — was removed from MCP in the 2025-06-18 revision.

Notification

A JSON-RPC message with no id, sent when no answer is expected. notifications/initialized is part of every handshake. The correct response is HTTP 202 with an empty body — which naive validation frequently mistakes for a failure.

Streamable HTTP

The current MCP transport. A client POSTs JSON-RPC to a single endpoint; the server answers with JSON or, when it chooses, an SSE stream. Replaced the older HTTP+SSE two-endpoint transport.

Mcp-Session-Id

An opaque identifier the server issues on initialize and expects on every later request. Lose it in either direction and each call looks like a fresh, uninitialised session — the client restarts the handshake and never reaches tools/list.

Browser clients also need it in Access-Control-Expose-Headers, or the header arrives and JavaScript is forbidden from reading it.

Mcp-Method and Mcp-Name 2026-07-28

Transport headers carrying the JSON-RPC method and, for a tool call, the tool name — so a gateway can route and meter without parsing the body. Required as of the 2026-07-28 revision, and servers are expected to reject requests where the headers and the body disagree.

MCP-Protocol-Version

The revision a client speaks. Negotiated during initialize: a server that supports the requested version echoes it, otherwise it answers with its own and the client decides whether to proceed. Negotiating down works; assuming a version does not.

OAuth 2.1

The consolidation of OAuth 2.0 and its security best practices into one specification — still an Internet-Draft as of 2026, and the authorization model MCP builds on. The practical differences from OAuth 2.0: PKCE is mandatory, redirect URIs match exactly rather than by prefix, the implicit and password grants are gone, and refresh tokens are rotated.

PKCE — Proof Key for Code Exchange

A client generates a random verifier, sends its SHA-256 hash with the authorization request, and presents the verifier when redeeming the code. An intercepted code is then useless without it. S256 only — the plain method is not acceptable.

Resource indicators RFC 8707

The client names which resource a token is for, via a resource parameter; the token comes back with that value in its aud claim, and the resource server accepts only tokens minted for itself. This is what stops a token issued for one store being replayed against another. An unrecognised value must return invalid_target, not a quiet fallback.

Issuer identification RFC 9207

The authorization server returns an iss parameter with the authorization response, and the client validates it before redeeming the code. Closes the mix-up attack, in which a client is tricked into sending its code — and its PKCE verifier — to an attacker’s token endpoint. Required by MCP as of 2026-07-28; PKCE alone does not cover it.

Dynamic Client Registration RFC 7591

A client registers itself with an authorization server at runtime and receives a client_id, with no human onboarding step. Formally deprecated in MCP 2026-07-28 in favour of CIMD, and retained for compatibility.

CIMD — Client ID Metadata Document

The successor to DCR: the client’s client_id is a URL, and the authorization server fetches its metadata from there rather than storing a registration. Removes the open registration endpoint, which is a meaningful reduction in attack surface.

Confused deputy

A server that holds more authority than its caller and can be induced to use it on the caller’s behalf. In an MCP proxy the concrete form is forwarding the shopper’s token upstream: the upstream can no longer tell whose authority it is acting on. The specification forbids token pass-through for exactly this reason — the proxy validates the client’s token and calls the upstream with a separate credential of its own.

JWKS — JSON Web Key Set

The public keys a resource server uses to verify token signatures, published at a well-known URL. Each key carries a kid and a declared algorithm; binding the key to its algorithm is what defeats alg:none and RS256-to-HS256 downgrade attempts. Publishing several keys at once is what makes rotation possible without invalidating every live token.

Protected Resource Metadata RFC 9728

Served at /.well-known/oauth-protected-resource, optionally with a path suffix for a specific resource. Tells a client which authorization server to use, what scopes exist, and — critically — carries a resource field that must identify the URI the client actually asked about. A mismatch there stops the flow during discovery, before any request reaches your application, which is why the server logs stay empty.

Authorization Server Metadata RFC 8414

Served at /.well-known/oauth-authorization-server. Lists the authorization, token, registration and revocation endpoints, the JWKS URI and the supported methods. Its issuer must equal the URL used for discovery byte for byte, trailing slash included — the single most common reason a strict client walks away before showing a consent screen.

Well-known URI

A reserved path prefix, /.well-known/, where machine-readable metadata lives by convention. In commerce you will also meet /.well-known/ucp for a UCP merchant profile.

Integration token

Magento’s long-lived API credential, created under System → Integrations. Correct for your own tooling and for a proxy calling the store; wrong as the only thing between the public and a checkout endpoint, because it carries no per-shopper identity, has no consent step, and cannot be revoked individually.

Guest cart and masked ID

A cart with no customer account, addressed by an unguessable masked identifier. The deliberate choice for agent checkout: no stored credentials exist for a compromised session to reach, so the blast radius of one is a single cart.

Store view scope

Magento’s per-locale, per-market scope. It matters here because tool descriptions, generated instructions and the store name an agent matches against are all resolved per store view — a multi-language catalogue can present a different, correctly localised connector on each.

Optional constructor arguments in di.xml

Magento does not auto-wire an optional constructor argument: a nullable parameter with a default receives that default unless it is named explicitly in di.xml. Worth knowing because the failure is silent — the feature falls back to its previous behaviour and nothing reports it.

MCP vs ACP vs UCP

Different layers, not competitors. MCP is how any assistant calls a tool — vendor-neutral, general-purpose. ACP is OpenAI’s feed and discovery standard for ChatGPT Shopping. UCP is Google’s discovery and checkout standard for its own surfaces. A store can implement all three; they compose.

Sequencing argument: ACP vs UCP for Magento 2.

Discovery vs transactability

Two separate problems with two separate solutions. Crawler access, structured data and llms.txt decide whether an assistant knows you exist. An MCP connector decides whether it can act once it does. Neither substitutes for the other, and an MCP endpoint is not a discovery channel — nobody finds you through it.

Feed vs live connection

A feed is a periodic export read from someone else’s copy; freshness is bounded by the refresh interval. An MCP call reads the store at the moment the question is asked. A feed is how you get into a shopping result; a live connection is how the conversation stays accurate once it starts.

Tool selection

The model’s decision about which capability to use, made before anything is called, from the instructions, tool names and descriptions. Not controllable by a server beyond making those three accurate. Requests about a specific store reach a connector reliably; a cold shopping request that names no shop competes with the client’s own product search and often loses — reasonably, since one store should not win a question about the whole market.