OrbitsDocs
esc
    Open Orbits
    AIConnect your AI

    Connect your AI app to Orbits

    Let Claude, ChatGPT, Cursor, VS Code and other AI apps deploy and look after your Orbits projects, with one link and your approval.

    Paste one link into your AI app, approve it in the Orbits web app, and you can ask things like "why did my last deployment fail?" or "add shop.example.com to the storefront project".

    text
    https://mcp.theorbits.app/mcp

    What MCP is

    MCP (the Model Context Protocol) is a standard way for an AI app to use outside tools. Orbits runs an MCP server at the link above. Your AI app connects to it and gets 48 Orbits tools: list projects, read a build log, deploy a branch, roll back production, set an environment variable, add a domain, read runtime logs, check usage, and so on. Every tool calls the Orbits API with an API token that only this app holds, with the access you approved. Nothing else is shared.

    Anything that deletes something, changes what production serves, changes a domain or DNS record, or shows a secret value asks you first.

    How connecting works

    1. Add the link to your AI app (the steps for each app are below).
    2. The app opens your browser at the web app's Connect page. Sign in if you need to.
    3. Choose the team, the access and when it expires, then press Allow.
    4. Go back to your AI app. It is connected.

    You need to be an owner or admin of the team, because only they can create API tokens. If you aren't one in any team, the page says so.

    What the approval page asks

    • Team. If you own or administer more than one, pick the one this app may use. One connection works in one team.
    • Access.
      • Full access: deploy, change settings and domains. This is the default, unless the app asked only to read.
      • Read only: see projects, deployments and logs, and change nothing. Good for questions about status, errors and usage.
    • Expires. In 30 days, in 90 days or in a year. There is no "never" for an AI app. When it expires, the app asks you to approve it again.

    The page shows the app's name with the label Not verified by Orbits. Any app can call itself anything, so check the name and the address it will send you back to before you press Allow. What the label means.

    Allowing creates an API token named after the app, like Claude-Code-MCP, in the team's Settings › API tokens. The page never shows it: it goes straight to the app. Revoke it there to disconnect the app.

    Set up your app

    The id in each tab is the one orbits mcp install takes. See Use the CLI to set it up.

    For claude.ai and Claude Desktop. Id: claude.

    1. In Claude, open Settings › Connectors and choose Add custom connector.
    2. Name it Orbits and paste https://mcp.theorbits.app/mcp.
    3. Choose Add, then Connect, and allow access on the Orbits page that opens.

    Apps that can't sign in

    Any app that can't sign in with OAuth can do what Grok does: send an API token from Team › Settings › API tokens as Authorization: Bearer orb_live_… to https://mcp.theorbits.app/mcp. A read token is a good start.

    Use the CLI to set it up

    The Orbits CLI can write the config for you. It keeps every other server and setting in the app's file and saves the old file as <file>.bak. For Claude Code and Gemini CLI it runs their own mcp add command (user scope) when they are installed.

    Terminal
    $ orbits mcp install cursor$ orbits mcp install vscode --print   # show the config, change nothing$ orbits mcp list-clients             # the ids it knows$ orbits mcp status                   # the link, whether orbits-mcp is installed, and which apps have Orbits

    For claude it prints the connector steps above. For chatgpt and grok it prints instructions only, since their setup lives in the app or your request. --url points it at another hosted server.

    Run it locally

    You can also run the MCP server on your own computer. It is a program called orbits-mcp. In this mode there is no browser approval: it uses a token you already have. Only the local server can deploy a folder from your computer (deploy_folder).

    Install it one of these ways:

    • Download an archive for macOS, Linux or Windows (amd64 or arm64) from the releases page, and check it against SHA256SUMS:

      Terminal
      $ shasum -a 256 -c SHA256SUMS --ignore-missing
    • With Go 1.26 or later:

      Terminal
      $ go install github.com/The-Orbits/orbits-mcp/cmd/orbits-mcp@latest
    • With Docker (linux/amd64 and linux/arm64):

      Terminal
      $ docker pull ghcr.io/the-orbits/orbits-mcp:latest

    Then run it:

    Terminal
    $ orbits-mcp stdio

    It looks for a token in this order:

    1. The ORBITS_TOKEN environment variable.
    2. The token the Orbits CLI stored when you ran orbits login, from your system's keychain or the CLI's credentials.json. Set ORBITS_PROFILE to pick a profile (and ORBITS_CONFIG_DIR if the CLI's settings are somewhere else).
    VariableWhat it does
    ORBITS_TOKENThe API token. Default: the Orbits CLI's sign-in
    ORBITS_PROFILEThe CLI profile to read. Default: the CLI's current one
    ORBITS_API_URLThe API. Default https://api.theorbits.app/v1, or the API the CLI profile signed in on. --api-url does the same
    ORBITS_TEAMThe default team's slug. Default: the CLI profile's team, else the token's own team. --team does the same
    MCP_DISABLE_REVEALtrue leaves out reveal_env_var, so no value can be read back

    The server refuses a CLI config or credentials file that other users can write, and an API address that isn't https (or localhost). orbits-mcp help lists its commands.

    To point an app at the local server:

    Terminal
    $ orbits mcp install claude-code --local

    That runs claude mcp add --scope user orbits -- <path to orbits-mcp> stdio. The CLI writes the full path, because apps opened from the dock or Start menu may not see your shell's PATH; write the full path too if you edit a config by hand (find it with which orbits-mcp). The same flag works for claude (it writes Claude Desktop's claude_desktop_config.json), cursor, vscode, windsurf, codex and gemini. ChatGPT and Grok can only use the hosted server. By hand, the config is the same for most apps:

    claude_desktop_config.json
    {
      "mcpServers": {
        "orbits": { "command": "orbits-mcp", "args": ["stdio"] }
      }
    }

    Restart the app afterwards. For VS Code, run code --add-mcp '{"name":"orbits","type":"stdio","command":"orbits-mcp","args":["stdio"]}'. Codex takes:

    ~/.codex/config.toml
    [mcp_servers.orbits]
    command = "orbits-mcp"
    args = ["stdio"]

    If orbits-mcp is not on your PATH, orbits mcp install --local warns you and writes the config anyway, so install it before you restart the app.

    Was this page helpful?

    Updated