Orbiter Dev MCP Server

Approve, reject, and monitor AI agent actions from your phone. Stop babysitting your terminal. Stop YOLO-ing your codebase.

Overview

The Orbiter Dev MCP server integrates directly with Claude Code, Codex, Antigravity, Gemini CLI, and MCP-compatible agents such as Cursor and Windsurf. It intercepts risky actions — deploying to production, modifying databases, installing packages — and sends them to your phone for explicit approval with FaceID.

Stop bypassing safety by running --dangerously-skip-permissions. Use Orbiter Dev to auto-approve safe tasks via the Policy Engine, and securely gate destructive commands via your iOS device.

Android support coming soon.

Provider Status

Minimum npm package for the hook CLIs below: @orbiterdev/[email protected].

| Provider | Current status | Setup | Doctor | |---|---|---|---| | Codex | Live HTTP hook posting verified on 2026-06-17; iOS approve/reject round-trip is the final device evidence gate | npx -y @orbiterdev/[email protected] codex setup --adapter http --server-url https://api.orbiterdev.ai --hook-profile full | npx -y @orbiterdev/[email protected] codex doctor --check-backend | | Antigravity | Live HTTP PreToolUse posting verified on 2026-06-17; run setup per workspace/worktree; iOS approve/reject is the final device evidence gate | npx -y @orbiterdev/[email protected] antigravity setup --workspace <workspace> --adapter http --server-url https://api.orbiterdev.ai --profile blocking --fallback deny --approval-timeout 300 --configure-native-command-policy | npx -y @orbiterdev/[email protected] antigravity doctor --workspace <workspace> --check-backend | | Claude Code | Local bridge hooks posted production approval rows on 2026-06-17; npm package exposes MCP tools and permission-check, while the full bridge hook pack remains beta; iOS approve/reject is still manual evidence | npx -y @orbiterdev/[email protected] permission-check | Verify MCP config plus one controlled permission request | | Gemini CLI | Fixture-proven beta hook path; complete a live Gemini CLI approve/reject field test before making production claims | npx -y @orbiterdev/[email protected] gemini setup --adapter http --server-url https://api.orbiterdev.ai --profile guarded | npx -y @orbiterdev/[email protected] gemini doctor --check-backend |

Installation

We recommend using npx so your agents always pull the latest hardened release.

Prerequisites: Node.js 18+

Configuration

Add the following to your MCP configuration file:

Claude Code (~/.claude.json):

{
  "mcpServers": {
    "orbiter-dev": {
      "command": "npx",
      "args": ["-y", "@orbiterdev/[email protected]"],
      "env": {
        "ORBITER_SERVER_URL": "https://api.orbiterdev.ai"
      }
    }
  }
}

Cursor / Windsurf (MCP settings):

{
  "orbiter-dev": {
    "command": "npx",
    "args": ["-y", "@orbiterdev/[email protected]"],
    "env": {
      "ORBITER_SERVER_URL": "https://api.orbiterdev.ai"
    }
  }
}

How It Works

1. Agent Signals — Your AI attempts a risky sequence (deploy, delete, push).
2. Intercept — The Orbiter MCP server pauses the agent and sends a summary to your phone.
3. Approve — You review the risk level on the Orbiter mobile app. Tap "Approve" (with FaceID for critical actions). Choose scope: Allow Globally, Allow Once, or Allow in Workspace.
4. Resume — The agent picks up exactly where it left off. No context lost.

Tools Exposed to Agents

The server exposes the following tools to the AI agent via MCP:

Approval & Governance

| Tool | Description | |------|-------------| | request_approval | Pauses the agent, sends a push notification with action plan and risk analysis, waits for explicit human approval | | orbiter_auth | Pair the IDE workspace to your Orbiter mobile app using a short-lived pairing code | | orbiter_auth_verify | Verify that pairing was completed on the mobile device | | kill_agent | Immediately terminate a hung or dangerous agent session |

Observability & Telemetry

| Tool | Description | |------|-------------| | agent_heartbeat | Report agent state (working/idle/waiting/error) — powers the live HUD on your phone | | checkpoint_post | Log structured progress milestones — shown as a visual timeline on mobile | | report_tool_result | Report tool execution outcomes for loop detection (stuck-agent alerts) | | context_health | Report context window usage — triggers compaction warnings at 80%+ | | report_usage | Track token consumption and cost per session | | notify_user | Send ad-hoc push notifications (build complete, tests passed, etc.) |

