Skip to content
excalibase
mcp
MCPbeta

MCP for AI coding tools

Excalibase serves a hosted MCP endpoint at https://app.excalibase.io/mcp. Point an AI coding tool at it with a token and the tool can read your project's schema, run SQL and migrations, set API permissions, deploy functions and apps, and read logs. It goes through the same API and the same checks as Studio, so it can do what your role can do and nothing more. There is nothing to install: the server is hosted, and Cursor, Claude Code, Codex and Gemini CLI connect to it over HTTP.

1. Create a token in Studio

  1. Open your project in Studio and choose AI Tools in the project's menu. The page is called Connect your AI tool.
  2. Pick your tool, and pick Read only or Read and write.
  3. Pick when the token expires: 30 days, 90 days or 1 year.
  4. Choose Create token and show setup.

The token is shown once, together with the setup for your tool. Copy it before you click I have saved it; if you lose it, create another.

  • Project-bound. The token reaches this project only, and the URL carries the project id: https://app.excalibase.io/mcp?project=<id>.
  • Read only lets the agent look and query. It is offered no write tool, and SQL runs in a read-only transaction. A read-only URL ends in &read_only=true.
  • Read and write lets it change the project, still limited by your own role. A viewer's token cannot apply a migration, exactly as a viewer cannot in Studio.

2. Set up your tool

Studio fills in your project id. Each setup keeps the token in the EXCALIBASE_TOKEN environment variable, so no config file you commit holds a secret. Add the token to your shell profile (~/.zshrc or ~/.bashrc) and open a new terminal:

export EXCALIBASE_TOKEN=<your token>

Replace <id> below with your project id. For a read-only connection add &read_only=true to the URL.

Claude Code

claude mcp add --transport http excalibase "https://app.excalibase.io/mcp?project=<id>" --header "Authorization: Bearer $EXCALIBASE_TOKEN"

Claude Code saves the header as your shell expanded it, so the token ends up in its config.

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "excalibase": {
      "url": "https://app.excalibase.io/mcp?project=<id>",
      "headers": { "Authorization": "Bearer ${env:EXCALIBASE_TOKEN}" }
    }
  }
}

Codex

Add to ~/.codex/config.toml:

[mcp_servers.excalibase]
url = "https://app.excalibase.io/mcp?project=<id>"
bearer_token_env_var = "EXCALIBASE_TOKEN"

codex exec cannot ask you to approve a tool, so on a read and write connection every write tool is refused by the client. For codex exec runs only, add this line to the same block:

default_tools_approval_mode = "approve"

Gemini CLI

Add to .gemini/settings.json in your project:

{
  "mcpServers": {
    "excalibase": {
      "httpUrl": "https://app.excalibase.io/mcp?project=<id>",
      "headers": { "Authorization": "Bearer $EXCALIBASE_TOKEN" }
    }
  }
}

3. Your first prompt

Start with something that uses the project, not a blank page:

  • "Look at my project and tell me what tables and permissions it has."
  • "Build a feedback board with sign-in, realtime votes and deploy it."
  • "Add a comments table, let signed-in users read everyone's comments but edit only their own, and show me the migration first."
  • "Why did my last deploy fail? Check the logs."

For the first one a read-only token is enough. The agent reads your project first, writes a migration and the permissions, builds the page, tests the requests the page makes, and deploys it as a container app. See the examples gallery and its source for the kind of app that comes out.

What your agent can do

Tools marked write are not offered on a read-only connection.

Project and schema

ToolWhat it does
list_projects, get_project_infoList the projects the token reaches; get a project's GraphQL, REST, auth and realtime endpoints, publishable keys, CORS origins and an SDK setup snippet.
list_tables, describe_tableTables and views; columns, indexes, CHECK constraints and foreign keys.
get_graphql_schema, generate_typescript_typesWhat the GraphQL and REST APIs are generated from; TypeScript row types for every table.
create_publishable_key (write)A publishable SDK key for client apps. Only publishable keys, never a secret one.

SQL and migrations

ToolWhat it does
execute_sqlOne statement. On a read-only connection it runs in a read-only transaction and refuses functions that act outside it.
list_migrations, apply_migration (write)The migration history; apply a SQL migration and record it.

Permissions

ToolWhat it does
list_permissionsWhich role may select, insert, update or delete which rows and columns of each table, and which functions are tracked.
set_permission (write)Set or remove one permission for a table, role and operation. A table a role has no permission for is hidden from that role.
track_db_function, set_db_function_permission (write)Serve a database function through the API and decide which roles may call it. A query function tracked with inference (the default) is callable by every role that may select its return table, so taking its function permission away has no effect: the answer says so. Remove that role's select on the return table, or track the function again with infer_permissions: false.

Realtime

ToolWhat it does
set_realtime (write)Turn realtime on or off for one table. Events still pass through the subscriber's select permission.

CORS

ToolWhat it does
list_cors_originsThe browser origins allowed to call the project's APIs.
add_cors_origin, remove_cors_origin (write)Allow or stop allowing an origin, such as a local dev server or a custom domain.

