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.
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.
| 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.
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_rolekey.get_publishable_keysreturns 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_migrationand 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_sqland 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.
Connect your client
If it won't connect, see MCP server not connecting in your AI tool. For when to let an agent loose on a database at all, see Can an AI coding agent manage my database?.