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.
- The hook needs its migration first. If the Custom Access Token Hook is switched on before the migrations that create it, every sign-in fails, including the administrator's.
- The MCP service needs the caller read before deployment. Apply
20261112120000_current_principal.sqlto the hosted Site before deploying the MCP service. The server callsapi.current_principal()on every request; without it, authenticated requests fail. - The MCP address is set last, because it is the switch. Until
auth_hooks.mcp_server.canonical_urlholds the address, an assistant's tokens carry no audience and the MCP server refuses them. Everything before step 10 can be done and left standing without opening anything.
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
- The Site is open and its web app is up. See Open a Site and Set up the Site web app. The web app must be a build that includes the
/oauth/consentpage, and an administrator must be able to sign in. Deployis green for the Site, so the image you will run exists. See Deploy and roll back.- You can reach the Supabase dashboard, the Site's operator connection string (see Open a Site), and the Railway and GitHub settings.
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.
- Check: every file in
site/db/supabase/migrationsshows as applied locally and remotely, including20261012120000_oauth_token_rule.sql, which creates theauth_hooksschema. - If not: do not go on. Read the push error. Do not edit an applied migration.
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.
- Check:
<supabase url>/auth/v1/.well-known/jwks.jsonlists a key with"alg": "ES256". - If not: create an ECC P-256 signing key and rotate to it in the dashboard, then check the list again. Stop and ask before rotating a Site that already has signed-in users.
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.
- Check: an administrator can still sign in to the web app with a fresh sign-in link.
- If not: switch the hook off in the dashboard, confirm step 1, and try again.
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.
- Check:
<supabase url>/.well-known/oauth-authorization-server/auth/v1returns a document that includes aregistration_endpoint. - If not: the dashboard lists the OAuth Server under Auth. Check it is saved and 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.
- Check: Site URL is
https://<site web>with nothing after it, and the callback is still in Redirect URLs. An administrator's sign-in link still works. - If not: see the 404 under Troubleshooting below.
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.
- Check: the service exists and shows a generated
<mcp domain>.
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.
- Check: all four are set. The service will not start without
SITE_SUPABASE_PUBLISHABLE_KEY. - If not: read the
mcpservice's log in Railway. It names the missing setting.
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.
- Check: the run is green, including the wait for MCP's health.
- If not: the run's log names the failing service. For an unhealthy
mcp, read its Railway log. See Deploy and roll back.
9. Check the server before opening it
All three checks need no sign-in.
GET https://<mcp domain>/healthreturns 200.GET https://<mcp domain>/mcpwith no token returns 401, and itsWWW-Authenticateheader carries aresource_metadatapointer.- The protected-resource metadata that pointer names lists
https://<mcp domain>/mcpas the resource, and your Supabase project as the authorization server (issuer).
- Check: all three.
- If not: a wrong
resourcemeansMCP_CANONICAL_URLis wrong. A wrong issuer meansSITE_SUPABASE_URLis.
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';
- Check:
SELECT canonical_url FROM auth_hooks.mcp_server;returns that one row. The next token issued to an assistant carries it as its audience. - If not: the two must match exactly. A mismatch, even a trailing slash, can leave every token refused (see Troubleshooting).
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.
- Check: the client lists the projects.
- If not: see Troubleshooting 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:
| Code | Meaning |
|---|---|
bad-id | The authorization_id is missing or malformed. |
signed-out | No signed-in administrator. |
details-threw | Looking up the request failed with an error. |
details-error | Supabase returned an error for the request: usually expired, already answered, or unknown. |
no-data | Supabase returned nothing for the request. |
empty-redirect | The request was already answered, and Supabase gave no address to go back to. |
other-user | The request belongs to a different signed-in user. |
bad-redirect-uri | The app's return address could not be read. |
answer-threw | Approving or denying failed with an error. |
answer-error | Supabase returned an error on approve or deny. |
no-redirect-url | Supabase 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.
- One assistant, one administrator. The administrator can open Connected apps in the Site and select Disconnect for that app. This revokes their grant and ends refresh. The access token already issued keeps working until it expires, up to an hour. The same operation is
DELETE <supabase url>/auth/v1/user/oauth/grants?client_id=<client id>, called with that administrator's session token. - Everything one person can reach, at once. Deactivate the administrator. A deactivated administrator's tokens read nothing and write nothing as soon as the change is made, whichever token they hold (§7.6).
- One app, for everyone. Delete its OAuth client with the Auth Admin API:
DELETE <supabase url>/auth/v1/admin/oauth/clients/<client id>, authorized with the Site's service key. List the clients first withGET <supabase url>/auth/v1/admin/oauth/clients. The service key is an operator credential: use it in a shell for the one run, as the other scripts do, and never hold it in the web app or the MCP service.- The call returns 204, the client no longer appears in the list, and its refresh token is then refused with 400
invalid_credentials. An access token issued before the deletion still works until it expires.
- The call returns 204, the client no longer appears in the list, and its refresh token is then refused with 400
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
- 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.
- Check:
- Remove
RAILWAY_MCP_SERVICE_IDfrom the GitHub Environment, so thatDeployskips the service.- Check: the next
Deployhas no MCP step.
- Check: the next
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.