Access tokens
Create, scope and revoke SupaHost access tokens for the MCP server and AI coding agents. Project or instance scope, read-only tokens and narrowing access with URL parameters.
Access tokens let tools act on your SupaHost projects without your password. Today they authenticate the SupaHost MCP server, which is how AI coding agents such as Claude Code, Cursor and Codex read your schema, run SQL, apply migrations and deploy Edge Functions.
Tokens look like shp_ followed by 48 hex characters. They're different from your projects' anon and service_role keys: a project key talks to one project's APIs, while an access token talks to SupaHost's MCP server about one project or your whole instance.
SupaHost doesn't offer the Supabase Management API, so access tokens don't work with tools built for that API.
Create a token
You can create one in two places:
- Dashboard → Access tokens → New token, or
- Dashboard → AI agents (MCP) → Create token, which also gives you a ready-made config snippet for your client.
Each token has:
| Setting | Options |
|---|---|
| Name | Anything that tells you who or what uses it, such as jo-cursor-laptop |
| Scope | One project, or Whole instance (all projects) |
| Read-only | On or off |
The full token is shown once, when you create it. SupaHost stores only a SHA-256 hash of it, so nobody, including SupaHost, can show it to you again. Copy it straight into your tool's config or a password manager. If you lose it, revoke it and make a new one.
When a token is created, SupaHost sends an "access token created" security email. If you didn't create it, revoke it right away.
Scope and read-only
Project scope limits the token to one project. Prefer it whenever an agent works on a single app.
Whole instance lets the token see every project, and is the only scope that can list projects and create new ones (creating one beyond your plan's allowance needs explicit confirmation of the extra cost).
Read-only tokens run SQL as a special role, sh_readonly, that can read all data but can't write. Postgres itself rejects any write, and the write tools (such as apply_migration and deploy_edge_function) aren't offered to the agent at all. Use read-only for exploring production, reviewing data, or teammates' tools.
Narrowing a token with URL parameters
You can make a token do less than it allows by adding parameters to the MCP URL. They can only narrow access, never widen it.
| Parameter | Effect |
|---|---|
project=app-one |
Work with this project only |
instance=acme |
Must match the token's instance |
read_only=true |
Read-only, even if the token isn't |
features=database,docs |
Only these tool groups: docs, account, database, debugging, development, functions, storage. By default all are on except storage |
For example, a project-wide token used read-only against production:
claude mcp add --transport http supahost-prod \
"https://mcp.supahost.space/mcp?project=app-one&read_only=true" \
--header "Authorization: Bearer $SUPAHOST_TOKEN"
Client-by-client setup is in The SupaHost MCP server, Connect Claude Code and Connect Cursor.
The token list
The Access tokens page lists each token with:
| Column | Meaning |
|---|---|
| Prefix | The first 8 characters, to tell tokens apart |
| Scope | The project, or the whole instance |
| Access | Read-only or read-write |
| Created | When it was made |
| Last used | When it last authenticated a request |
| Revoke | Turns the token off |
A token that hasn't been used for months is a good candidate for revoking.
Seeing what a token did
Changes made through MCP show in Dashboard → Activity with the actor MCP (<token name>) and a badge. That's why good names matter: MCP (jo-cursor-laptop) tells you who to ask about a migration; MCP (token1) doesn't.
If a token leaks
- Revoke it on the Access tokens page. Requests with a revoked token are rejected with a 401.
- Check Activity for writes by that token.
- If it was read-write and you see changes you didn't expect, consider a point-in-time restore.
Good habits
- One token per person per tool, never shared.
- Project scope and read-only by default; widen only when needed.
- Keep tokens in environment variables or your client's secret storage, not in files you commit. If your MCP config lives in the repo, reference an environment variable as above.