MCP Server
Control your Aurabase backend from Claude Desktop, Cursor, Windsurf, Antigravity, Mistral AI, VS Code or any Model Context Protocol compatible client — 86 tools, no manufactured value.
Local stdio mode by default, local HTTP mode#
The official Aurabase MCP server exposes 86 tools to inspect and control your backend (82 with a project key). It runs on your machine, in one of two modes:
- stdio mode (default): your MCP client starts the server as a subprocess with
npx. - HTTP mode (Streamable HTTP): you start one local server (
http://127.0.0.1:3001/mcp) and point each client to its URL.
The hosted service (https://mcp.aurabase.dev/mcp, sign-in with OAuth 2.1) is planned, not live yet.
The package has two binaries (aurabase-mcp and aurabase-mcp-hosted), so npx needs the binary name: npx -y -p @aurabase/mcp-server aurabase-mcp. --project-id is required.
npx -y -p @aurabase/mcp-server aurabase-mcp \
--url https://<slug>.aurabase.cloud \
--project-id <uuid> \
--service-role-key aura_sk_…
To start the local HTTP server instead, add the transport, port and token:
npx -y -p @aurabase/mcp-server aurabase-mcp \
--transport http \
--port 3001 \
--auth-token my_secret_token \
--url http://localhost:8080 \
--project-id <uuid> \
--service-role-key aura_sk_…
Configuration per client and per mode#
stdio mode (default)
Cursor (.cursor/mcp.json), Claude Desktop (claude_desktop_config.json), Windsurf (~/.codeium/windsurf/mcp_config.json), Google Antigravity (~/.gemini/config/mcp_config.json) and VS Code with Cline or Roo Code (cline_mcp_settings.json) use the same block:
{
"mcpServers": {
"aurabase": {
"command": "npx",
"args": ["-y", "-p", "@aurabase/mcp-server", "aurabase-mcp"],
"env": {
"AURABASE_URL": "https://<slug>.aurabase.cloud",
"AURABASE_PROJECT_ID": "<uuid>",
"AURABASE_SERVICE_ROLE_KEY": "aura_sk_…"
}
}
}
}
Against a local Docker/k3d stack, set AURABASE_URL to http://localhost:8080.
HTTP mode (local server)
Start the local HTTP server (see above), then add its URL and the --auth-token value as a Bearer token.
Cursor — .cursor/mcp.json or ~/.cursor/mcp.json:
{
"mcpServers": {
"aurabase": {
"url": "http://127.0.0.1:3001/mcp",
"headers": {
"Authorization": "Bearer my_secret_token"
}
}
}
}
Windsurf — ~/.codeium/windsurf/mcp_config.json (the key is serverUrl):
{
"mcpServers": {
"aurabase": {
"serverUrl": "http://127.0.0.1:3001/mcp",
"headers": {
"Authorization": "Bearer my_secret_token"
}
}
}
}
Continue.dev (VS Code & JetBrains with Codestral) — ~/.continue/config.yaml:
models:
- name: Codestral
provider: mistral
model: codestral-latest
apiKey: MISTRAL_API_KEY
mcpServers:
- name: aurabase
url: http://127.0.0.1:3001/mcp
headers:
Authorization: Bearer my_secret_token
Mistral AI (Agents & Connectors) reaches MCP servers over a public HTTPS URL: it will use the hosted service (https://mcp.aurabase.dev/mcp), planned, not live yet.
A tool returns the response from the backend, or an error#
Never a manufactured value. This rule is not an intention: it is checked at each execution of the CI by a bench which launches the server against a dead URL and fails if the slightest tool responds successfully. Each tool also declares an output schema that the SDK validates before emitting the response.
Read-only mode (--read-only) removes mutating tools from the catalog and instructs PostgreSQL to execute the SQL in a read-only transaction (37 tools of 86) — the guarantee comes from the engine, not just from client-side filtering.
Flags and environment variables#
--url(AURABASE_URL) — Aurabase instance URL--project-id(AURABASE_PROJECT_ID) — Project ID--service-role-key(AURABASE_SERVICE_ROLE_KEY) — Admin Key--read-only(AURABASE_READ_ONLY) — Only exposes reading tools (37 of 86)--allowed-tools(AURABASE_ALLOWED_TOOLS) — Whitelist, separated by commas--destructive-policy(MCP_DESTRUCTIVE_POLICY) — Interactive confirmation of destructive SQL operations:elicit(default),token,deny--state-key(MCP_STATE_KEY) — Key (≥ 32 bytes) that signs multi-turn confirmations--transport—stdio(default) orhttp--port— HTTP transport port (default 3001)--host— HTTP listening interface (default127.0.0.1)--auth-token(AURABASE_MCP_AUTH_TOKEN) — Token required on /mcp — required in http mode
Distributed by domain#
82 exposed with a simple project key, 4 reserved for the management plan (API keys and list_all_projects — better no tool than a tool that systematically fails without this channel).
| Database (23) | list_tables, describe_table, get_performance_advisors, list_extensions, execute_sql, query_table, insert_rows, update_rows, delete_rows, call_rpc, generate_types, diff_schema, apply_migration, list_migrations, explain_query, analyze_table, get_db_size, list_sql_functions, create_sql_function, drop_sql_function, list_sql_triggers, create_sql_trigger, drop_sql_trigger |
|---|---|
| Storage (9) | list_buckets, get_bucket, create_bucket, list_files, delete_files, move_file, create_signed_url, upload_file, empty_bucket |
| Auth (7) | list_users, get_user, create_user, update_user, delete_user, ban_user, generate_link |
| Notifications (10) | send_email, send_push_notification, send_sms, list_notification_logs, get_notification_settings, update_notification_settings, list_notification_templates, create_notification_template, delete_notification_template, get_notification_stats |
| Backups (5) | list_backups, create_backup, restore_backup, get_backup_schedule, set_backup_schedule |
| Edge Functions (6) | invoke_function, list_functions, get_function_info, deploy_function, delete_function, set_function_env |
| RLS (6) | list_rls_policies, create_rls_policy, update_rls_policy, drop_rls_policy, toggle_rls, get_security_advisors |
| AI (5) | index_document, rag_query, vector_search, create_vector_index, ai_completion |
| Observability (4) | get_project_metrics, list_slow_queries, list_active_queries, cancel_query |
| Realtime (3) | list_realtime_channels, get_realtime_settings, update_realtime_settings |
| Project (4) | project_info, switch_project, get_active_project, list_all_projects (management channel) |
| API keys (3) | create_api_key, list_api_keys, revoke_api_key (management channel) |
| Documentation (1) | search_docs — search in embedded documentation (English) |
The *_sql_function / *_sql_trigger tools create real PostgreSQL functions and triggers stored in the project schema — unrelated to list_functions / deploy_function (Edge Functions WASM, a separate runtime).
HTTP mode for clients that connect by URL#
stdio is the default transport. The http mode (Streamable HTTP, MCP protocols 2025-11-25 and 2026-07-28):
- listens on
127.0.0.1by default (--hostto change it); - requires a token (
--auth-tokenor Bearer token) — without it, the server refuses to start; - validates the
Originheader and responds 403 to an unauthorized origin (anti-CSRF protection); - one server instance per session, with expiration and configurable cap;
- compares tokens in constant time and bounds request body size.