MCP Service Rollout
When to Use
Section titled “When to Use”- 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
Source Material
Section titled “Source Material”Use these as the minimum references before making changes:
backend/graphql-gateway/supergraph.generated.graphqlin the current repo, when available- the closest local
backend/mcp-*service in the current repo, when available - otherwise,
backend/mcp-customerinhttps://github.com/evolve-platform/evolve-reference-b2b, as a read-only scaffold source - the README of
@evolve-framework/mcp-coreand 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.
Required Input
Section titled “Required Input”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.graphqlfor available query and mutation fieldsbackend/for any existingmcp-*service that can act as the closest scaffold
Required Question
Section titled “Required Question”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.
Workflow
Section titled “Workflow”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>.
1. Choose the Baseline
Section titled “1. Choose the Baseline”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-customerfrom 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
2. Copy the Service Scaffold
Section titled “2. Copy the Service Scaffold”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 startStdioKeep 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.
3. Update Service Identity
Section titled “3. Update Service Identity”package.json: setnameto@evolve-platform/mcp-<name>, and keep the scriptscodegen,dev,dev:stdio,start,testandtscREADME.md: update the overview, the port and the examplessrc/config.ts: setCOMPONENT_NAME,HTTP_PORT,MCP_PUBLIC_URL, and theMCP_<NAME>_prefix inloadConfigsrc/module.ts: set the server’snametoevolve-mcp-<name>, and theresourceNameunderoauthsrc/cli.ts: setpackageName- 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.
4. Define operations.graphql
Section titled “4. Define operations.graphql”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: "...") scopeson@mcpToolnames 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 elsewheretools/listshows 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: REQUIREDon a tool that must name the company, such as placing an order. WithoutBusinessUnitSwitch, this fails when the server is built - put
businessUnit: NONEon a tool that does not depend on a company, such as the one that lists companies - an operation with its own
$businessUnitIdvariable 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.
5. Configure Codegen
Section titled “5. Configure Codegen”codegen.ts:
- always include
./operations.graphql - keep the schema inputs aligned with
../graphql-gateway/supergraph.generated.graphqland./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.
6. Connect the Storefront
Section titled “6. Connect the Storefront”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,transpilePackagesinnext.config.ts, and the styles toglobal.css - add
MCP_URLandMCP_INTERACTION_SECRETto the server config. Never give the storefrontMCP_OAUTH_SECRETS - create the flow with
createConnectFlow, and pass itCustomerLoginfrom@evolve-storefront/feature-auth/documentsandSessionGuestCreatefrom@evolve-storefront/session/documents - run
connectTicketStepfrom@evolve-storefront/feature-mcp-connect/proxyfirst in the site’s proxy, so themcp_requestticket moves into an HttpOnly cookie before any page or script loads - make the login page spread
useConnectFormontoLoginFormViewfromfeature-authwhen it carriesconnect, 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/connectpage withConnectConsentandConnectExpired, and its path to the site’s routing - in the consent action, pass the ticked scopes to
answerasscopes: formData.getAll("scope").map(String). Each scope is a checkbox; withoutscopesthe client gets every scope, whatever the customer unticked - set
guestScopesto 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, namedbusinessUnitId, 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.
7. Update the Root Dev Workflow
Section titled “7. Update the Root Dev Workflow”- add a root
pnpm dev:mcpwhen 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
8. Deployment
Section titled “8. Deployment”- register
generated/persisted-documents.jsonwith Hive before the version rolls out, as the storefront does, because the deployed gateway accepts nothing else - set
COMPONENT_VERSIONto 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/readinessnever 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
trustProxyoncreateApplicationto 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
replayStoreinoauthonce the service runs more than one instance
9. Run Validation
Section titled “9. Run Validation”From the repo root, run:
pnpm codegenpnpm checkpnpm testConfirm 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>Definition of Done
Section titled “Definition of Done”- the new service starts with the expected name and port
pnpm checkandpnpm testpass- 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.jsonexposespnpm dev:mcp - all required changes are included, not only the files under
backend/mcp-<name>
Common Mistakes
Section titled “Common Mistakes”- forgetting to ask which queries and mutations belong in
operations.graphql - guessing GraphQL operations without checking the supergraph
- copying all of the scaffold
operations.graphqlinstead 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
CustomerLogoutorBusinessUnitSwitch, which mcp-core runs but codegen only registers whenoperations.graphqlholds 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.tsorserver.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:backendinstead of a separatepnpm dev:mcp - treating the rollout as complete after only editing
backend/mcp-<name>

