Skip to content

MCP Service Rollout

  • Creating a new MCP service under backend/
  • Reusing an existing local backend/mcp-* service as the baseline for another MCP server
  • Bootstrapping the first MCP service in a repo that does not have any local mcp-* service yet
  • Defining which GraphQL operations should be exposed as MCP tools
  • Connecting customers to a service through OAuth and the storefront’s login page

Use these as the minimum references before making changes:

  • backend/graphql-gateway/supergraph.generated.graphql in the current repo, when available
  • the closest local backend/mcp-* service in the current repo, when available
  • otherwise, backend/mcp-customer in https://github.com/evolve-platform/evolve-reference-b2b, as a read-only scaffold source
  • the README of @evolve-framework/mcp-core and of @evolve-storefront/feature-mcp-connect
  • Expose your API to AI assistants

If the current repo contains multiple mcp-* services, prefer the one whose authentication setup is closest to the new service you are creating.

Collect or confirm these inputs up front:

  • service folder name: mcp-<name>
  • package name: @evolve-platform/mcp-<name>
  • server name: evolve-mcp-<name>
  • HTTP port: a port no other service uses
  • purpose of the service and intended MCP client or user
  • whether customers sign in through OAuth, or whether every call is a guest
  • whether the shop has business units
  • which GraphQL queries and mutations must be exposed as tools

Before asking questions, inspect:

  • backend/graphql-gateway/supergraph.generated.graphql for available query and mutation fields
  • backend/ for any existing mcp-* service that can act as the closest scaffold

Before writing operations.graphql, ask the user exactly which GraphQL queries and mutations they want exposed.

Ask for:

  • operation names or business actions
  • whether each one is a query or mutation
  • the key variables each operation needs
  • whether any operation depends on a previous lookup step
  • which scope each one needs, and whether a guest may use it

Translate business actions into likely GraphQL operations from the supergraph, and present them back to the user for confirmation before implementing operations.graphql.

If supergraph.generated.graphql is missing in the current repo, find the actual gateway schema source used by that repo and use it instead of guessing.

An MCP rollout is complete only when the new service and every required change outside it have been applied and validated: root scripts, the storefront, and deployment. Do not stop at changes inside backend/mcp-<name>.

Search the current repo first for a service under backend/ whose folder name starts with mcp-.

  • prefer a local mcp-* service as the scaffold when one exists
  • if multiple exist, choose the closest match for authentication
  • if none exist, use backend/mcp-customer from the B2B reference site as a read-only source
  • if the repo already has an mcp-* service, follow that local pattern instead of redoing the bootstrap work

Duplicate the baseline and rename it to backend/mcp-<name>. A service follows the layout of every Evolve service:

backend/mcp-<name>/
├── operations.graphql the tools
├── codegen.ts step 1: persisted documents
├── codegen.tools.ts step 2: tool definitions
├── run.ts local entry: observability, then the CLI
└── src/
├── cli.ts the CLI's entry point
├── commands.ts serve and stdio
├── config.ts extends MCPCoreConfig
├── module.ts the service, and createMcpModule
└── server.ts createApp, startServer and startStdio

Keep module.ts and server.ts in the service: they are how it composes itself, and where it adds modules or startup hooks. MCP behavior belongs in @evolve-framework/mcp-core, not here. Do not add a create-server.ts or copy OAuth or session code into the service.

Keep turbo.json, tsconfig.json and vitest.config.ts as they are. turbo.json keeps the codegen dependency on @evolve-platform/graphql-gateway#codegen.

  • package.json: set name to @evolve-platform/mcp-<name>, and keep the scripts codegen, dev, dev:stdio, start, test and tsc
  • README.md: update the overview, the port and the examples
  • src/config.ts: set COMPONENT_NAME, HTTP_PORT, MCP_PUBLIC_URL, and the MCP_<NAME>_ prefix in loadConfig
  • src/module.ts: set the server’s name to evolve-mcp-<name>, and the resourceName under oauth
  • src/cli.ts: set packageName
  • tests: update the names they expect

Rename every scaffold string. A service left with another’s name reports under that name in traces and logs.

Create a backend/mcp-<name>/operations.graphql with only the operations the user confirmed. Use the scaffold as an example of format, not as the source of which operations belong here. Do not ship a generic file.

