> Every term you meet when building an MCP connector for Magento: JSON-RPC, Streamable HTTP, PKCE, RFC 8707, tool annotations, and what each breaks. Source: https://angeo.dev/docs/mcp-glossary/ Updated: 2026-10-17 # MCP & Agentic Commerce Glossary for Magento Last updated 23 September 2026 - Terms checked against MCP 2026-07-28 (stateless) and OAuth 2.1 draft-15. Terms that only exist in older revisions are marked *legacy*. The vocabulary you actually meet while building or debugging an MCP connector for a Magento store - protocol mechanics, the OAuth layer underneath it, and the handful of terms whose precise meaning decides whether a connector works. **What this page is not.** It does not define the strategic terms - AEO, AI Commerce Visibility, the agentic commerce protocols as a category. Those have their own canonical pages: [Magento AEO](https://angeo.dev/magento-aeo-definition/), [AI Commerce Visibility](https://angeo.dev/ai-commerce-visibility-definition/), [ACP & UCP](https://angeo.dev/agentic-commerce-protocol-definition/), [AI Commerce Stack](https://angeo.dev/ai-commerce-stack-definition/). This one is the implementation vocabulary that sits beneath them. **Sections** - Protocol - Transport and session - Authorization - Discovery documents - Magento-specific - Commonly confused ## Protocol ### 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](https://angeo.dev/magento-mcp-server/). ### 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. ### `server/discover` 2026-07-28 The request a client can send to learn what a server supports - its protocol versions, capabilities and instructions - without a handshake. Every 2026-07-28 server must implement it; clients may call it before anything else. MCP 2026-07-28 made the protocol stateless and removed the `initialize` / `initialized` handshake; a dual-era server can still serve older clients. ### Instructions A free-text field describing what the server is and when to use it: part of the `server/discover` result in 2026-07-28, and of the `initialize` response in older revisions. 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 the `server/discover` result (2026-07-28) or the `initialize` response (older revisions): `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 the legacy handshake (revisions before 2026-07-28). The correct response is HTTP 202 with an empty body - which naive validation frequently mistakes for a failure. ## Transport and session ### 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` legacy Before 2026-07-28: an opaque identifier the server issued on `initialize` and expected on every later request. The 2026-07-28 revision removed protocol-level sessions; servers that still serve older clients may keep issuing it. 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. ## Authorization ### 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. ## Discovery documents ### 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](https://angeo.dev/modules/ucp/). ## Magento-specific ### 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. ## Commonly confused ### 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](https://angeo.dev/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. **Related** - [MCP modules for Magento 2](https://angeo.dev/docs/mcp/) - configuration reference and the tool SPI - [MCP Checkout for Magento 2](https://angeo.dev/docs/mcp-checkout/) - connecting an assistant, prompts, safety model - [Agentic Commerce Protocol (ACP & UCP)](https://angeo.dev/agentic-commerce-protocol-definition/) - [AI Commerce Stack](https://angeo.dev/ai-commerce-stack-definition/) - the strategic layer above this vocabulary - [AI crawlers for Magento 2](https://angeo.dev/docs/ai-crawlers/) - the discovery vocabulary, defined the same way ## More on this topic - [AI Agent Checkout in Magento 2 via MCP | Claude Demo | Angeo](https://angeo.dev/ai-agent-checkout-in-magento-2-claude-places-a-real-order-via-mcp/) - [Magento 2 MCP Server Module - Free](https://angeo.dev/modules/mcp-server/) - [MCP Checkout Tools for Magento 2](https://angeo.dev/modules/mcp-checkout/) - [Magento Agentic Commerce Hub 2026: ACP - UCP - AP2](https://angeo.dev/magento-agentic-commerce-hub/) - [Agentic Commerce for Magento: 12 Merchant Questions Answered](https://angeo.dev/agentic-commerce-magento-questions/) - [Claude Commerce Agents on Magento 2](https://angeo.dev/claude-commerce-agents-magento/) - [MCP account linking - definition](https://angeo.dev/mcp-account-linking-definition/) - [WebMCP - definition](https://angeo.dev/webmcp-definition/) ## Sources - [MCP specification 2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28) - [OAuth 2.1 (IETF draft)](https://datatracker.ietf.org/doc/draft-ietf-oauth-v2-1/) - [RFC 8707: Resource Indicators](https://www.rfc-editor.org/rfc/rfc8707.html) - [RFC 9728: OAuth Protected Resource Metadata](https://www.rfc-editor.org/rfc/rfc9728.html) - [RFC 8414: OAuth Authorization Server Metadata](https://www.rfc-editor.org/rfc/rfc8414.html) Links checked 23 September 2026.