# The SupaHost MCP server

> Connect AI coding agents to your SupaHost projects with the MCP server: endpoint, access tokens, URL options for project, read-only and feature groups, and safety.

Source: https://supahost.app/docs/ai-tools/mcp · Updated 2026-11-11

The SupaHost MCP server lets AI coding agents (Claude Code, Cursor, Codex, VS Code, Windsurf and others) work with your projects directly. An agent can list tables, run SQL, apply migrations, generate TypeScript types, check for missing Row Level Security, and deploy and debug Edge Functions, all scoped by an access token you control.

It's modelled on Supabase's own MCP server, so tool names and behaviour will be familiar, but it talks to your SupaHost instance and uses SupaHost access tokens.

## Endpoint

```
https://mcp.supahost.space/mcp
```

It uses the **Streamable HTTP** transport: clients send JSON-RPC with `POST` and get JSON back. The server is stateless and accepts request bodies up to 4 MB. A `GET` gets `405`, so clients that only speak the older SSE transport can't connect. Most current MCP clients support Streamable HTTP.

## Authentication

Send a SupaHost access token as a bearer token:

```
Authorization: Bearer shp_0123456789abcdef...
```

Tokens start with `shp_` followed by 48 hex characters. SupaHost stores only a SHA-256 hash, so a token is shown once when you create it. A missing or wrong token gets `401` with `WWW-Authenticate: Bearer realm="supahost"`.

There's no OAuth sign-in yet. That's why hosted connectors such as Claude.ai custom connectors and ChatGPT developer-mode connectors show as "coming soon" in the dashboard: use a desktop or CLI client with a token for now.

### Create a token

The quickest way is the setup page: *Dashboard → **AI agents (MCP)*** in the sidebar (or a project's **Connect** tab → **AI agents (MCP)**, or **…** → **Hand off to an AI agent** in the project header). Pick your client, a scope, read-only or not, and the feature groups, then click **Create token**. The page shows the token once, an `export SUPAHOST_TOKEN="..."` line for your shell, and a config snippet for the client you picked.

You can also create tokens in *Dashboard → **Access tokens** → **New token***, with a Name, a Scope (one project, or "Whole instance (all projects)") and a Read-only option. See [Access tokens](/docs/platform/access-tokens).

| Token scope | What the agent can reach |
|---|---|
| One project | Only that project. Project tools work without a `project` argument. |
| Whole instance | Every project on the instance, plus `list_projects`, `get_project` and `create_project`. Project tools take a `project` argument. |

Keep the token in an environment variable (the examples use `SUPAHOST_TOKEN`), not in a file you commit.

## URL options

Query parameters on the endpoint can only **narrow** what the token allows. They never widen it.

| Parameter | Effect |
|---|---|
| `project=<name>` | Project-scoped token: must match the token's project, or you get `403`. Instance token: sets the default project for tools called without `project`. |
| `instance=<name>` | Must match the token's instance, or you get `403`. |
| `read_only=true` | Read-only mode, even if the token allows writes. |
| `features=<groups>` | Comma-separated list of tool groups to expose. |

For example, a read-only connection to project `app-one` with only database and docs tools:

```
https://mcp.supahost.space/mcp?project=app-one&read_only=true&features=database,docs
```

Quote the URL in shell commands: `&` and `?` mean something to your shell.

### Feature groups

| Group | Tools | On by default |
|---|---|---|
| `docs` | `search_docs` | Yes |
| `account` | `list_projects`, `get_project`, `create_project` (instance tokens only) | Yes |
| `database` | `list_tables`, `list_extensions`, `list_migrations`, `execute_sql`, `apply_migration` | Yes |
| `debugging` | `get_advisors` | Yes |
| `development` | `get_project_url`, `get_publishable_keys`, `generate_typescript_types` | Yes |
| `functions` | `list_edge_functions`, `get_edge_function`, `get_edge_function_logs`, `deploy_edge_function`, `delete_edge_function` | Yes |
| `storage` | `list_storage_buckets`, `get_storage_config` | No |

Storage is off by default to keep the tool list short; add `storage` to `features` if you want it. Details of every tool are in [MCP tools reference](/docs/ai-tools/mcp-tools).

## Read-only mode

Turn it on with a read-only token or `read_only=true`. Then:

- SQL runs as a dedicated read-only database role (`sh_readonly`), so Postgres itself rejects any write, even one hidden inside a function call.
- Write tools (`apply_migration`, `create_project`, `deploy_edge_function`, `delete_edge_function`) aren't registered at all, so the agent can't see them.

Use read-only for anything that touches production data.

## What agents can't do

- Get the `service_role` key. `get_publishable_keys` returns only the anon key.
- Change Auth settings, OAuth providers, function secrets, custom domains, backups or billing. There are no tools for those; they stay in the dashboard.
- Reach projects outside the token's scope.

## Safety

Agents act with your token's permissions. To keep that in check:

- **Scope tokens tightly.** One project per token, read-only where you can.
- **Keep tool-call approval on** in your client, at least for `execute_sql`, `apply_migration` and deploys.
- **Watch Activity.** Writes made over MCP show in *Dashboard → **Activity*** as `MCP (<token name>)`.
- **Revoke tokens** in **Access tokens** when you're done. The table shows each token's prefix and when it was last used.
- **Untrusted data is marked.** Results from `execute_sql` and function logs are wrapped in boundaries that tell the model not to follow instructions found in the data. That reduces prompt-injection risk; it doesn't remove it.

The server also sends the agent a short set of guidelines on connect: inspect the schema before writing SQL, use `apply_migration` for schema changes, enable RLS on new tables, run `get_advisors`, and don't run `create extension pg_cron`. Add your own on top with a rules file; see [Rules and prompts for AI agents](/docs/ai-tools/agent-rules).

## Connect your client

- [Connect Claude Code](/docs/ai-tools/claude-code)
- [Connect Cursor](/docs/ai-tools/cursor)
- [Connect Codex, VS Code, Windsurf and others](/docs/ai-tools/other-clients)

If it won't connect, see [MCP server not connecting in your AI tool](/kb/mcp-not-connecting). For when to let an agent loose on a database at all, see [Can an AI coding agent manage my database?](/kb/ai-agent-database).