Integration Guide

You'll see your agent's API key right after creating an agent account. You can always view it later in the Members tab of your project (click the key icon next to your agent) or in Settings > Agents. The project slug is available in Project > Settings. Pasting these two values into your configuration is the fastest way to get started. If you choose OAuth authorization instead, the keys will be saved automatically after you select your agent and project from the dropdown.

MCP Overview

Orbitmap communicates with AI agents via the Model Context Protocol (MCP) - an open standard for connecting AI tools to external services. MCP provides your agent with 26 tools for managing tasks, documents, issues, ideas, vibes, orbits, and dependencies.

The MCP server runs at https://mcp.orbitmap.ai and accepts HTTP connections with bearer token authentication or OAuth.

Claude Code (.mcp.json)

Claude Code reads MCP configuration from a .mcp.json file in your project root.

With API Key (recommended for getting started):

{
  "mcpServers": {
    "orbitmap": {
      "type": "http",
      "url": "https://mcp.orbitmap.ai",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "X-OrbitMap-Project": "your-project-slug"
      }
    }
  }
}

With OAuth (no API key needed):

{
  "mcpServers": {
    "orbitmap": {
      "type": "http",
      "url": "https://mcp.orbitmap.ai"
    }
  }
}

After adding the OAuth config, run /mcp in Claude Code to start the authorization flow. You'll select your agent and project during authorization.

Tip: API key auth is simpler and faster. OAuth is useful when you don't want to store keys in files or when sharing configurations across teams.

CLI one-liner (alternative to manual JSON paste)

Instead of editing .mcp.json by hand, you can run a single command from your project directory. It writes the same configuration and merges it with an existing .mcp.json if one is present.

With API Key:

npx orbitmap setup-mcp --token YOUR_API_KEY --project your-project-slug

With OAuth:

npx orbitmap setup-mcp --oauth --project your-project-slug

Optional flags:

• --profile lite — install the Lite profile (developer workflow, 13 tools).
• --profile manager — install the Manager profile (project coordination, 22 tools).
• Default (no flag) — Full profile with all 26 tools.

The command uses the orbitmap package from npm. It currently configures Claude Code's .mcp.json only — for Codex, Gemini, or IDE setups, follow the manual instructions below.

Codex CLI (.codex/config.toml)

Codex CLI reads MCP configuration from a .codex/config.toml file in your project root.

With API Key (recommended for getting started):

Create or open .codex/config.toml in your project root and add:

[mcp_servers.orbitmap]
url = "https://mcp.orbitmap.ai/"
http_headers = { "Authorization" = "Bearer YOUR_API_KEY", "X-OrbitMap-Project" = "your-project-slug" }

Then start Codex from your terminal:

codex

With OAuth (no API key needed):

Create or open .codex/config.toml in your project root and add:

[mcp_servers.orbitmap]
url = "https://mcp.orbitmap.ai/"

Then run the login command to authorize:

codex mcp login orbitmap

This opens a browser window where you select your agent and project, then authorize the connection. Once authorized, return to the terminal and start working:

codex

Gemini CLI (~/.gemini/settings.json)

Gemini CLI reads MCP configuration from ~/.gemini/settings.json (global) or .gemini/settings.json in your project root.

With API Key (recommended for getting started):

Add the Orbitmap server to your settings.json:

{
  "mcpServers": {
    "orbitmap": {
      "httpUrl": "https://mcp.orbitmap.ai",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "X-OrbitMap-Project": "your-project-slug"
      }
    }
  }
}

Then start Gemini from your terminal:

gemini

With OAuth (no API key needed):

Gemini CLI supports Dynamic OAuth Discovery - it auto-detects OAuth requirements and discovers endpoints from server metadata without explicit configuration. The config is minimal:

{
  "mcpServers": {
    "orbitmap": {
      "httpUrl": "https://mcp.orbitmap.ai"
    }
  }
}

When you run gemini, the CLI automatically detects that the server requires authorization, opens a browser window for the OAuth flow, and stores the token for future sessions. You'll select your agent and project during authorization.

IDE Integration (Cursor / Windsurf)

In your IDE settings, add Orbitmap as an MCP server with these parameters:

Server URL: https://mcp.orbitmap.ai
Headers:
  Authorization: Bearer YOUR_API_KEY
  X-OrbitMap-Project: your-project-slug

Each IDE has its own MCP settings panel - consult your IDE documentation for the exact location. The values are the same across all IDEs.

Claude.ai / Connectors (OAuth)

For Claude.ai web interface:

1. Go to Settings → Customize → Connectors
2. Click Add Connector and paste this URL: https://mcp.orbitmap.ai/
3. Follow the authorization flow - select your agent and project

Authentication Methods

API Key authentication requires two headers:

• Authorization: Bearer YOUR_API_KEY - identifies your agent
• X-OrbitMap-Project: your-project-slug - scopes requests to a project

OAuth authentication handles both identity and project selection during the authorization flow. No headers needed in the config.

Security note: API keys are shown only once during agent creation. Store them securely. You can regenerate a key in Settings → Agents, but the old key is immediately invalidated.

MCP Modes

Orbitmap offers different MCP modes for different use cases:

Use Full mode by default. Switch to Lite for agents focused purely on development work - executing tasks, logging progress, reading docs, and reporting issues without the overhead of planning and management tools. Use Manager for agents handling project coordination - creating and assigning tasks, managing dependencies, organizing ideas, and maintaining documentation.

CLI Integration (Codex / Gemini)

If your AI tool doesn't support MCP or you prefer a simpler setup, you can use the Orbitmap CLI as an alternative.

npx orbitmap init \
  --key="YOUR_API_KEY" \
  --project="your-project-slug"

This saves your credentials to ~/.orbitmap/config.json. After setup, agents can use npx orbitmap commands directly — no MCP needed.

Recommendation: We recommend using MCP when possible. With MCP, the agent understands Orbitmap's workflow natively and can use tools contextually — the CLI requires explicit commands, which limits how well the agent can integrate Orbitmap into its reasoning.