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/mcp-server@0.1.13.

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/mcp-server@0.1.13"],
      "env": {
        "ORBITER_SERVER_URL": "https://api.orbiterdev.ai"
      }
    }
  }
}

Cursor / Windsurf (MCP settings):

{
  "orbiter-dev": {
    "command": "npx",
    "args": ["-y", "@orbiterdev/mcp-server@0.1.13"],
    "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

Observability & Telemetry

Memory & Intelligence

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:

The public CLI starter path is npx -y @orbiterdev/mcp-server@0.1.13 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/mcp-server@0.1.13 codex setup --adapter http --server-url https://api.orbiterdev.ai --hook-profile full
npx -y @orbiterdev/mcp-server@0.1.13 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/mcp-server@0.1.13 antigravity setup --adapter http --server-url https://api.orbiterdev.ai --profile blocking --fallback deny
npx -y @orbiterdev/mcp-server@0.1.13 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/mcp-server@0.1.13 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/mcp-server@0.1.13 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:

npx -y @orbiterdev/mcp-server@0.1.13 gemini setup --adapter http --server-url https://api.orbiterdev.ai --profile guarded
npx -y @orbiterdev/mcp-server@0.1.13 gemini doctor

For local testing, pass the workspace explicitly:

npx -y @orbiterdev/mcp-server@0.1.13 gemini setup --workspace <workspace> --adapter http --server-url <backend-url> --profile guarded --approval-timeout 300
npx -y @orbiterdev/mcp-server@0.1.13 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/mcp-server@0.1.13 codex setup --offline-capture --capture-dir .tmp_hook_captures --adapter mock --mock-decision approved
npx -y @orbiterdev/mcp-server@0.1.13 antigravity setup --offline-capture --capture-dir .tmp_hook_captures --adapter mock --mock-decision approved
npx -y @orbiterdev/mcp-server@0.1.13 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

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.