The MCP plugin exposes your Vendure store to AI agents over the Model Context Protocol (MCP). Agents such as Claude, Cursor and ChatGPT use that open standard to discover and call tools on a server.
The plugin ships built-in shop tools for the catalog, the cart and checkout. It also ships admin tools for
products, orders, customers and stock. Any Vendure plugin can add its own with the
@McpTool decorator.
The plugin serves MCP over Streamable HTTP at two paths. Every MCP request is a POST.
| Endpoint | Authentication | Tools |
|---|---|---|
POST /mcp/shop | Anonymous by default, or a customer Bearer token | Browse the catalog, manage a cart, place an order |
POST /mcp/admin | Administrator Bearer token, always required | Manage products, orders, customers, stock |
The shop endpoint needs no OAuth configuration, which makes it the quickest way to try the server. The admin endpoint and authenticated customer access both need OAuth. An MCP client discovers where that flow starts from the server's own response, described in the OAuth Protocol Reference.
To get a server running and confirm it works:
The plugin requires Vendure 3.8.0 or later. On an older version the server refuses to boot with a compatibility error.
Add the plugin to your Vendure config. It needs no configuration to start:
That serves the anonymous shop endpoint. shopAccess controls who may call it: anonymous (default),
or . See
. Configure OAuth
later, when you need the admin endpoint or authenticated customer access. documents every
option.
authenticateddisabledMcpPlugin registers five entities, whether or not you configure OAuth:
McpOauthClientMcpAuthorizationCodeMcpAuthorizationRequestMcpOauthGrantMcpToolCallLogIf you run with synchronize: false (the recommended production setting), generate and run a migration so these
tables are created. See Migrations for the workflow.
Start your Vendure server. Then start the MCP Inspector, a browser-based tool for exploring an MCP server, without installing it globally:
Point it at http://localhost:3000/mcp/shop to browse and call shop tools anonymously. Point it at /mcp/admin
with a Bearer token for the admin tools.
The Inspector lists the live tool set, shows each tool's input schema, and runs calls so you can read the results. Seeing the shop tools listed confirms the server works, before any AI client is involved.
MCP clients that support remote Streamable HTTP servers connect by URL. To try the server without configuring OAuth, point the client at the shop endpoint:
The client now reaches the anonymous shop tools. For the admin endpoint or authenticated customer access, configure OAuth and point the client at that endpoint. The client runs the OAuth flow for you.
The dashboard has an MCP Server section in its navigation with four pages: Overview, Tools, Grants and Activity. The Connect a client button on the Overview page shows copyable connection snippets for both endpoints. OAuth & Consent covers how admin sign-in works through the dashboard.
Configure OAuth when you need the admin endpoint or authenticated customer access. Without it, every call that
needs a token fails with 400 MCP OAuth is not configured.
tokenSecret (string, required) — The secret the server uses to hash OAuth tokens before storing them. Keep it
in an environment variable.issuer (string, default: http://localhost:<your API port>) — The public base URL of this server. The default
suits local development only. With NODE_ENV=production the plugin refuses to start if the issuer is a
loopback URL.storefrontConsentUrl (string, optional) — The storefront page that approves customer consent. Required only if
customers will authorize MCP clients. Must be an HTTPS URL in production.McpOauthOptions documents every field and its default.
By default (toolExposure: 'direct') the server lists every tool the caller is permitted to use and that an
operator has not switched off. This suits almost all deployments, because modern agents and hosts run their own
tool search.
If your host has a low tool cap, or your model has no built-in tool search, set toolExposure: 'discovery'. That
replaces the full list with two meta-tools, search_tools and execute_tool.
Built-in Tool Reference explains when to
reach for it.
| What you see | Cause | Fix |
|---|---|---|
400 MCP OAuth is not configured | The call needs a token, and the config has no oauth block | Configure OAuth, or call the shop endpoint anonymously |
405 Method Not Allowed with an Allow: POST header | The request was a GET. Every MCP request here is a POST | Send a POST. MCP client libraries do this for you |
| The MCP tables are missing after adding the plugin | The server runs with synchronize: false and no migration was generated | Generate and run a migration for the five entities |
@McpTool tools.Architecture reviews, custom plugin work, migrations, ongoing support. Get a hand from the team that builds Vendure.
Talk to the team