Developers/MCP/Connect Your AI Editor over MCP

Connect Your AI Editor over MCP

Point Claude Code, Cursor, or GitHub Copilot at Supero's MCP server and build, validate, publish, and deploy real Supero apps without leaving your editor.

What this is

Supero exposes an MCP (Model Context Protocol) server that lets your own AI coding agent — Claude Code, Cursor, GitHub Copilot, or any MCP-capable client — build real Supero apps on your behalf. It is a bridge to the platform, not a chatbot: your agent authors app files locally (schemas, config, UI) and calls a small set of build_* tools over MCP to validate, publish, and deploy them against your Supero domain and project.

This page covers connecting an editor, how authentication and key scope work, and the tool-by-tool flow of a build session. For the authoring walkthrough itself, see Build an App over MCP. It is aimed at developers who already have (or can create) a Supero API key and want their agent to build directly against the platform.

💡 Bring your own agent

You are not limited to one client. Any MCP client that speaks Streamable HTTP and JSON-RPC 2.0 can connect — Claude Code, Cursor, and Copilot are simply the three with first-class setup instructions below.

Endpoint & transport

The MCP server speaks JSON-RPC 2.0 over a single Streamable HTTP endpoint. There is no per-tool or per-method route — every initialize, tools/list, tools/call, and ping request is a POST to the same path.

Method & path	Auth required	Purpose
POST /mcp/v1/messages	yes	Send any JSON-RPC 2.0 message: initialize, tools/list, tools/call, ping
GET /mcp/v1/health	no	Liveness check — confirms the MCP service is up
GET /mcp/v1/info	no	Server name, version, protocol version, and capabilities — useful for confirming your endpoint/host before wiring credentials

bash

curl https://api.supero.dev/mcp/v1/info

json

{
  "name": "supero",
  "version": "2.0.0",
  "protocol_version": "2025-03-26",
  "transport": "streamable-http",
  "endpoint": "/mcp/v1/messages",
  "authentication": {
    "methods": ["bearer", "api_key"],
    "bearer": { "header": "Authorization", "format": "Bearer <jwt_token>" },
    "api_key": { "header": "X-API-Key", "format": "<api_key>" }
  },
  "capabilities": { "tools": true, "resources": true, "prompts": true }
}

A raw JSON-RPC call to tools/call looks like this once you're authenticated (see the next section):

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "build_whoami",
    "arguments": {}
  }
}

ℹ️ You rarely call this directly

Your editor's MCP client handles the JSON-RPC framing for you once it's configured (see Editor setup below). The raw request/response shapes here are for scripting or troubleshooting a connection.

Authentication

The MCP endpoint accepts the same two credential types as the REST API: a JWT bearer token or an API key. Send exactly one — domain, project, and tenant scope are derived entirely from the credential, so there is no domain segment anywhere in the MCP URL.

•Authorization: Bearer <jwt_token> — a session token from POST /api/v1/auth/login.
•X-API-Key: <api_key> — an opaque key starting ak_, created in the Supero dashboard. Never send an API key as a Bearer token.

MCP/build API keys begin with ak_ and are scoped to the project (and tenant) they were minted for. The scope a key carries determines what it can build (see Key scope below).

⚠️ Requests need a resolvable domain

If neither header is present, or the credential can't resolve to a domain, the server returns a JSON-RPC error (HTTP 401/400) before any tool runs. Double-check you're sending the raw ak_... value with no "Bearer " prefix.

Key scope & roles

Build tools authorize against the role your credential resolves to. Each API key resolves to a role whose scope is fixed when the key is minted; plain JWT sessions are not project-scoped the same way, so they cannot run mutating build tools (project creation, publish, deploy, teardown).

Credential	Resolves to	Can build into
Domain-admin key	domain_admin	Any project in the domain, and can create new projects
Project-admin key	project_admin	That one project only
Tenant-scoped key	tenant_user	Refused — cannot run build tools
Plain JWT session (Bearer)	jwt	Refused for mutating build tools; read-only calls only

A project-admin key that targets a different project's project_uuid than the one it's scoped to is refused with a clear error rather than a bare permission failure. Replacing a project's entire app (build_replace_project) additionally requires a domain-admin key.

Editor setup

Create an API key for the project (or domain, if you want your agent to be able to create new projects) in the Supero dashboard at app.supero.dev, then wire it into your editor with one of the snippets below.

Claude Code

bash

claude mcp add --transport http supero \
  https://api.supero.dev/mcp/v1/messages \
  --header "X-API-Key: ak_..."

Run it in a terminal — there's no config file to edit. Then check /mcp inside Claude Code; you should see supero listed as a connected server.

Cursor

json

{
  "mcpServers": {
    "supero": {
      "url": "https://api.supero.dev/mcp/v1/messages",
      "headers": { "X-API-Key": "ak_..." }
    }
  }
}

Save this to ~/.cursor/mcp.json, then in Settings go to MCP and toggle supero on, and reload the window.

GitHub Copilot (VS Code)

json