Functions and outbound hosts

ToolWhat it does
list_functions, deploy_function (write), delete_function (write)Create, update, list and delete edge functions.
set_function_outbound_hosts (write)Allow or stop allowing outside hosts your functions may call. Anything not listed is blocked.
set_function_secret (write)Set a secret a function reads as an environment variable. The value is never returned.

Apps, deploy and CI

ToolWhat it does
list_apps, create_app (write), update_app (write), delete_app (write)Container apps. A new app's public URL is added to the CORS allowlist, and removed again when the app is deleted.
deploy_app (write), get_deploy_statusDeploy an image by digest and poll until the deploy succeeded or failed. Images from a private registry need a credential saved in Studio first. commit_sha is 7 to 64 lowercase hex characters, with or without image.
get_dockerfile_template, get_ci_snippetA Dockerfile for node, Next.js, Vite, Python, Go or Java; a ready pipeline for GitHub Actions, GitLab CI, Jenkins or a plain curl step. The agent writes them into your repository.

Sites

ToolWhat it does
list_sites, create_site (write), delete_site (write)Sites: static frontend builds served from the CDN. A site's origin is added to the CORS allowlist on its first deploy. A server-rendered app is a container app instead.
deploy_site (write), list_site_deploys, rollback_site (write)Deploy built files (a base64 gzipped tar of the output folder, at most 1 MiB; bigger builds deploy from CI with get_ci_snippet), list deploys and make an earlier one live again.
list_site_domains, add_site_domain (write), check_site_domain (write), remove_site_domain (write)Custom domains: the answer names the CNAME and TXT records to add at your DNS provider; a check sets the domain up once the TXT proof is seen.
connect_site_repo (write), list_site_buildsBuild and deploy a site on every push to a GitHub branch, and read each build's status and log. Needs the GitHub App installed from Studio.

Testing and logs

ToolWhat it does
test_api_requestSend one request to the project's own REST or GraphQL API the way a page does, as anon, with a publishable key, or as a signed-in user. Permissions, RLS and CORS apply. It reads only on a read-only connection.
test_auth_flowTry one sign-up or sign-in with a throwaway test account and report the outcome and the user's role claims, never the password or tokens. On a read-only connection only sign-in runs.
get_logsRecent logs of the database, an app or an edge function.

What your agent can't do

MCP is a door to building and shipping code, not to running your account. It never offers:

  • creating or deleting projects
  • members and roles
  • plans and tiers
  • sign-in providers
  • backups and restores
  • reading or rotating database credentials
  • minting tokens

Do these in Studio. create_publishable_key is the only key an agent can make, and a publishable key only grants what your project's anon role is allowed.

Safety

  • Permissions are enforced. Every tool call is an ordinary API request carrying your token, so org roles, project access and token scope apply exactly as in Studio.
  • You see what it did. The AI Tools page lists each call: tool, token name, time and result. SQL and secret values are not kept.
  • Revoke any time. Revoke a token you own from the activity list. Another member's token is never shown.
  • Set secrets yourself. A secret you give the agent passes through the conversation and the tool's logs. Ask it to tell you which secret to set, and set it in Studio under Edge Functions then Secrets.
  • Prefer read only until you want the agent to change something.

Troubleshooting

  • 401 or the tool will not connect. The token is wrong, expired or revoked, or it belongs to another project. Only personal access tokens work: a Studio sign-in session does not. Create a new token and check that EXCALIBASE_TOKEN is set in the terminal that started your tool.
  • Every tool call says it is refused. The URL asks for something the token does not allow, such as another project's id. Some clients hide the reason when the connection opens, but each tool call states it.
  • A write tool is missing. The connection is read only: the token has the read scope, or the URL ends in &read_only=true.
  • CORS still blocks a new origin. A CORS change takes about a minute to reach the data plane. Wait, then test again.
  • A deploy says "running, URL not answering yet". The app started but its URL does not answer. The reason is given: a certificate still issuing, DNS, or no ready instance. While a certificate is pending browsers refuse the URL; poll get_deploy_status again.
  • A deploy fails with "health check ... answered HTTP 404". The app runs but does not serve its health check path. The deploy fails once the app has answered that path with a 4xx for 2 minutes after its start delay, instead of waiting out the 10-minute deadline. An app that is still starting (connection refused, 503) is not failed early. Fix the path, or serve it.
  • An app reads ACTIVE but restarted appears. list_apps and get_deploy_status show how often the app's containers restarted since its deploy started them, and why the last one stopped. OOMKilled means it ran out of its memory limit.
  • A private image is refused. Save the registry credential in Studio first. The error names the registry.
  • Counting rows answers 403 permission_denied. Allow aggregations on that role's select permission.

Self-hosting

On your own install MCP is off until you turn it on: set FEATURE_MCP=true (chart value features.mcp). Until then /mcp answers 404 and Studio hides AI Tools. The Dockerfile, CI and deploy-by-image tools also need FEATURE_PIPELINE=true (features.pipeline). Use your own Studio host instead of app.excalibase.io. The full reference is docs/mcp.md.