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".
https://mcp.theorbits.app/mcpWhat 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
- Add the link to your AI app (the steps for each app are below).
- The app opens your browser at the web app's Connect page. Sign in if you need to.
- Choose the team, the access and when it expires, then press Allow.
- 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.
- In Claude, open Settings › Connectors and choose Add custom connector.
- Name it Orbits and paste
https://mcp.theorbits.app/mcp. - Choose Add, then Connect, and allow access on the Orbits page that opens.
Id: chatgpt.
- In ChatGPT, open Settings › Connectors › Advanced and turn on developer mode.
- Choose Create, name it Orbits, and paste
https://mcp.theorbits.app/mcp. - Choose OAuth for authentication, then Create, and allow access on the Orbits page that opens.
Id: claude-code.
$ claude mcp add --transport http --scope user orbits https://mcp.theorbits.app/mcpThen run /mcp inside Claude Code, choose orbits and sign in. Allow access on the Orbits page that opens.
Id: cursor. Add Orbits to ~/.cursor/mcp.json:
{
"mcpServers": {
"orbits": { "url": "https://mcp.theorbits.app/mcp" }
}
}Then, in Cursor's MCP settings, choose Connect next to orbits and allow access on the Orbits page that opens.
Id: vscode.
$ code --add-mcp '{"name":"orbits","type":"http","url":"https://mcp.theorbits.app/mcp"}'Start the orbits server when VS Code asks, and allow access on the Orbits page that opens.
Id: windsurf.
{
"mcpServers": {
"orbits": { "serverUrl": "https://mcp.theorbits.app/mcp" }
}
}Refresh Windsurf's MCP servers and allow access on the Orbits page that opens.
Id: codex.
[mcp_servers.orbits]
url = "https://mcp.theorbits.app/mcp"Then sign in, and allow access on the Orbits page that opens:
$ codex mcp login orbitsId: gemini.
$ gemini mcp add --scope user --transport http orbits https://mcp.theorbits.app/mcpOr add it to ~/.gemini/settings.json yourself. Gemini CLI finds the sign-in on its own: allow access on the Orbits page that opens.
{
"mcpServers": {
"orbits": { "httpUrl": "https://mcp.theorbits.app/mcp" }
}
}Id: grok. For the xAI API.
Grok doesn't sign in in a browser: it uses the xAI API's remote MCP tool, and sends an Orbits API token that you make under Team › Settings › API tokens. Make it read only unless Grok needs to make changes. Add Orbits to the tools of your xAI API request:
{
"tools": [
{
"type": "mcp",
"server_url": "https://mcp.theorbits.app/mcp",
"server_label": "orbits",
"authorization": "Bearer orb_live_…"
}
]
}Read the token from an environment variable or a secret store when you build the request. Never paste it into a prompt or your code.
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.
$ 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 OrbitsFor 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:
$ orbits-mcp stdioIt looks for a token in this order:
- The
ORBITS_TOKENenvironment variable. - The token the Orbits CLI stored when you ran
orbits login, from your system's keychain or the CLI'scredentials.json. SetORBITS_PROFILEto pick a profile (andORBITS_CONFIG_DIRif the CLI's settings are somewhere else).
| Variable | What it does |
|---|---|
ORBITS_TOKEN | The API token. Default: the Orbits CLI's sign-in |
ORBITS_PROFILE | The CLI profile to read. Default: the CLI's current one |
ORBITS_API_URL | The API. Default https://api.theorbits.app/v1, or the API the CLI profile signed in on. --api-url does the same |
ORBITS_TEAM | The default team's slug. Default: the CLI profile's team, else the token's own team. --team does the same |
MCP_DISABLE_REVEAL | true 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:
$ orbits mcp install claude-code --localThat 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:
{
"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:
[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.