Memory & Intelligence

| Tool | Description | |------|-------------| | session_memory | Save session snapshots for cross-session continuity | | get_project_instincts | Retrieve learned project patterns (bug avoidance, architecture rules) | | add_project_instinct | Save new learnings for future agent sessions |

Device Pairing

Agents can securely pair your local IDE workspace to the Orbiter Dev mobile app using short-lived pairing codes, eliminating the need to store static tokens in plain text.

Agent → orbiter_auth → Backend generates pairing code → User enters on phone → Verified

CLI Commands

Push Notifications

Send background push updates when your agent completes long-running processes:

export ORBITER_TOKEN="your-app-token"
npx @orbiterdev/mcp-server notify --event "Test Suite" --message "Tests passed successfully"

Permission Check (Hook Mode)

Route Claude Code permission checks through Orbiter for mobile approval:

npx @orbiterdev/mcp-server permission-check --command "npm publish" --risk high

Claude Code Hooks

Claude Code hooks are recommended when Claude Code is the agent surface. The MCP server exposes Orbiter tools; hooks add deterministic lifecycle capture.

The tested beta hook pack currently covers:

| Hook | Purpose | |------|---------| | PermissionRequest | Route native Bash permission requests to Orbiter approval | | PreToolUse | Check risky commands before execution | | PostToolUse | Report completed tool activity | | Notification | Forward permission, idle, auth, and elicitation notifications | | TaskCompleted | Notify when a Claude task finishes | | SessionStart | Mark session start and heartbeat state | | SessionEnd | Mark session shutdown and final heartbeat state |

The public CLI starter path is npx -y @orbiterdev/[email protected] permission-check. The full beta bridge hook pack is source-checkout only for now and is not included in the npm tarball.

Codex Hooks

Codex uses workspace-scoped hook trust. After running codex setup, Codex may show a new-chat banner such as "hooks need review before they can run"; users can review the same hooks later under Settings -> Hooks. Trust and enable each workspace separately, because Codex stores hook trust per project and re-prompts when the managed hook command changes.

Orbiter's Codex setup writes the current Codex feature flag:

[features]
hooks = true # orbiter-dev-codex

If Codex shows a warning that [features].codex_hooks is deprecated, update your Codex config.toml to use [features] hooks = true instead. Older Orbiter hook behavior should continue after the key is renamed. If hooks still do not fire, restart Codex, confirm the workspace is trusted, then run the Orbiter hook verification command for your IDE/CLI.

npx -y @orbiterdev/[email protected] codex setup --adapter http --server-url https://api.orbiterdev.ai --hook-profile full
npx -y @orbiterdev/[email protected] codex doctor

Recommended order:

1. Install hooks with codex setup.
2. In Codex, open the workspace and review the hook banner or go to Settings -> Hooks -> workspace.
3. Pair Codex with Orbiter using orbiter_auth; Codex uses its own credential profile, separate from Antigravity and generic MCP pairings.
4. Trust and enable the workspace hooks.
5. Road-test a real PermissionRequest and approve it from iOS.

For backend-free regression testing, use offline capture mode or clone the repository and run the fixture tests locally. Public npm installs do not include repository fixtures.

Antigravity 2.0 Hooks

Antigravity 2.0 uses a native project hook architecture rather than the legacy VS Code extension flow. Orbiter installs a workspace-scoped .agents/hooks.json entry that routes Antigravity PreToolUse events through Orbiter before risky tools run.

The default setup is fail-closed and deterministic: approved actions return allow, rejected actions return deny, and timeout/pending/malformed inputs return deny unless --fallback force_ask is explicitly configured.

npx -y @orbiterdev/[email protected] antigravity setup --adapter http --server-url https://api.orbiterdev.ai --profile blocking --fallback deny
npx -y @orbiterdev/[email protected] antigravity doctor

For local desktop AGY testing, always pass the workspace explicitly. Doctor verifies the managed hook block, hook runner, mock PreToolUse round trip, and AGY native command policy:

npx -y @orbiterdev/[email protected] antigravity doctor --workspace <workspace> --adapter http --server-url <backend-url> --profile blocking --fallback deny --approval-timeout 300

