Early access

Apply

Documentation
Developers/MCP/Connect Gemini CLI

Connect Gemini CLI

Add Supero to Gemini CLI with httpUrl https://mcp.supero.dev/mcp in settings.json, run /mcp auth supero to sign in, and build Supero apps from the terminal.

  • Gemini CLI
  • MCP
  • OAuth
  • settings.json
  • /mcp auth

Overview

Gemini CLI connects to Supero's MCP server at https://mcp.supero.dev/mcp over Streamable HTTP and signs you in through your browser (OAuth). No API key is needed.

Tested

Checked end to end against Supero on 2026-11-13 with Gemini CLI's own sign-in: it requests every scope Supero lists and requires the iss check; both work.

Add the server

Add Supero to ~/.gemini/settings.json (or .gemini/settings.json in a project). Use httpUrl, not url: url means the older SSE transport.
json
{
  "mcpServers": {
    "supero": {
      "httpUrl": "https://mcp.supero.dev/mcp"
    }
  }
}
  1. 1

    Start Gemini CLI

    Run gemini. It reports that Supero needs authentication.

  2. 2

    Sign in

    Run /mcp auth supero. Your browser opens at Supero. Sign in, or create an account.

  3. 3

    Allow

    The approval page says "Supero hasn't verified this app", followed by the local address the tool uses (such as 127.0.0.1 or localhost). That is normal. Supero can't check a program on your computer, so it asks you to confirm you started the sign-in. Pick where it may work (access options). Click Allow.

  4. 4

    Use it

    Run /mcp to see the Supero tools, then ask Gemini to build an app.

Check the connection

Ask the assistant: "Use Supero and tell me who I am connected as." It calls build_whoami and answers with your workspace and access. Supero lists about 50 tools, with the build tools first.

Your first app

text
Build a booking app for a dog grooming salon: customers pick a groomer and a time slot and pay a deposit; staff see the day's appointments.

Use an API key instead (optional)

Only for CI pipelines, scripts, and machines without a browser. The tools are the same. Use https://api.supero.dev/mcp/v1/messages with the key in the X-API-Key header; Two addresses, one set of tools explains why there are two addresses, and Use an API key instead covers creating a key in the console (Build via MCP). A project key can read, change and delete records in every tenant of its project. Never commit a key.
json
{
  "mcpServers": {
    "supero": {
      "httpUrl": "https://api.supero.dev/mcp/v1/messages",
      "headers": { "X-API-Key": "$GEMINI_CLI_SUPERO_API_KEY" }
    }
  }
}
Set GEMINI_CLI_SUPERO_API_KEY in your environment; Gemini CLI expands it, so the key stays out of the file. Keep the GEMINI_CLI_ prefix: Gemini CLI blanks variables whose names contain words like KEY or TOKEN before expanding headers, and a name starting with GEMINI_CLI_ is exempt.

Troubleshooting

  • Use the URL exactly as https://mcp.supero.dev/mcp, with no trailing slash. Some clients compare it with the server's published resource and stop if they differ.
  • "Too many registrations" (HTTP 429). Each new sign-in registers the tool with Supero. One IP address may register 10 times an hour (an IPv6 /64 network 20 times), and there is an overall hourly limit. Wait, then try again. A sign-in that already works is not affected.
  • Signed in as the wrong account: remove the server, add it again, and use Switch account on the approval page.
  • To disconnect, use Disconnect at app.supero.dev/oauth/connections, then remove the server from the tool's config.
  • Changing your Supero password or email ends every assistant connection you signed in. Your projects and apps are not affected; sign in again from the tool.
  • Gemini CLI keeps your sign-in in ~/.gemini/mcp-oauth-tokens.json. If it expires, run /mcp auth supero again.