Orbit CPaaS — MCP Server

Stdio-based Model Context Protocol server that exposes the Orbit CPaaS API as first-class tools for any MCP client (Claude Desktop, Claude Code, Cursor, VS Code extensions, custom agent harnesses, …).

Docs: https://docs.orbit.devotel.io/guides/mcp-claude-cursor

Install

Most MCP clients launch the server on demand with npx, so no separate install step is needed — the per-client config blocks below do it for you. To install it explicitly:

npm install -g @devotel-orbit/mcp-server

The package installs a single orbit-mcp-server binary.

Related MCP server: armavita-quo-mcp

Quick start

ORBIT_API_KEY=dv_live_sk_xxxxxxxxxxxxxxxx npx @devotel-orbit/mcp-server

The process speaks JSON-RPC framing on stdio per the MCP spec. All logs go to stderr — never write to stdout from this server (it would corrupt MCP framing).

Claude Desktop setup

Add an entry to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "orbit": {
      "command": "npx",
      "args": ["-y", "@devotel-orbit/mcp-server"],
      "env": {
        "ORBIT_API_KEY": "dv_live_sk_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Restart Claude Desktop. The Orbit tools appear in the toolbox on the next conversation. Verify with: "List my Orbit campaigns."

Sandbox mode (no charges)

Use a test key (dv_test_sk_*) to exercise every tool against the sandbox without incurring real charges. Sandbox calls are logged in the Orbit dashboard under Settings → API Logs → sandbox.

Cursor setup

Click the badge above to install with one click (Cursor prompts you to confirm, then fill in your real ORBIT_API_KEY), or set it up manually. Open Cursor Settings → Features → MCP → Add new MCP server and set:

Alternatively, add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "orbit": {
      "command": "npx",
      "args": ["-y", "@devotel-orbit/mcp-server"],
      "env": {
        "ORBIT_API_KEY": "dv_live_sk_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Cursor automatically reloads MCP config on file save. Test with @orbit in any Cursor chat: "Using orbit, send an SMS to +14155551234 saying hello."

Claude Code (CLI)

export ORBIT_API_KEY=dv_live_sk_xxxxxxxxxxxxxxxx
claude mcp add orbit -- npx -y @devotel-orbit/mcp-server

Or add the block below to your project's .claude/settings.json / .mcp.json:

{
  "mcpServers": {
    "orbit": {
      "command": "npx",
      "args": ["-y", "@devotel-orbit/mcp-server"],
      "env": {
        "ORBIT_API_KEY": "dv_live_sk_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

VS Code (GitHub Copilot Chat / MCP extension)

Add to .vscode/mcp.json in your workspace (or User Settings → mcp.servers for a global install):

{
  "servers": {
    "orbit": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@devotel-orbit/mcp-server"],
      "env": {
        "ORBIT_API_KEY": "dv_live_sk_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Run MCP: List Servers → orbit → Start Server from the command palette, then invoke Orbit tools from Copilot Chat's agent mode.

Windsurf

Open Windsurf Settings → Cascade → MCP Servers → View raw config (or edit ~/.codeium/windsurf/mcp_config.json directly) and add:

{
  "mcpServers": {
    "orbit": {
      "command": "npx",
      "args": ["-y", "@devotel-orbit/mcp-server"],
      "env": {
        "ORBIT_API_KEY": "dv_live_sk_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Click Refresh in the MCP panel, then call Orbit tools from Cascade.

Cline (VS Code extension)

Open Cline → MCP Servers → Configure MCP Servers, which opens cline_mcp_settings.json, and add:

{
  "mcpServers": {
    "orbit": {
      "command": "npx",
      "args": ["-y", "@devotel-orbit/mcp-server"],
      "env": {
        "ORBIT_API_KEY": "dv_live_sk_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Cline reloads MCP servers automatically after the file is saved.

Zed

Add to your Zed settings.json (Zed → Settings → Open Settings):

{
  "context_servers": {
    "orbit": {
      "source": "custom",
      "command": {
        "path": "npx",
        "args": ["-y", "@devotel-orbit/mcp-server"],
        "env": {
          "ORBIT_API_KEY": "dv_live_sk_xxxxxxxxxxxxxxxx"
        }
      }
    }
  }
}

Orbit tools then appear in the Zed Assistant panel's context-server picker.

Continue

Add a block to ~/.continue/config.json (or the workspace .continue/config.json):

{
  "mcpServers": {
    "orbit": {
      "command": "npx",
      "args": ["-y", "@devotel-orbit/mcp-server"],
      "env": {
        "ORBIT_API_KEY": "dv_live_sk_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Reload the Continue window (Cmd/Ctrl+Shift+P → Continue: Reload) to pick up the new server.

Configuration

Auth header

The Orbit REST API authenticates MCP traffic via the X-API-Key header. You can also pass a Devotel API key as Authorization: Bearer …: since DC-UNCOVERED_SURFACES-01 (2026-06-01) Bearer tokens that carry a Devotel key prefix (dv_live_sk_, dv_test_sk_, dv_live_pk_, dv_test_pk_) are accepted as API keys. Only a non-Devotel Bearer token falls through to Clerk session-JWT verification and is rejected with 401 when no Clerk cookie is present (verified at packages/auth/src/middleware.ts ~880-994).

The MCP server attaches X-API-Key automatically. A boot-time ping validates the key and surfaces a clear error to stderr:

[MCP] ORBIT_API_KEY rejected by API; check key format
      (should start with dv_live_sk_ or dv_test_sk_).

Generate a key at Orbit Dashboard → Settings → API Keys.

Idempotency (LLM retry semantics)

Every chargeable POST tool attaches a deterministic Idempotency-Key header derived from (toolName, args, sessionId). callId is intentionally excluded from the key: it advances on every tools/call request (including network retries), so folding it in would produce a fresh key on each retry, defeat the 24h idempotency cache, and double-charge. callId is retained only as an audit-trace breadcrumb. When an LLM retries a tool call after a network blip with the same arguments the Orbit API replays its 24h Redis-cached response — operators see one message / purchase / campaign-start, never a duplicate.

Key shape: mcp_<toolName>_<32 hex chars> (well under the 255-char API cap).

Per-tool budget guard

Set MCP_TOOLS_BUDGET_LIMIT_USD=10 to refuse chargeable calls whose pessimistic estimated cost would exceed $10 in a single MCP session. Advisory bonus on top of the API's own per-tenant spend caps.

Per-tool allow / deny lists

# Read-only mode — no chargeable tools.
MCP_TOOLS_ALLOW_LIST=lookup_contact,list_campaigns,kb_query,list_segments,list_templates,get_message_status,search_numbers,check_balance,list_agents,analytics_summary

# Block high-impact tools.
MCP_TOOLS_DENY_LIST=purchase_number,start_campaign,voice_call

Disabled tools are NOT advertised in the tools/list response — the LLM never sees them as available primitives.

Docs-MCP tools (no Orbit account required)

Three tools are pure documentation lookups (plus one live, unauthenticated fetch) — they work even with no ORBIT_API_KEY set, so an agent can look up the real endpoint for a channel, get a copy-pasteable quickstart, or check current pricing before a developer has signed up for Orbit at all:

See src/docs-tools.ts for the full design note (grounding + SSRF-safety rationale for get_pricing's fetch).

Tools (47 total)

44 API / documentation tools are listed below; the remaining 3 are the host-model reasoning tools in the next section. Listed in registration order (see src/index.ts). The Chargeable column reflects membership of the CHARGEABLE_TOOLS set — those calls flow through the Idempotency-Key + audit + budget-guard path.

* Charges accrue per-message at fan-out time, not at invocation. The budget guard treats them as zero-cost; the audit log still records every invocation.

Host-model reasoning (MCP sampling)

Three tools don't call the Orbit API at all — they reason over free text by asking the connected host to run an LLM completion on the server's behalf (sampling/createMessage). The completion runs on the host's model, so no separate Orbit inference key or spend is involved, and the host stays in control of model choice and human approval. They return generated text only — never send or spend — so they are neither chargeable nor high-risk.

Requires a host that advertises the sampling capability (Claude Desktop, Claude Code, Cursor, or your own agent). When it's absent, each tool returns a clear message saying so rather than failing silently.

Interactive app cards (Apps SDK)

In an Apps-SDK host (ChatGPT, Claude), three tools render as interactive cards instead of plain text. The server advertises the resources capability and serves each card as a ui://widget/*.html template that the host mounts and hydrates with the tool's structuredContent:

Each button is confirm-to-act and routes back through the existing tool, so the idempotency, audit, and budget guarantees are unchanged. The card templates are self-contained (no outbound network) and hidden when the producing tool is denied via the allow/deny lists. Clients that don't support generative UI receive the same JSON text content and ignore the extra metadata.

Audit log

Every chargeable tool call emits a JSON-Lines audit entry to stderr:

{
  "ts": "2026-05-20T14:33:21.402Z",
  "level": "audit",
  "component": "orbit-mcp",
  "event": "tool.chargeable.invoked",
  "tool": "voice_call",
  "session_id": "mcp_session_94821_1715353101204",
  "call_id": "call_3",
  "args": { "to": "+14155551234", "record": true }
}

Pipe stderr to your structured-log sink to retain a full trace. The API key is never logged.

Local development

pnpm --filter @devotel-orbit/mcp-server dev        # tsx watch src/index.ts
pnpm --filter @devotel-orbit/mcp-server test       # vitest run
pnpm --filter @devotel-orbit/mcp-server type-check # tsc --noEmit

License

MIT. See LICENSE.