Skip to main content
Glama

keystone-mcp

Mount an MCP endpoint on the Express server of a Keystone 6 app.

What the users of your app get

  • A user adds https://<your app>/mcp to an MCP client, such as Claude Desktop, Claude Code or MCP Inspector. The client opens a page of your app, where the user signs in with their email and password and allows the client.

  • The agent in the client gets two tools. searchTool finds the queries and mutations of the app, with their arguments and the field paths that a call can select. callTool runs one of them.

  • The agent acts as the user who signed in. Keystone access control decides what it can read and change, as in the Admin UI: a user who may not update a post cannot update it through the agent either.

  • When it connects, the agent reads a short description of the project: your paragraph, then the kinds of records in plain words.

The package uses only the public hook server.extendExpressApp and the public context. It does not modify @keystone-6/core.

For a working app, start with the shop example in examples/shop: a small Keystone 6 shop with access rules, seed data, a storefront, and the steps to connect MCP Inspector and Claude Desktop.

Related MCP server: mcp-app-server

Install

npm install keystone-mcp

The app must have express and graphql installed; Keystone 6 brings both.

To try a local checkout instead, install it as a copy, so that the package shares the graphql and express copies of the app: npm install --install-links /path/to/keystone-mcp.

The package ships ESM (dist/index.js) and CommonJS (dist/cjs/index.js). Keystone compiles keystone.ts to CommonJS and loads the CommonJS build.

Wire it in keystone.ts

The package needs password sign-in from @keystone-6/auth (createAuth), because users sign in to the MCP endpoint with it. Without an authenticate<List>WithPassword mutation in the schema, keystoneMcp throws at start.

import { config } from '@keystone-6/core';
import { createAuth } from '@keystone-6/auth';
import { keystoneMcp } from 'keystone-mcp';

const { withAuth } = createAuth({ listKey: 'User', identityField: 'email', secretField: 'password' });

export default withAuth(
  config({
    db: { /* ... */ },
    lists,
    session,
    server: {
      extendExpressApp: keystoneMcp({
        instructions: 'The blog of Example Inc. Authors write posts; readers leave comments.',
      }),
    },
  }),
);

To keep another extendExpressApp function, call both:

const mcp = keystoneMcp({ queriesOnly: true });

server: {
  extendExpressApp: (app, context) => {
    app.get('/health', (_req, res) => res.json({ ok: true }));
    mcp(app, context);
  },
},

At start, and again after each keystone dev rebuild, the server log shows one line for the endpoint:

keystone-mcp: MCP endpoint at /mcp: 48 operations, search on, sign-in with authenticateUserWithPassword, sign-ins end at restart; keystoneMcp({ secret }) keeps them.

It names the path, the number of operations that the agent can find, whether searchTool is on, the mutation that the sign-in page runs, and whether sign-ins survive a restart. When search is off, the line names the reason and the option that turns it on: search off (NODE_ENV=production); keystoneMcp({ introspection: true }) turns it on. With the secret option, the line ends with sign-ins sealed with secret.

Try it on your computer

An MCP client that runs on your computer, such as MCP Inspector or Claude Code, connects to http://localhost:3000/mcp directly. It needs no tunnel, no HTTPS and no trust proxy.

  1. Start the app with a fixed session secret:

    export SESSION_SECRET="$(openssl rand -hex 32)"
    npm run dev

    keystone.ts must pass it to the session, for example session: statelessSessions({ secret: process.env.SESSION_SECRET }). Without a fixed secret, Keystone makes a new one each time it loads keystone.ts, also at each dev rebuild, and the client must sign in again after each edit.

  2. Find the mount line in the log: keystone-mcp: MCP endpoint at /mcp: … operations, search on, ….

  3. Connect a client.

    • MCP Inspector: run npx @modelcontextprotocol/inspector. It opens its page in the browser. Click Add Servers, then + Add manually. Enter the server ID shop, choose the transport streamable-http, enter the URL http://localhost:3000/mcp, and click Add. Then turn on the switch of the shop server.

    • Claude Code: run claude mcp add --transport http shop http://localhost:3000/mcp. claude mcp list then shows shop with ! Needs authentication. In Claude Code, run /mcp, choose shop, and choose Authenticate.

  4. The browser opens the sign-in page of the app. The page says where the browser goes next: the client's own address on your computer, for example 127.0.0.1:6274 for MCP Inspector. Sign in as a user of the app, and click Sign in and allow.

  5. Run a call. In MCP Inspector, open Tools and choose callTool. Enter the operation products and the select ["name"], and click Execute Tool. The result holds the products that this user may read. In Claude Code, ask for the products.

After a schema edit, keystone dev rebuilds and logs the mount line again, with the new number of operations. The client stays signed in. After a restart of the process, it signs in again, unless the app sets secret.

