Browse this guideTurn MCP on
DevelopmentUpdated 2026-11-13

Turn MCP on

MCP lets an administrator connect an AI assistant, such as Claude or ChatGPT, to their Site. It runs as its own Railway service, and it works only after Supabase's OAuth server, a token hook, and the Site web app's consent page are configured to match. This page gives the order. Every step has a check. Do not go on until it passes.

Three parts of the order matter.

Placeholders are as in the Platform runbook: <site web> is the Site web app's origin and <supabase url> is https://<project-ref>.supabase.co. <mcp domain> is the domain Railway generates for the mcp service. Never write the real values into a page, commit, or pull request.

Before you start

1. Apply the migrations

The OAuth token rule, the MCP reads and writes, proposals, and the token hook arrive as migrations. From site/db, run supabase db push, then supabase migration list.

2. Check the JWT signing keys are asymmetric

The MCP server checks each token's signature against the Site's published keys, so the project must sign with an asymmetric key (ECC P-256, which Supabase calls ES256), not the old shared secret. In the dashboard, open the project's JWT signing keys.

3. Switch on the Custom Access Token Hook

In the dashboard's Auth settings, add a Custom Access Token hook of type Postgres function, and choose the function auth_hooks.mcp_access_token. It adds the MCP address as the audience on tokens issued to an assistant, and it does nothing to a web sign-in. If the address setting is empty, or the hook cannot read it, it fails safe: no audience is added.

4. Switch on the OAuth Server

In the dashboard's Auth settings, open OAuth Server and switch it on. Set the authorization path to /oauth/consent, and turn on dynamic client registration. An assistant registers itself as a client the first time it connects, so registration must be on.

5. Set the Site URL to the web origin

In the dashboard's Auth URL configuration, set Site URL to the bare web origin, https://<site web>, with no path. Keep https://<site web>/auth/callback in the Redirect URLs. Supabase builds the consent link from the Site URL plus the authorization path, so the Site URL must be the origin and nothing more.

6. Create the Railway mcp service

Create the service, from the GitHub container-registry image with its registry credential, and give it a generated domain. The details, in order, are in Open a Site (the section "Optional: enable MCP deployment"). Do not set a start command by hand: Deploy applies it from services.json, as a /bin/sh -c command so that Railway's $PORT is expanded.

7. Set its four variables

On the mcp service, set SITE_SUPABASE_URL, SITE_SUPABASE_PUBLISHABLE_KEY, SITE_WEB_URL, and MCP_CANONICAL_URL, which is https://<mcp domain>/mcp. The MCP server holds no secret; the publishable key is the Site's public one. See Open a Site for each value.

8. Set the GitHub Environment variables and deploy

In the Site's site-<site> GitHub Environment, add RAILWAY_MCP_SERVICE_ID and MCP_HEALTH_URL (https://<mcp domain>/health). See Open a Site. Then dispatch Deploy from main.

9. Check the server before opening it

All three checks need no sign-in.

  1. GET https://<mcp domain>/health returns 200.
  2. GET https://<mcp domain>/mcp with no token returns 401, and its WWW-Authenticate header carries a resource_metadata pointer.
  3. The protected-resource metadata that pointer names lists https://<mcp domain>/mcp as the resource, and your Supabase project as the authorization server (issuer).

10. Set the MCP address: the switch

Run this in the Supabase SQL editor, or with the operator connection string. The value is exactly MCP_CANONICAL_URL, character for character:

UPDATE auth_hooks.mcp_server SET canonical_url = 'https://<mcp domain>/mcp';

11. Test the connection

From any MCP client, add the address from step 10 as a remote MCP server (some apps call it a custom connector). Connect, sign in if asked, and on the Connect an app screen check that the "sends you back to" line is the web address of the client you are connecting, then select Approve. Ask the client to list the projects. To use Claude Code, see "Test with another client" below.

The administrator-facing version of this step is Connecting an AI assistant.

Troubleshooting

The assistant lands on a 404 page when it sends the administrator to approve. The Site URL ends in a path, for example /auth/callback. Supabase builds the consent link from the Site URL plus /oauth/consent. Set the Site URL to the bare origin (step 5).

The mcp service crashes at start. Read its log in Railway. If SITE_SUPABASE_PUBLISHABLE_KEY is missing, the service stops at start (step 7).

The assistant connects and then every call is refused. Compare auth_hooks.mcp_server.canonical_url with MCP_CANONICAL_URL (step 10), then disconnect and connect again so the assistant gets a fresh token. If authenticated requests fail with an unavailable error, confirm 20261112120000_current_principal.sql is applied remotely (step 1).

The consent page says the request expired or was already answered. Every failure shows this one message. The reason is in the Site web app's Vercel runtime logs as a single line, oauth-consent: <code>. It carries no authorization id, user, app name, redirect address, or Supabase error text. The codes:

CodeMeaning
bad-idThe authorization_id is missing or malformed.
signed-outNo signed-in administrator.
details-threwLooking up the request failed with an error.
details-errorSupabase returned an error for the request: usually expired, already answered, or unknown.
no-dataSupabase returned nothing for the request.
empty-redirectThe request was already answered, and Supabase gave no address to go back to.
other-userThe request belongs to a different signed-in user.
bad-redirect-uriThe app's return address could not be read.
answer-threwApproving or denying failed with an error.
answer-errorSupabase returned an error on approve or deny.
no-redirect-urlSupabase answered but gave no address to send the browser to.

Source: oauth-consent.ts. An authorization id is 32 lowercase letters and digits, not a UUID.

Test with another client

Any client that follows the MCP authorization standard can connect to the same address. To use Claude Code, once the switch is set:

claude mcp add --transport http provenience https://<mcp domain>/mcp

Then run /mcp inside Claude Code, choose the server, and sign in and approve in the browser. Test with a throwaway account on a test Site first, never an administrator's real session on a Site you cannot afford to disturb.

Revoke a connection

Choose the narrowest of these that does what you need.

An assistant's own screen can remove its connection too. For an administrator's Site connection, use Connected apps so Provenience revokes the grant.

Turn MCP off

  1. Shut agent tokens out: UPDATE auth_hooks.mcp_server SET canonical_url = '';. New tokens carry no audience, and the server refuses them.
    • Check: SELECT canonical_url FROM auth_hooks.mcp_server; returns an empty value, and a new connection attempt is refused. A token issued before the change lives out its hour.
  2. Remove RAILWAY_MCP_SERVICE_ID from the GitHub Environment, so that Deploy skips the service.
    • Check: the next Deploy has no MCP step.

The Railway service, the hook, and the OAuth server can stay in place. To switch back on, restore the address (step 10) and the variable.

What is logged

The MCP server records counters only (§7.11): calls, denials, latency, result-count bands, and limit hits, grouped by tool and OAuth client. It does not keep prompts, results, record ids, or an assistant's answers. A write made through MCP is a Daybook event like any other, with a via field that names the app's client. Nothing here asks you to read customer content.