Use Orbit from your AI coding agent (MCP)

1 · One-click connect (OAuth — recommended)

Clients that support MCP OAuth need only the URL — no key to mint or paste: https://api.optimaorbit.com/api/v1/ext/mcp

1. Settings → Connectors → Add custom connector → paste the URL above → Add.
2. Click Connect — your browser opens Orbit's authorization page. Sign in if asked.
3. Review the requested scopes (untick anything you don't want to grant) and click Authorize.

Copyclaude mcp add orbit --transport http https://api.optimaorbit.com/api/v1/ext/mcp

Then run /mcp → orbit → Authenticate; the same browser consent page opens. Other OAuth-capable MCP clients work the same way — add the URL with no headers and the client discovers the rest.

Authorizing requires the Orbit permission org.developer.apikeys.manage — the same privilege as minting an API key by hand. Each approved connection appears in Developer → API Keys as a revocable key; revoke it there to disconnect the app instantly. Tokens expire and refresh automatically.

2 · Or: get an API key (for clients without OAuth)

1. In your Orbit workspace, open Developer → API Keys and create a key for the module you need (Orbit Ops for tasks, Orbit Resolve for tickets, Orbit Books for invoices and ledger, …).
2. Pin it to a project if you can — your agent then never has to pass project_id, and cannot touch any other project.
3. Grant scopes deliberately: the agent's tool list is derived from the key's scopes. A key with only read scopes produces a read-only assistant; write tools don't even appear.

3 · Connect your editor with the key

The MCP endpoint (this environment): https://api.optimaorbit.com/api/v1/ext/mcp

Copyclaude mcp add orbit --transport http https://api.optimaorbit.com/api/v1/ext/mcp \
  --header "Authorization: Bearer orb_live_YOUR_KEY"

Cursor: ~/.cursor/mcp.json (global) or .cursor/mcp.json (project) — or Settings → MCP → Add custom MCP. Reload the server from that panel after editing.

Copy{
  "mcpServers": {
    "orbit": {
      "url": "https://api.optimaorbit.com/api/v1/ext/mcp",
      "headers": { "Authorization": "Bearer orb_live_YOUR_KEY" }
    }
  }
}

Windsurf uses ~/.codeium/windsurf/mcp_config.json and, like Antigravity below, expects serverUrl instead of url.

Copy{
  "servers": {
    "orbit": {
      "type": "http",
      "url": "https://api.optimaorbit.com/api/v1/ext/mcp",
      "headers": { "Authorization": "Bearer orb_live_YOUR_KEY" }
    }
  }
}

Save as .vscode/mcp.json in your workspace.

Copy{
  "mcpServers": {
    "orbit": {
      "serverUrl": "https://api.optimaorbit.com/api/v1/ext/mcp",
      "headers": { "Authorization": "Bearer orb_live_YOUR_KEY" }
    }
  }
}

Global: ~/.gemini/config/mcp_config.json · per-workspace: .agents/mcp_config.json. Antigravity rejects the legacy url / httpUrl keys — a config copied from the Cursor snippet above will silently fail to connect there.

Do I need to register Orbit in an MCP directory?

No. Public registries (mcpfind, Smithery, the official MCP registry) are optional discovery catalogues — clients never consult them to connect. A client connects with the URL alone (OAuth) or the URL + key header from the config file above, nothing else. Likewise, MCP servers are added by editing config / using the editor's MCP settings panel — not by asking the AI in chat to “connect to an MCP server”; asked that way, agents tend to go searching public directories and come back empty-handed.

4 · Talk to it

Try, in your agent's chat:

“Create a task ‘Fix login redirect’, priority High, assign it to Priya” “What are my open P1 tickets?” “Log a lead for ACME Corp from today's call” “Move OO-42 to In Progress and comment with the PR link”

Agents automatically call the lookup tools first (statuses, priorities, members, pipelines…) and only use ids those return — the same “read the lookups, then write” contract as the REST API.

How it maps

REST concept	MCP equivalent
Endpoint (e.g. POST /ext/task/tasks)	Tool (e.g. create_task) — generated from the same OpenAPI spec, so they can never disagree
Scopes on the key	Which tools exist in the agent's list (+ re-checked on every call)
Project-scoped key	Agent never passes project_id; org-wide keys pass it per call (list_projects first)
Rate limits · IP allowlist · request logs	Identical — MCP calls are ordinary keyed API calls in Developer → API Keys → Logs
OAuth connection (claude.ai, Claude Code…)	An auto-minted key in Developer → API Keys, scoped to exactly what was authorized — revoke it to disconnect the app
Errors	The same error envelope, surfaced to the agent so it can self-correct

Modules covered: Orbit Ops (tasks) · Orbit Resolve (service desk) · Orbit Pulse (CRM) · Orbit Schedule · Orbit Papers · Orbit Inventory · Orbit Storefront · Orbit People (HR, read-only) · Orbit Books (accounting). Full per-endpoint detail lives in the API reference.

Smoke test with curl

Copycurl -s https://api.optimaorbit.com/api/v1/ext/mcp \
  -H "Authorization: Bearer orb_test_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Returns the tools your key's scopes allow. Security notes: keys are shown once at creation, can be rolled/revoked instantly, and MCP honours per-key IP allowlists — treat the key like a password and prefer orb_test_… keys while experimenting.