Build an MCP Assistant outside Vendure | Vendure | Vendure Docs

Assistant outside Vendure

An assistant that runs outside the Vendure process must obtain an OAuth token before it can act for a signed-in shopper. For a first-party assistant, you can handle the OAuth flow without showing a consent screen to the shopper. Start the flow during a navigation the shopper is already making, and your consent page can automatically approve your own client.

When this is the right shape

Use this approach when the assistant runs as a separate service from Vendure.

Use a different approach when:

The assistant is a Vendure plugin in the same process. It can run the tools directly, with no token at all: see Assistant inside Vendure.
The AI client belongs to the shopper, such as Claude Desktop, ChatGPT, or Cursor. Those clients run this flow themselves. All you build is the customer consent page.

Before you start

Every authorization for the shop toolset redirects the browser to your oauth.storefrontConsentUrl. Even a first-party assistant must go through the storefront OAuth flow. That redirect is where the invisibility comes from: your consent page recognises your own client_id, approves without drawing a screen, and redirects onward. Build that page first: the customer consent page.

To integrate your assistant, you will:

Register it once and store its client id.
Start the authorization by redirecting the shopper's browser.
Handle the callback and exchange the code for tokens.
Hold the tokens for the conversation.
Renew silently and call tools.

Text

Your assistant                     Vendure                        Your consent page     │     │ 1. Register once ──────────────▶ client_id     │     │ 2. Redirect shopper ───────────▶ /mcp/oauth/authorize     │                                        │     │                                        └─ redirect ──────────▶ ?request_token=…     │                                                                     │     │                                                           approve your client     │                                                                     │     │ 3. Browser returns with ?code=…&state=… ◀──────────────────────────────┘     │     │ 4. Exchange code ──────────────▶ /mcp/oauth/token     │                                  ◀── access_token + refresh_token     │     │ 5. Call MCP tools ─────────────▶ /mcp/shop

Was this chapter helpful?

Report Issue

Edited Oct 1, 2026·View source

src/mcp/oauth-client.ts

