Developers/MCP/Build an App over MCP

Build an App over MCP

The end-to-end path: mint a correctly scoped API key, connect your editor, drive a build through the build_* tools, and deploy — either a short-lived preview or a permanent one.

Driving Supero from an AI editor over MCP to build a full application — You direct the build from your editor; Supero provides the tenancy, access control and data layer underneath.

Before You Start

If you are driving a build from an agent loop rather than an editor session, Build with an AI Agent covers that shape.

This page is the whole path in order: get a key, connect an editor, build, deploy. If you only want the tool signatures, go to the MCP Tools & Protocol Reference; if you want to know what MCP is for in the first place, start at Connect Your AI Editor over MCP.

🚨 Building requires an API key — a login session will not work

This is the single most common way a first attempt fails. The build tools refuse a caller authenticated with a JWT bearer token from a normal login. You must authenticate with an API key. Mint one as described below before you configure your editor.

The fastest route to a working setup is the console: open your project and choose Connect via MCP. That page mints a correctly scoped key and hands you the exact configuration block for your editor. Everything below explains what it is doing, so you can do it by hand or automate it.

1. Get an API Key, and Scope It Correctly

Scoping is where most of the confusion lives, so it is worth stating the rule plainly.

ℹ️ The scope is the address, not a setting

A key's reach is determined by which domain, project and tenant its fully-qualified name points at. There is no "level" field you set. Change the address and you change what the key can do.

Key is created under	Effective role	Can it build?
`default-project` / `default-tenant`	`domain_admin` — the whole domain	Yes, and more besides. Broader than a build needs.
your project / `default-tenant`	`project_admin` — that one project	Yes. This is the one you want for building.
your project / a named tenant	`tenant_user` — one tenant's data	No. Build tools refuse this role.

So a build key is a key created under the project you intend to build, in that project's default-tenant. That is exactly what the console's Connect via MCP page mints.

🚨 A build key is project-wide — never ship it as a runtime credential

The reason this key can build is the reason it must not leave your machine: a key against a project's default-tenant resolves to project_admin and can read every tenant in that project. That is correct for authoring an application and wrong for anything the application itself runs with. Keep build keys in your editor configuration, mint separate credentials against named tenants for runtime, and delete a build key when you are finished with it — disabling one does not reliably revoke it.

bash

curl -X POST https://api.supero.dev/api/v1/domains/acme/api-key \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_name": "my-app",
    "tenant_name": "default-tenant",
    "description": "MCP build key",
    "scopes": ["read", "write", "delete"]
  }'

Scopes cap a key — they never widen it

The scopes list narrows what a key may do within the role its address already implies. It cannot grant anything the role does not have.

scopes	What the key can do
`["read"]`	Read only.
`["read", "write"]`	Read and write, but not delete.
`["read", "write", "delete"]`	Full record access. Use this for a build key.

⚠️ A read-only key will start a build and then fail partway

The build tools decide whether you may build from the key's address, not from its scopes — so a read-only key looks like a valid project builder, begins publishing, and is then refused when it tries to write. The failure appears late and reads like a platform error. Mint build keys with read, write and delete, which is what the console does.

Revoking a key

🚨 Delete a key to revoke it — disabling is not enough

Setting a key to disabled does not reliably stop it being accepted, because an already-authenticated key can continue to be served from cache. Deleting the key is what actually evicts it. If you believe a key has leaked, delete it; do not disable it and assume you are covered. Rotation is also available and issues a new secret against the same key — note there is no grace period, so the old secret stops working immediately and anything using it will break at once.

ℹ️ Two fields that are stored but not enforced today

An expiry date and an hourly rate limit can both be set on a key, and both are recorded — but neither is currently applied on the authentication path. Do not rely on either as a control. Treat key lifetime as something you manage by deleting keys.

2. Connect Your Editor

Supero exposes an MCP server over HTTP. Point your editor at it and pass the key in the X-API-Key header.

Setting	Value
Endpoint	`https://api.supero.dev/mcp/v1/messages`
Transport	Streamable HTTP, JSON-RPC 2.0
Auth header	`X-API-Key: ak_...`

Claude Code

bash

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

Cursor — ~/.cursor/mcp.json

json

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

VS Code — .vscode/mcp.json

json

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

⚠️ Send exactly one credential header

If your editor also sends an Authorization header — left over from another server, or added by a proxy — that header wins, and every build tool will refuse you as a session caller. If builds fail immediately with an authentication error while your key is definitely valid, a stray Authorization header is the first thing to check.

Verify the connection

