Supero

supero-mcp

Build and deploy a real web app from your AI assistant, using Supero over MCP.

You describe the app. Your assistant (Claude Code, Cursor, VS Code Copilot, or any MCP client) reads the build spec from Supero, writes the app, validates it, and deploys it to a URL you can open. The app gets sign-in, roles, a database, an admin panel and an API from the platform, so the assistant writes the part that is yours and nothing else.

This repo has three things:

• This guide: how to connect and build, start to finish.
• Project briefs: 31 apps worth building, in 16 verticals, written as requirements. Pick one and build it.
• Community apps: apps people have built, with source. Run one, add your own, or send a fix to someone else's.

The free plan gives you 3 projects and needs no card. Deployments on it are 30-minute previews; a URL that stays up is a paid plan.

Start here

The rest of this page is the short version for people who have done this before.

Contents

1. Get a key
2. Connect your assistant
3. Check the connection
4. Build an app
5. What the assistant does
6. Change it and ship it
7. Free plan limits
8. When something goes wrong
9. Contribute

1. Get a key

1. Create a free Supero account. No card.
2. In the dashboard, open Build via MCP. It is on every project page and in the sidebar.
3. Create a key. There are two kinds:

The key starts with ak_ and is shown once. Copy it then. If you lose it, rotate it under API Keys to get a new one.

Treat the key like a password. Do not commit it, and do not paste it into an issue or an app folder.

2. Connect your assistant

The server is at https://api.supero.dev/mcp/v1/messages (streamable HTTP). Send the key in an X-API-Key header, raw, with no Bearer in front.

Claude Code

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

Then run /mcp inside Claude Code and check that supero is connected.

Cursor: ~/.cursor/mcp.json

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

VS Code (GitHub Copilot): .vscode/mcp.json

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

Run MCP: List Servers, start supero, and use Copilot in Agent mode.

Anything else. Any client that speaks MCP over streamable HTTP and lets you set a request header will work. More detail, and the one known gap (Claude Desktop's connector screen wants OAuth, which the server does not offer yet), is in docs/connect.md.

3. Check the connection

Ask your assistant:

Call build_whoami on Supero and tell me what it says.

You should get back your role, your domain and, for a project key, the project it is bound to. If you would rather check from a terminal:

curl -s https://api.supero.dev/mcp/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ak_..." \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"build_whoami","arguments":{}}}'

4. Build an app

Paste this, with your own description in the middle.

With a project key (the project already exists):

Connect to Supero over MCP and use your build_ tools. Everything runs through MCP: don't look for a local supero CLI or a SKILLS.md file on disk, there isn't one.

Build this app in my project: [describe your app: the main thing users do, the key screens, and an admin view].

Work in this order: build_whoami, then build_get_skills to load the spec, then build_plan. Echo the plan back to me and wait for my go-ahead. Then build_get_examples with the closest archetype as your reference, author the bundle, run build_validate and fix everything it reports, run build_doctor and fix its warnings, then build_publish and deploy (build_deploy for a ~30-minute preview, build_go_live for the permanent URL). Finally build_smoke_test the deployed URL and finish with a short summary: what you built, the URL, and how I log in.

With a domain key, change the second paragraph to:

Create a new project with build_create_project (pick a short name and namespace), then build this app in it: [describe your app].

Stuck for an idea? Every project brief ends with a prompt that is ready to paste.

If the assistant starts searching your disk for a CLI, send it this:

Stop reading the local filesystem. There is no CLI and no SKILLS.md. Call build_get_skills over MCP now, author the bundle, then build_validate.

More prompts, for changing an app, fixing a failed deploy and going live, are in docs/prompts.md.

5. What the assistant does

A deploy usually takes a few minutes and can sit in launching for five or more. That is normal: the assistant should keep polling build_deploy_status for up to ten minutes before deciding something is wrong.

The full walk-through is in docs/build-flow.md, and every tool is listed in docs/tools.md (64 tools; you can list them without a key).

What you do not have to build. Sign-in, roles and permissions, per-record and per-field access rules, the database, the REST API, the admin panel, and data kept apart between organisations in a multi-tenant app. There are also ready-made services to switch on instead of writing: bookings, appointments, rentals, cart, orders, payments, approvals, tasks, tickets, reviews, memberships, recurring plans, inventory, document signature, attachments, notifications, email and more. Ask the assistant to call build_list_capabilities to see them all.

6. Change it and ship it

• Change the app. Tell the assistant what to change. It fetches the current version with build_get_bundle, edits it, then validates, publishes and deploys again. The version number goes up each time.
• Preview or live. build_deploy gives a preview URL that lasts about 30 minutes, which is enough to click through and share. build_go_live gives a permanent address on supero.live and needs a paid plan.
• Secrets. Keys for email, SMS or payments go in the app's admin panel under Services. Never put one in the bundle.
• Dev and live mode. A project starts in dev mode. Switch it to live mode before real users arrive.

Free plan limits

These are the figures on the pricing page on 5 October 2026. That page is the authority if they differ. A plan and a validation pass cost nothing, so get build_validate clean before spending a preview. More in docs/limits.md.

When something goes wrong

Still stuck? Ask in Discussions. Found a way to make the server misbehave? See SECURITY.md and report it privately.

Contribute

There are four ways in, and none of them needs permission first. The open issues list good first ones, and we reply within a day.

• Publish an app. Build a brief, or your own idea, and add it with its source to community apps.
• Improve someone else's app. Deploy it into your own project, fix one of its known gaps, and send the change back.
• Write a brief for an app you wish existed. Copy projects/TEMPLATE.md.
• Improve this guide: a client we have not covered, a prompt that works better, an error we did not explain.

CONTRIBUTING.md has the details.

Related

• supero-apps: 19 complete reference apps with source and live demos.
• MCP documentation on docs.supero.dev, and a guide to the feature pages most useful while building.

Licence

Everything in this repo is MIT. An app you build is yours. The Supero platform itself is a hosted service and is not open source.