const VENDURE_URL = 'https://my-store.example.com';const RESOURCE = `${VENDURE_URL}/mcp/shop`;const REDIRECT_URI = 'https://assistant.example.com/mcp/callback';/** * Returns this assistant's client id, registering it the first time only. `db` here is your * own storage, not Vendure's. */export async function getClientId(): Promise<string> {    const stored = await db.getSetting('mcpClientId');    if (stored) {        return stored;    }    const response = await fetch(`${VENDURE_URL}/mcp/oauth/register`, {        method: 'POST',        headers: { 'content-type': 'application/json' },        body: JSON.stringify({            client_name: 'Acme Assistant',            client_uri: 'https://assistant.example.com',            // The address used in step 3 must appear here, or the authorize step refuses it.            redirect_uris: [REDIRECT_URI],        }),    });    if (!response.ok) {        throw new Error(`MCP client registration failed: ${response.status}`);    }    const { client_id } = (await response.json()) as { client_id: string };    await db.setSetting('mcpClientId', client_id);    return client_id;}

Value	Where it goes	What it is for
Code verifier	Stays on your server, then goes to the token endpoint	Proves that the service redeeming the code is the one that started the flow. Never send it to the browser.
Code challenge	Travels in the browser, on the authorize URL	A one-way hash of the verifier. Anyone who steals it learns nothing, because they cannot work backwards to the verifier.
State	Travels in the browser, and comes back on the callback	Ties the callback to a flow this server started, and to the customer who started it.

src/mcp/oauth-client.ts

import { createHash, randomBytes } from 'crypto';interface PendingFlow {    /** The secret half of the pair. Never leaves your server. */    codeVerifier: string;    /** Who started this flow. The callback needs it to know whose tokens these are. */    customerId: string;    conversationId: string;}// Keyed by state. Use shared storage if more than one instance can handle the callback.const pendingFlows = new Map<string, PendingFlow>();/** Returns the URL to send the shopper's browser to. */export async function startAuthorization(    customerId: string,    conversationId: string,): Promise<string> {    const codeVerifier = randomBytes(32).toString('base64url');    const codeChallenge = createHash('sha256').update(codeVerifier).digest('base64url');    const state = randomBytes(16).toString('base64url');    pendingFlows.set(state, { codeVerifier, customerId, conversationId });    const url = new URL('/mcp/oauth/authorize', VENDURE_URL);    url.searchParams.set('response_type', 'code');    url.searchParams.set('client_id', await getClientId());    url.searchParams.set('redirect_uri', REDIRECT_URI);    url.searchParams.set('code_challenge', codeChallenge);    url.searchParams.set('code_challenge_method', 'S256');    // Names the toolset the token will be good for. `/mcp/shop` is the customer-facing one.    url.searchParams.set('resource', RESOURCE);    url.searchParams.set('state', state);    return url.toString();}

src/mcp/oauth-client.ts

/** Handles the browser's return from the consent page. */export async function handleCallback(query: Record<string, string | undefined>): Promise<void> {    const { code, state, error } = query;    // Check the state before anything else, every time.    if (!state) {        throw new Error('Unrecognised MCP callback — no state');    }    const flow = pendingFlows.get(state);    if (!flow) {        throw new Error('Unrecognised MCP callback — no matching flow');    }    // Each state is good for one callback only.    pendingFlows.delete(state);    if (error || !code) {        // The shopper denied, or the server refused. There is nothing to store.        return;    }    const tokens = await requestTokens({        grant_type: 'authorization_code',        code,        client_id: await getClientId(),        redirect_uri: REDIRECT_URI,        code_verifier: flow.codeVerifier,        resource: RESOURCE,    });    conversations.set(flow.conversationId, tokens);}

src/mcp/oauth-client.ts

/** Replace the access token this long before it expires. */const RENEW_WITHIN_MS = 60_000;interface Tokens {    accessToken: string;    refreshToken: string;    /** Clock time at which the access token stops working. */    expiresAt: number;    /** Set while a renewal is in flight, so two messages cannot renew at once. */    renewal?: Promise<Tokens>;}const conversations = new Map<string, Tokens>();async function requestTokens(body: Record<string, string>): Promise<Tokens> {    const response = await fetch(`${VENDURE_URL}/mcp/oauth/token`, {        method: 'POST',        headers: { 'content-type': 'application/json' },        body: JSON.stringify(body),    });    if (!response.ok) {        throw new Error(`MCP token request failed: ${response.status}`);    }    const payload = (await response.json()) as {        access_token: string;        refresh_token: string;        expires_in: number;    };    return {        accessToken: payload.access_token,        refreshToken: payload.refresh_token,        expiresAt: Date.now() + payload.expires_in * 1000,    };}

src/mcp/oauth-client.ts

/** Returns a usable access token, renewing first if the current one is nearly up. */export async function accessTokenFor(conversationId: string): Promise<string> {    const tokens = conversations.get(conversationId);    if (!tokens) {        throw new Error('This conversation has no MCP grant yet');    }    if (tokens.expiresAt - Date.now() > RENEW_WITHIN_MS) {        return tokens.accessToken;    }    // One renewal at a time: a simultaneous second renewal can revoke the whole grant    // (see "How refresh-token rotation works" below). Share one promise so there is    // only ever one call in flight.    const renewal = (tokens.renewal ??= renew(conversationId, tokens).finally(() => {        delete tokens.renewal;    }));    return (await renewal).accessToken;}async function renew(conversationId: string, current: Tokens): Promise<Tokens> {    const fresh = await requestTokens({        grant_type: 'refresh_token',        refresh_token: current.refreshToken,        client_id: await getClientId(),        resource: RESOURCE,    });    conversations.set(conversationId, fresh);    return fresh;}

import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';const transport = new StreamableHTTPClientTransport(new URL(`${VENDURE_URL}/mcp/shop`), {    requestInit: {        headers: { authorization: `Bearer ${await accessTokenFor(conversationId)}` },    },});const client = new Client({ name: 'acme-assistant', version: '1.0.0' });await client.connect(transport);

What you see	Cause	Fix
The authorize call returns a 400 saying the redirect is not registered	The `redirect_uri` on the authorize URL is not among the `redirect_uris` the client was registered with. The comparison is an exact string match	Send a `redirect_uri` that exactly matches a registered one
The callback carries a `state` with no matching flow	The flow was not started by this server, or the state was already used	Treat it as an error and store nothing
Callbacks intermittently find no matching flow after you scale past one instance	Pending flows are stored in one instance's memory	Store pending flows in shared storage
The callback carries `error`, or no `code`	The shopper denied (`access_denied`), or the server refused (`invalid_request`, `server_error`)	There is nothing to store; start a fresh flow on a later navigation
The token endpoint rejects a refresh	The grant was revoked (by an administrator, your own code, or automatically after a refresh-token replay), or it expired 30 days after the last refresh	Treat the grant as dead: ask this shopper to authorize again next time they visit
A protocol error with `data.retryAfterSeconds`	A rate limit refused the call before a tool ran	Wait the given seconds, and tell the shopper to try again in a moment

Assistant outside Vendure

When this is the right shape

Before you start

Assistant outside Vendure

When this is the right shape

Before you start

Register once, and store the client id

Start the authorization

Handle the callback

Hold the tokens for the conversation

Renew silently and call tools

Optional: Act for a shopper who is not present

Security and production considerations

Why the state check matters

How refresh-token rotation works

Handling a rate-limit refusal

Troubleshooting

See also