The real AGY desktop approve/continue path requires:

native_terminal_policy_allows_orbiter_gate=true

If this check fails and Orbiter hooks are trusted/enabled, rerun setup with:

npx -y @orbiterdev/[email protected] antigravity setup --workspace <workspace> --adapter http --server-url <backend-url> --profile blocking --fallback deny --approval-timeout 300 --configure-native-command-policy

This sets the matching AGY project command policy to allow continuation after Orbiter approves. Restore AGY Request Review if hooks are disabled, untrusted, or doctor fails.

For backend-free regression testing, use offline capture mode or clone the repository and run the fixture tests locally. Public npm installs do not include repository fixtures.

Gemini CLI Hooks

Gemini CLI uses a separate native hook/config surface from Antigravity. Orbiter's local beta setup writes workspace-scoped .gemini/settings.json entries for Gemini CLI hooks and an mcpServers.orbiter-dev entry. This path is fixture-proven locally; run a live Gemini CLI approve/reject field test before using public support copy.

The guarded profile installs:

| Hook | Purpose | |------|---------| | BeforeTool | Route high-risk Gemini CLI tool calls through Orbiter mobile approval | | AfterTool | Observe completed tool activity for future telemetry | | Notification | Observe Gemini CLI system notifications | | SessionStart | Mark session startup context |

npx -y @orbiterdev/[email protected] gemini setup --adapter http --server-url https://api.orbiterdev.ai --profile guarded
npx -y @orbiterdev/[email protected] gemini doctor

For local testing, pass the workspace explicitly:

npx -y @orbiterdev/[email protected] gemini setup --workspace <workspace> --adapter http --server-url <backend-url> --profile guarded --approval-timeout 300
npx -y @orbiterdev/[email protected] gemini doctor --workspace <workspace> --adapter http --server-url <backend-url>

For backend-free regression testing, use offline capture mode or clone the repository and run the fixture tests locally. Public npm installs do not include repository fixtures.

Offline Hook Capture

Use offline capture when you need real IDE hook payloads without calling the live backend or writing to the live database:

npx -y @orbiterdev/[email protected] codex setup --offline-capture --capture-dir .tmp_hook_captures --adapter mock --mock-decision approved
npx -y @orbiterdev/[email protected] antigravity setup --offline-capture --capture-dir .tmp_hook_captures --adapter mock --mock-decision approved
npx -y @orbiterdev/[email protected] gemini setup --offline-capture --capture-dir .tmp_hook_captures --adapter mock --mock-decision approved

doctor reports backendMode as offline-capture, mock, file, or live-http. Offline capture receipts are written under <capture-dir>/<provider>/<event>/ with redacted payloads and "backend_used": false. Public setup guidance lives at https://orbiterdev.ai/docs and https://orbiterdev.ai/setup; repository-only fixture guides are intentionally not bundled in the npm package.

If iOS Shows No Approvals

Run checks in this order:

1. Confirm the hook mode is live-http, not offline-capture, mock, or file.
2. Confirm the generated hook command includes --server-url https://api.orbiterdev.ai.
3. Run the provider doctor command with --check-backend.
4. Confirm the IDE/MCP profile is paired with the same account used in the iOS app. A split profile can make the backend row real while the App Store app correctly lists zero rows for the signed-in user.
5. Foreground Orbiter Dev iOS and pull to refresh the approval list.
6. Remember that APNs only affects notification delivery; a healthy REST refresh should still show pending backend approvals.

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | ORBITER_SERVER_URL | https://api.orbiterdev.ai | Backend API URL | | ORBITER_TOKEN | — | Auth token (auto-managed after pairing) | | ORBITER_CREDENTIAL_PROFILE | — | Optional per-client credential slot, for example codex or gemini-cli | | ORBITER_CREDENTIAL_PATH | — | Optional explicit credential file path; overrides profile resolution |

Security

• All traffic encrypted via TLS
• FaceID/biometric gating for high-risk approvals
• Approval payloads use redacted previews and input hashes where hooks support them
• Short-lived pairing codes (expire in 5 minutes)
• JWT authentication with 15-minute token rotation

Website • Documentation • Privacy • Terms • Support

© 2026 Orbiter Dev. MIT License.