Before you deploy

  • SESSION_SECRET. Set a random string of 32 characters or more, and pass it to statelessSessions. Without it, each start makes a new secret, and every user signs in again. Give every process the same value.

  • secret. Set a second random string of 32 characters or more, for example openssl rand -hex 32 in MCP_SECRET, and pass keystoneMcp({ secret: process.env.MCP_SECRET }). Give every process the same value. Then MCP clients stay signed in across a deploy or restart, and every process behind a load balancer accepts their tokens. Without it, clients and tokens live in the memory of one process: a restart signs every user out, and another process rejects them. A new secret ends every grant, so change it only to sign everyone out.

  • trust proxy. Behind a proxy or tunnel that ends TLS, set Express trust proxy in extendExpressApp. Without it, Express reads each request as http, the OAuth URLs use http, and a client that connected over https refuses them. The server log warns once per process when a request has X-Forwarded-Proto: https but Express reads http:

    keystone-mcp: a request to /.well-known/oauth-protected-resource/mcp has X-Forwarded-Proto: https, but Express reads it as http, so the OAuth URLs use http and MCP clients refuse them. Behind a proxy or tunnel that ends TLS, call app.set('trust proxy', 1) in extendExpressApp.
    const mcp = keystoneMcp();
    
    server: {
      extendExpressApp: (app, context) => {
        app.set('trust proxy', 1);
        mcp(app, context);
      },
    },
  • introspection. With NODE_ENV=production, searchTool is off by default, as in Apollo Server, and the mount line says so. To keep search, pass keystoneMcp({ introspection: true }). callTool works either way.

  • Several processes. Set secret and SESSION_SECRET to the same values in each. Without secret, run one process per app.

Connect Claude Desktop

Claude connects from Anthropic's cloud (160.79.104.0/21), so the app must be reachable over public HTTPS. For a local app, use a tunnel, for example cloudflared tunnel --url http://localhost:3000, and set trust proxy (see Before you deploy). To try the endpoint without a tunnel, use a local client: see Try it on your computer.

  1. In Claude Desktop, open Customize > Connectors. On a Team or Enterprise plan, an Owner adds the connector in Organization settings > Connectors with Add, then Custom.

  2. Click Add custom connector.

  3. Enter a name, for example Keystone, and the URL of the endpoint, for example https://cms.example.com/mcp. The URL must be the app's public origin followed by path.

  4. If the dialog asks how Claude identifies itself, choose Register automatically. The package supports dynamic client registration. Leave the OAuth client ID and secret empty.

  5. Click Add, then Connect. A browser window opens the sign-in page of the app.

  6. Check that the page says your browser goes to claude.ai. Enter your Keystone email and password, and click Sign in and allow.

  7. The browser returns to Claude, and the connector shows as connected. Ask Claude, for example, "Find the posts with draft status and publish the first one."

Claude acts as the user who signed in. A user who may not update a post in the Admin UI cannot update it through Claude either.

Control what the agent can do

Keystone access control applies to each call. Two more levers exist in Keystone today.

Hide a list or an operation with graphql.omit. The catalog comes from the public GraphQL schema, so an operation that the schema omits is gone from searchTool and callTool, and from /api/graphql too:

Category: list({
  access: allowAll,
  // No deleteCategory and no deleteCategories, for any client.
  graphql: { omit: { delete: true } },
  fields: { /* ... */ },
}),

Tell an MCP call from other calls with context.req. callTool runs with the context of the POST <path> request, so a hook sees context.req.url equal to path, for example /mcp. A request to /api/graphql has another url:

hooks: {
  beforeOperation: ({ operation, context }) => {
    if (context.req?.url === '/mcp') console.log(`An MCP client runs ${operation}.`);
  },
},

Options

Option

Default

Effect

path

/mcp

The HTTP path of the endpoint.

queriesOnly

false

When true, the catalog holds queries only, and callTool cannot mutate.

takeLimit

50

The maximum take that callTool sends, in either direction. A missing take becomes this. A negative take reads from the end and stops at -takeLimit.

introspection

NODE_ENV !== 'production'

When false, searchTool returns a tool error that asks the agent to have the app's owner turn search on, and callTool still runs operations by name. The server instructions still name the operations for one record. The default follows Apollo Server's introspection default. Keystone does not pass the app's graphql.apolloConfig to extendExpressApp, so to match it, pass the same value to both.

instructions

none

One paragraph about the project, in your words. The server instructions start with it, before the part that the package builds from the catalog.

secret

none

A random string of 32 characters or more, the same in every process. With it, the OAuth clients, sign-ins, codes and tokens are sealed values that need no server state, so MCP clients stay signed in across a restart and every process accepts them. Without it, they live in the memory of the process and end at restart. A shorter string throws at start. See Sign-in for what a sealed grant cannot do.

