Connecting AI tools over MCP

Flatstack runs a remote MCP server at https://api.flatstack.dev/mcp. Claude, Claude Code, Cursor, Codex and any other client that speaks MCP over Streamable HTTP can connect to it, sign in with your Flatstack account, and then create projects, deploy, set variables and secrets, manage domains and email, import from Supabase or Clerk, read logs and usage, and look things up in these docs for you.

Connecting

You sign in once in the browser: the client opens Flatstack’s consent screen, you choose what it may do, and it receives its own token. You need a Flatstack account first; the MCP server can’t create one.

Claude Code

claude mcp add --transport http flatstack https://api.flatstack.dev/mcp

Then run /mcp in Claude Code, choose flatstack and Authenticate.

Claude (claude.ai and the desktop app): Settings, Connectors, Add custom connector, with the URL https://api.flatstack.dev/mcp. Then choose Connect.

Cursor: add to ~/.cursor/mcp.json (or the project’s .cursor/mcp.json):

{ "mcpServers": { "flatstack": { "url": "https://api.flatstack.dev/mcp" } } }

Cursor shows Needs login next to the server; choose it to sign in.

Other clients: give them the URL. A client that supports MCP authorisation finds the sign-in on its own. One that doesn’t can send a personal access token instead, as Authorization: Bearer fs_pat_…, for example claude mcp add --transport http flatstack https://api.flatstack.dev/mcp --header "Authorization: Bearer $FLATSTACK_TOKEN".

What the consent screen asks

The consent screen names the app, shows the address it will return you to, and lists what it asked to do. Untick anything you don’t want it to have. It never gets more than your role allows (see Teams and roles): a developer can’t give an app projects:write, for example, and if your role changes later, the app’s access changes with it.

Like other tokens, an MCP app can’t manage members or tokens, change plan or cards, remove add-ons, or transfer a project to another account. Those need you signed in to the dashboard; an owner sends a project from its Settings in the dashboard and the receiving owner accepts it on Projects, then Transfers (see moving a project). With projects:lifecycle, an owner’s app can delete and restore projects (delete_project needs confirm: true).

Connected apps are listed on Security in the dashboard, with what each can do and when it was last used. Disconnect cuts one off at once. An app nobody uses for 90 days is disconnected on its own. Owners and admins see and can disconnect every member’s apps.

Tools

Every tool calls the same API the dashboard and CLI use, so it behaves the same way and its changes are in the audit log, under the app’s token. Most tools take projectId (from list_projects) and an optional environment: production, the default, or preview/<name>.

More tools arrive as their features ship: branches, errors, SQL, export and type generation.

Sandboxes without an account

https://api.flatstack.dev/mcp/sandbox needs no sign-in. It offers create_sandbox, which makes a 24-hour sandbox and returns its URL, a token and a claim link for the person you’re building for, and then apply_schema, deploy, get_deploy_status, get_logs, run_security_scan, set_env, set_secret and search_docs for that sandbox alone. Send the token as a Bearer token or as each tool’s token argument; projectId isn’t needed. Three sandboxes an hour and ten a day per address (sandbox_rate_limited). Account tokens are refused there, and sandbox tokens are refused here.

Results, warnings and errors

Every result is JSON with a warnings list. It holds cap warnings (a metric at 80% of its limit, or capped at 100%) and security scan findings. Clients should show them to you.

Results of create_project, deploy, publish_site and a completed get_import_status also carry next: the setup step to offer you next (id, label, the CLI command, the mcpTool that does it, and a docs link), or null once the setup checklist is complete. It is the earliest checklist step still undone that a tool can do; get_activation returns the whole checklist. Agents are asked to offer it once, in their own words.

A failed call comes back as a tool error whose body is the API’s error: { "error": { "code", "message", "docsUrl", "details"? }, "warnings": [] }. The codes are the API’s own; each has a page under errors. Arguments that don’t match a tool’s schema get validation_failed with details for each field. A missing permission is forbidden, with details.requiredPermission.

Changes that can’t be undone

Destructive tools refuse to run without confirm: true and answer confirmation_required. remove_email_domain, archive_project and delete_project are. apply_schema and deploy take confirm: true to apply migrations that drop or rewrite data; without it they answer destructive_migration and list the changes. A deploy with critical scan findings is refused with deploy_blocked_by_scanner unless the call passes forceInsecure: { confirm: "<project slug>" }. A client should ask you before setting any of these.

For client developers

The server follows the MCP authorisation spec.

• POST /mcp takes one JSON-RPC message and answers application/json. There are no sessions and no server-sent stream: GET and DELETE answer 405.
• Without a valid token, /mcp answers 401 with WWW-Authenticate: Bearer resource_metadata="https://api.flatstack.dev/.well-known/oauth-protected-resource/mcp".
• OAuth 2.1 with PKCE (S256), dynamic client registration and rotating refresh tokens. The endpoints are in OAuth for MCP clients.
• Access tokens last an hour and only work at /mcp; /v1 refuses them. Use a personal access token for the REST API.
• Deploy tokens can’t use /mcp.

As Markdown: apps/mcp.md