# 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.

Source: https://supahost.app/docs/platform/access-tokens · Updated 2026-11-11

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:

```bash
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](/docs/ai-tools/mcp), [Connect Claude Code](/docs/ai-tools/claude-code) and [Connect Cursor](/docs/ai-tools/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

1. **Revoke** it on the Access tokens page. Requests with a revoked token are rejected with a 401.
2. Check **Activity** for writes by that token.
3. If it was read-write and you see changes you didn't expect, consider a [point-in-time restore](/docs/platform/point-in-time-recovery).

## 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.

## Related

- [MCP tools reference](/docs/ai-tools/mcp-tools)
- [Rules and prompts for AI agents](/docs/ai-tools/agent-rules)
- [Keeping keys safe](/docs/security/api-key-safety)
- [MCP server not connecting in your AI tool](/kb/mcp-not-connecting)