{
  "servers": {
    "supero": {
      "type": "http",
      "url": "https://api.supero.dev/mcp/v1/messages",
      "headers": { "X-API-Key": "ak_..." }
    }
  }
}

Save this to .vscode/mcp.json, then run "MCP: List Servers → Start" from the Command Palette and switch Copilot Chat to Agent mode.

🚨 Treat your API key like a password

Anyone with the key can build into whatever it's scoped to. Keep it out of source control — most editors store MCP config outside the repo (Claude Code's is local machine config; put project-level Cursor/Copilot config files in .gitignore) — and rotate it from the dashboard if it leaks.

Your first build session

Once connected, tell your agent what to build in plain language — it should reach for the build_* tools itself rather than guessing at the platform's shape. A typical first session looks like this:

•build_whoami — resolve your key's role, domain, and what you're allowed to do. Always start here.
•build_get_skills — fetch the build spec your agent authors schemas.py / config.py / setup.py / ui/app.js against.
•build_create_project (or build_list_projects + build_get_project for an existing one) — pick or create the target project, and read its schema_namespace.
•build_validate — AST-only validation of the authored bundle against the live platform; your code is never executed.
•build_publish — package, upload, and record a version; returns a version_uuid and download_url.
•build_deploy (target: local for you to run, or cloud_ephemeral for a short-lived managed preview) — or build_go_live for a permanent public URL at <project>.supero.live.

json

// tools/call params for the first step of a session
{
  "name": "build_whoami",
  "arguments": {}
}

💡 Iterating on an existing app

For a change request on an app you already published, have your agent start from build_get_bundle rather than re-authoring from scratch — that pulls the current published files (including any hand-tuned UI) so edits build on top of them instead of silently dropping prior work.

Tool reference

The build_* family is grouped by what stage of the build lifecycle it belongs to. Your agent discovers the full set (with JSON-Schema input shapes) by calling tools/list once connected — this table is the map to keep in your head, and the MCP tool reference documents every tool and protocol method in full.

Group	Tools	What it's for
Docs & planning	build_get_skills, build_get_examples, build_plan, build_get_service_contract	Fetch the build spec, a complete reference app to copy patterns from, a checklist for a described app idea, and the state-machine contract for a transactional service (cart, order, booking, payment, ...)
Project	build_whoami, build_list_projects, build_get_project, build_create_project, build_update_project, build_set_project_mode, build_replace_project	Resolve your scope, find or create the target project, read its schema_namespace, and (destructively, domain-admin only) wipe-and-replace a dev-mode project's app
Build lifecycle	build_validate, build_publish, build_stage_bundle, build_get_bundle, build_deploy, build_deploy_status, build_logs, build_go_live, build_teardown	Validate, publish a version, stage a large bundle out-of-band, fetch the current published bundle, deploy (ephemeral or permanent), poll status, read logs, and tear a deployment down
Capabilities & integrations	build_list_capabilities, build_recommend_integrations, build_configure_services	List the live services catalog, get tiered integration recommendations for an app description, and wire test/sandbox keys for a service
Quality gates	build_doctor, build_smoke_test, build_e2e_test, build_e2e_test_status	Preflight a bundle for silent deploy-killers, verify a deployed URL actually loads and reads data, and run the full behavioural test suite against a deployed app
Data sources	build_list_data_sources, build_connect_data_source, build_discover_source, build_bind_data_source, build_run_data_source, build_list_bound_schemas	Connect an app's own database, REST API, or warehouse, discover its schema, and bind it to app schemas for live or synced reads

For any schema-backed service your app extends (cart, order, booking, appointment, payment, membership, inventory, and more), have your agent call build_get_service_contract before authoring its UI rather than guessing operation names or required fields — it returns the real state machine, operations, and default UI schemas for that service.

Usage, limits & billing

MCP tool calls and successful publishes draw from your plan's Power allowance the same way other platform activity does — current plan tiers and allowances are on the Billing screen in your dashboard at app.supero.dev/billing.

Limit	Value
Files per bundle	300
Bytes per file	2 MB
Total bundle size (inline)	~8 MB

💡 Bundle too big to send inline?

If your app's files exceed what fits inline (or your model's own output-token cap truncates large files), use build_stage_bundle to get an out-of-band upload URL, upload a compressed {path: content} blob with your own key, and pass the returned file_id as files_ref to build_validate / build_publish / build_doctor instead of files.

Next steps

•supero-mcp on GitHub: a step-by-step first build, 26 project briefs to pick from, and community apps you can run and improve
•Authentication — how login, JWT refresh, and API keys work across the REST API and MCP
•Schema Reference — the fields/references/namespace model your agent authors schemas.py against
•CRUD Endpoints — the REST endpoints a deployed app's UI (and your own scripts) call directly
•Choosing a Deployment Option — the three deploy targets (Supero Cloud, your own AWS/GCP, on-premise) beyond build_go_live's managed preview and permanent URL

← PreviousCLI (App Runner)Next →Build an App over MCP

On this page