Rules:

  • every exposed operation has @mcpTool(description: "...")
  • every important variable has @mcpToolVariable(description: "...")
  • scopes on @mcpTool names the scopes that permit the tool, and any one of them is enough. The server offers the scopes its tools name, so there is no list to keep elsewhere
  • tools/list shows a client only the tools its token’s scopes permit, so a scope the customer withholds removes its tools from the assistant
  • an operation the service runs itself has exclude: true, so it is registered without becoming a tool

Group the tools into a few scopes the customer can judge on the consent screen, and give each tool the one scope whose consent text covers it:

  • leave a tool without a scope only when it returns public data, such as the catalog, content or an address lookup. A tool without a scope is open to every token, a guest’s included
  • keep reading the account apart from committing money: placing, paying and cancelling orders belong in a scope of their own
  • put every tool a step needs in the same scope. A cart scope that holds renaming a cart but not adding a line does not stop the agent filling the cart
  • name a second scope only when two groups genuinely need one tool, such as reading a company’s addresses for both the account and checkout

Keep these operations, each with exclude: true:

Operation Why
CreateGuestSession Guest sessions
RefreshToken Renewing a session
CustomerLogout Ending a session when a client is revoked, with OAuth
BusinessUnitSwitch Gives the service business units. Leave it out of a shop without them

With business units:

  • put businessUnit: REQUIRED on a tool that must name the company, such as placing an order. Without BusinessUnitSwitch, this fails when the server is built
  • put businessUnit: NONE on a tool that does not depend on a company, such as the one that lists companies
  • an operation with its own $businessUnitId variable keeps it

Write the descriptions for an agent that knows nothing about the shop:

  • explain what the tool is for
  • mention the most important variables and when they are required
  • say where a value comes from, instead of only that it is required
  • name the tool to call first when an input depends on another call

For example, cartLineItemsAdd creates a new cart when it gets no id, so its description has to say to call get_cart first and pass the id.

Select what the agent needs to take the next step. A tool that sets a value needs another tool that lists the options, and a reorder needs the SKUs on an order’s lines.

codegen.ts:

  • always include ./operations.graphql
  • keep the schema inputs aligned with ../graphql-gateway/supergraph.generated.graphql and ./node_modules/@evolve-framework/mcp-core/directives.graphql

Keep codegen.tools.ts aligned with the scaffold, so tools still come from ./generated/persisted-documents.json into ./generated/mcp-tools.generated.ts.

Skip this when every call is a guest, or when a chat backend forwards the shopper’s session.

Service settings: MCP_OAUTH_SECRETS, MCP_INTERACTION_SECRET, MCP_PUBLIC_URL and MCP_LOGIN_URL. OAuth stays off without oauth in createMcpModule or without MCP_OAUTH_SECRETS.

Storefront, using @evolve-storefront/feature-mcp-connect:

  • add the package to package.json, transpilePackages in next.config.ts, and the styles to global.css
  • add MCP_URL and MCP_INTERACTION_SECRET to the server config. Never give the storefront MCP_OAUTH_SECRETS
  • create the flow with createConnectFlow, and pass it CustomerLogin from @evolve-storefront/feature-auth/documents and SessionGuestCreate from @evolve-storefront/session/documents
  • run connectTicketStep from @evolve-storefront/feature-mcp-connect/proxy first in the site’s proxy, so the mcp_request ticket moves into an HttpOnly cookie before any page or script loads
  • make the login page spread useConnectForm onto LoginFormView from feature-auth when it carries connect, and never pass the ticket to a page, prop or form
  • for a customer already signed in on the site, show ConnectConfirmForm, which asks for the password alone, with a way to use another account
  • add an /account/connect page with ConnectConsent and ConnectExpired, and its path to the site’s routing
  • in the consent action, pass the ticked scopes to answer as scopes: formData.getAll("scope").map(String). Each scope is a checkbox; without scopes the client gets every scope, whatever the customer unticked
  • set guestScopes to what a guest may get, usually only the cart scope
  • describe each scope for the customer, in every locale. State what it lets a client change, not only what it lets it see
  • with business units, add a selection that loads them and applies businessUnitSwitch, named businessUnitId, so the company survives a token refresh