Ask your editor to call build_whoami. It returns the domain, project and role your key resolved to, so you can confirm the scope is what you intended before you build anything.

💡 Do not verify by listing tools

The tool list is static and is returned regardless of whether your credential is any good, so a dead key still produces a healthy-looking list. build_whoami is the check that actually exercises authentication.

3. Build the Application

The build tools are designed to be driven in a particular order, and the server tells your editor that order when it connects. You do not have to memorise it — but knowing the shape helps you understand what your editor is doing and where a build went wrong.

1
build_whoami
Confirm which domain, project and role the key resolved to.
2
build_create_project, or list and get an existing one
Establish the project you are building into.
3
build_get_skills and build_get_examples
Pull the platform's own build guidance and worked examples into your editor's context. Skipping this is the most common cause of a build that produces plausible but non-working code.
4
build_plan
Turn your intent into a concrete plan before any file is written.
5
Author the bundle
Your editor writes the files. See the file contract below.
6
build_validate
Static checking of the bundle. Your code is analysed, never executed.
7
build_doctor
Catches the problems validation cannot see — startup and seeding issues, reserved names, namespace collisions.
8
build_publish
Registers the version with the platform.
9
Deploy
See the next section.
10
build_smoke_test
Confirms the deployed URL actually renders, and that the deploy you are looking at is the one you just published.

The bundle file contract

A bundle must contain exactly these seven files.

•schemas.py — your object types
•config.py — project identity and the services you import
•setup.py — provisioning, seed data and workflow definitions
•__main__.py
•requirements.txt
•run.sh
•ui/app.js — the application shell resolver

⚠️ Six files must not be in the bundle

ui/index.html, ui/config.js, ui/server.py, Dockerfile, docker-compose.yml and .env are provided by the platform at run time. If your editor generates them, they are dropped — and if you have hand-edited one expecting it to ship, your change will silently not apply.

Iterating after the first build

Fetch the current bundle with build_get_bundle, edit, then run validate, doctor and publish again. Each publish creates a new version rather than overwriting the last.

If you want to start over rather than iterate, a project can be reset and rebuilt in place, keeping its credentials, keys, namespace and tenant. That is a domain-admin operation and it is refused on a project that is currently live, which is deliberate.

Adding integrations

Integrations are declared in config.py by their catalog service id. build_list_capabilities shows you what exists; build_recommend_integrations suggests what suits the application you are describing. See External Integrations for what each one needs.

⚠️ Configure test credentials only over MCP

The service-configuration tool is for sandbox and test keys. Do not put live payment or messaging credentials through it — set those in the dashboard, where they go into the key store.

4. Deploy

There are two deployment tools, and the difference is how long the result lives.

Tool	What you get	Lifetime
`build_deploy`	A preview, or a local run. Targets are `cloud_ephemeral` and `local`.	The cloud preview expires after 30 minutes.
`build_go_live`	A permanent application on its own `supero.live` subdomain.	Until you take it offline.

ℹ️ Going live is reachable from MCP

You do not have to switch to the dashboard to publish permanently. build_go_live is a first-class tool, so the whole path from empty project to a permanent URL can be driven from your editor.

Both cloud paths are asynchronous

A deploy call returns a poll URL rather than a finished deployment. Poll build_deploy_status until it resolves. If a deploy is still pending after about five minutes, treat it as failed rather than continuing to wait, and use build_logs to find out why.

Limits worth knowing before you hit them

Limit	Value
Preview lifetime	30 minutes
Files per bundle	300
Size per file	2 MB
Total bundle size	8 MB
Request body	12 MB

Permanent hosting depends on your plan. build_whoami reports whether your plan includes it, so check that before you plan a launch rather than discovering it at the deploy step. Builds and deploys draw on your plan's usage allowance; when an allowance is exhausted the platform says so explicitly, naming which one.

🚨 Two failure modes that look like something they are not

If you try to launch a preview over an application that is already published, the platform refuses with a conflict. That is expected — do not respond by tearing down the published app. Separately, if a teardown reports that it did not stop, believe it: the application is still running and still consuming your allowance. Re-run it rather than assuming the report is wrong.

Where to Go Next

Ideas for what to build

Project briefs, a step-by-step first build, and community apps with source. supero-mcp on GitHub

Tool reference

Every tool, its parameters, and the protocol details. Open

What you are building on

Domain, project, tenant, and the Builder/Runtime split. Core Concepts

A worked example

A multi-tenant issue tracker built this way, end to end. Case study

Compare the paths

MCP is one of five ways in. Ways to Build

← PreviousConnect Your AI Editor over MCP Next →MCP Tools & Protocol Reference

On this page