Behavior

  • POST <path> serves a stateless MCP Streamable HTTP endpoint with JSON responses. Each request creates a new MCP server.

  • GET <path> and DELETE <path> respond 405 with JSON-RPC error code -32000.

  • A POST <path> without a valid access token gets 401 with WWW-Authenticate: Bearer … resource_metadata="<origin>/.well-known/oauth-protected-resource<path>".

  • callTool runs context.withRequest(req, res) and then context.graphql.run, with the Keystone session of the user behind the access token. Keystone access control applies as for any GraphQL request.

  • When a call fails, callTool returns a tool error whose text is {"errors":[{"message":…,"extensions":{"code":…}}]} with one of three codes. ACCESS_DENIED: Keystone denied access (KS_ACCESS_DENIED, KS_FILTER_DENIED). INVALID_INPUT: an argument has the wrong type, a validation failed, a take exceeds the list's limit, or the catalog rejects the input (KS_USER_INPUT_ERROR, KS_VALIDATION_FAILURE, KS_LIMITS_EXCEEDED). SERVER_ERROR: every other failure, such as a database error (KS_PRISMA_ERROR), a hook that throws, an access function that does not return a boolean, or an unknown code. A list of field errors (KS_RELATIONSHIP_ERROR, KS_RESOLVER_ERROR, KS_EXTENSION_ERROR) gets ACCESS_DENIED or INVALID_INPUT only when each of its field errors has that meaning.

  • An ACCESS_DENIED or INVALID_INPUT error keeps its message, because the message helps the agent fix the call; a wrong argument is named as Argument "take". A SERVER_ERROR gets a fixed sentence, and so does any message that names Keystone, GraphQL, Prisma or Apollo. When the agent gets a fixed sentence, the server logs the original error with console.error. /api/graphql keeps Keystone's own codes and messages, and the app's graphql.apolloConfig.formatError does not run on <path>.

  • The initialize result carries instructions for the client: the instructions option first, then the kinds of records in plain words (from the list names, for example products and order lines), the operations for one record of each kind, and how to search and call. With introspection off, it still names the operations.

  • The text that the agent reads (server instructions, tool and argument descriptions, the search-off message, the sign-in page, the session-ended errors and the errors of a failed call) describes the project and names no technology: no Keystone, GraphQL or Prisma.

  • The catalog skips the root field keystone. Keystone builds a new catalog after each dev rebuild.

  • The JSON and form body parsers run on <path> and <path>/oauth/* only.

Sign-in (OAuth 2.1)

The package is the OAuth authorization server for its own endpoint. It serves:

Path

Purpose

/.well-known/oauth-protected-resource<path> and /.well-known/oauth-protected-resource

Protected resource metadata (RFC 9728).

/.well-known/oauth-authorization-server

Authorization server metadata (RFC 8414). The issuer is the origin of the app.

<path>/oauth/register

Dynamic client registration (RFC 7591). Redirect URIs must use https, or http on a loopback host.

<path>/oauth/authorize

The sign-in and consent page. It shows the host that the browser returns to.

<path>/oauth/token

Code exchange with S256 PKCE, and refresh. Each refresh returns a new refresh token. Without secret, the old one then gets invalid_grant.

<path>/oauth/revoke

Token revocation (RFC 7009).

  • Redirect URIs match exactly. Only the port of a loopback redirect (localhost, 127.0.0.1, [::1]) can differ from the registered one.

  • The sign-in page runs the app's password mutation. The client gets its own access token (1 hour) and refresh token; the Keystone session token is never readable by the client.

  • The grant ends with the Keystone session: when the session expires (statelessSessions maxAge, 8 hours by default) or the user is deleted, /mcp answers 401 and refresh answers invalid_grant, so the client asks the user to sign in again.

  • Without secret, clients and tokens live in the memory of the process. They survive a keystone dev rebuild, because Keystone keeps the package loaded. After a restart, each user signs in again. Run one process per app.

  • With secret, the server keeps no OAuth state. The client_id, the transaction of the sign-in page, the code and the tokens are values sealed with AES-256-GCM under a key derived from secret, so a client cannot read or change them. A value sealed with another secret, changed in one character, or expired gets 401 on /mcp and an error at the token endpoint. A client_id is about 250 characters and an access token about 900.

  • What a sealed grant cannot do, because no server remembers its use: a code works more than once within its 5 minutes (PKCE still binds it to the client's verifier); a refresh token keeps working after it was used, until it expires (30 days), so its reuse is not detected; revoke does nothing, so a grant ends only when the Keystone session ends or the token expires; a sign-in page ends, and its limit of 5 password tries counts, only in the process that handled it, so another process accepts the same page until it expires (10 minutes). Keystone's statelessSessions has the same limits.

  • The issuer and resource URLs come from each request: req.protocol and the Host header. Behind a proxy or tunnel that ends TLS, set Express trust proxy, so that the URLs use https. See Before you deploy.

Tool input

searchTool:

{ "text": "posts", "limit": 10 }

callTool:

{
  "operation": "posts",
  "args": { "where": { "title": { "contains": "mcp" } }, "take": 5 },
  "select": ["id", "title", "author.name"]
}

Without select, callTool selects the top-level paths of the operation.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables turning selected OpenAPI operations into authenticated MCP tools with branded OAuth, operation allowlisting, and live schema refreshes.
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables existing apps to expose their users and data to external AI agents via MCP with OAuth 2.1 authentication and scoped tools.
      51 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables any MCP client to read and edit database schemas (DBML/SQL), Mermaid diagrams, and shared board layouts, along with the organizations, projects, documents, and marketplace listings around them. It runs as a hosted OAuth 2.1 endpoint, so there is nothing to install and access is limited to what the signed-in user can already see.
      MIT