A shop that signs people in another way, such as single sign-on, leaves login and guest out and passes a gateway session to handOver.

  • add a root pnpm dev:mcp when the repo has none, or add the service to the existing one
  • keep MCP services out of pnpm dev:backend
  • add the service to the backend table in AGENTS.md
  • register generated/persisted-documents.json with Hive before the version rolls out, as the storefront does, because the deployed gateway accepts nothing else
  • set COMPONENT_VERSION to the version you registered
  • add the service to .github/artifacts.yaml, the deploy configs and the release workflow
  • inspect the other backend services and match their Terraform: cloud, modules, naming and deployment. Do not copy infrastructure from another repo as it is
  • point the startup probe at /readiness, which fails while the gateway is unreachable, and keep liveness and readiness on /healthcheck. A revision whose image has no /readiness never starts, so roll out an image on mcp-core 2.0 before changing the probe
  • give the service its public hostname before customers connect, as the other public services have theirs. Tokens are bound to MCP_PUBLIC_URL, so changing it later disconnects every client
  • set trustProxy on createApplication to match the proxies in front of the service, such as a CDN and the platform’s ingress, so rate limits count per client and not per proxy. While the origin can also be reached directly, around the CDN, a caller can fill the forwarded header and choose its own address, so trust no more hops than every route to the service passes
  • put the secrets where the repo keeps secrets, and pass a shared replayStore in oauth once the service runs more than one instance

From the repo root, run:

pnpm codegen
pnpm check
pnpm test

Confirm codegen updates generated/persisted-documents.json and generated/mcp-tools.generated.ts, and that the persisted documents hold the excluded operations.

Then try it with a real client: connect, sign in, continue as a guest, and let a guest call a tool that needs a scope. Untick a scope on the consent screen and check that its tools are gone from the client’s list. Run stdio with pnpm --filter @evolve-platform/mcp-<name> dev:stdio, and check that stdout carries nothing but JSON.

To connect locally, run claude mcp add --transport http mcp-<name> http://localhost:<port>/mcp and sign in through /mcp in Claude Code. For a deployed service, a link opens Claude’s dialog to add a custom connector with the name and URL filled in:

https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=<name>&connectorUrl=<percent-encoded MCP_PUBLIC_URL>
  • the new service starts with the expected name and port
  • pnpm check and pnpm test pass
  • generated tools reflect only the operations the user confirmed against the supergraph
  • every tool that needs a customer names a scope
  • with business units, every tool that commits the company has businessUnit: REQUIRED
  • with OAuth, a customer and a guest can both connect, the consent page shows each scope as a checkbox, and a withheld scope removes its tools from the client
  • the root package.json exposes pnpm dev:mcp
  • all required changes are included, not only the files under backend/mcp-<name>
  • forgetting to ask which queries and mutations belong in operations.graphql
  • guessing GraphQL operations without checking the supergraph
  • copying all of the scaffold operations.graphql instead of keeping the new service focused
  • writing vague descriptions that do not explain prerequisite calls or where dependent IDs come from
  • leaving a tool without the scope its data needs. A tool that returns personal details needs one even when a guest would get nothing back
  • a consent text that says read-only for a scope that also changes data
  • leaving the tools that do most of a step without a scope, so unticking that scope on the consent screen changes nothing
  • a consent action that does not pass scopes, so the checkboxes have no effect
  • exposing a tool whose input no other tool can provide
  • leaving out CustomerLogout or BusinessUnitSwitch, which mcp-core runs but codegen only registers when operations.graphql holds them
  • adding a sign-in tool, which puts a customer’s password in the conversation
  • giving the storefront MCP_OAUTH_SECRETS, which would let it issue tokens
  • writing OAuth, session or business-unit code in the service instead of using @evolve-framework/mcp-core
  • removing module.ts or server.ts, which every Evolve service has
  • keeping state in a tool between calls. Over HTTP nothing is kept between requests
  • forgetting to rename scaffold strings in config, tests or server identity
  • wiring MCP startup into pnpm dev:backend instead of a separate pnpm dev:mcp
  • treating the rollout as complete after only editing backend/mcp-<name>