We're looking for beta testers.

API reference

MCP

Connect AI assistants to your Orbimon data with a read-only MCP server.

Orbimon exposes a read-only Model Context Protocol server on the API host so you can connect AI assistants (Cursor, Claude Desktop, Grok Bot, and other MCP clients) to your organization’s monitor data.

Endpoint

EnvironmentURL
Productionhttps://api.orbimon.com/mcp
API preview (PR branches)https://api-<branch>.preview.orbimon.com/mcp

POST carries JSON-RPC (Streamable HTTP, stateless). GET and DELETE return 405 in stateless mode.

Authentication

MCP uses the same user or service API tokens as the Orbimon REST API. No dashboard login or browser session is involved — the client sends the token on every request.

Authorization: Bearer omb_user_…

or

Authorization: Bearer omb_svc_…

Requirements:

  • Token must include the read scope (user tokens include read and write by default; service tokens may be read-only or read/write; MCP never exposes write tools).
  • User tokens (omb_user_…) and service tokens (omb_svc_…) with read scope are accepted. Monitor (omb_mon_…) tokens are rejected with 401.
  • Service tokens are scoped to the organization that created them; MCP tools never return another organization’s data.
  • Revoked or unknown tokens receive 401 with WWW-Authenticate: Bearer.

Create a user token in the dashboard (Settings → Account → API token). Owners and admins create service tokens on the Organization page.

Connect in Cursor

  1. Put your omb_user_… or read-scope omb_svc_… token in the MCP server headers (never commit it to git).
  2. Open Cursor Settings → MCP and add a server:
{
  "mcpServers": {
    "orbimon": {
      "url": "https://api.orbimon.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

Use your preview API URL when testing a branch deployment.

Connect in Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "orbimon": {
      "url": "https://api.orbimon.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

Tools (read-only)

All tools are annotated with readOnlyHint: true.

ToolDescription
list_monitorsMonitors in your org (id, name, type, status, last seen, location)
get_monitor_statusCurrent status and latest metrics
get_metrics_historyCompact chart series (≤150 points) with per-metric summary for a time range
list_events_and_outagesDish events and outages (optional monitor)
list_speed_testsSpeed tests (optional monitor)
list_alertsAlert settings and profiles (webhook_secret_set booleans only; never signing secrets)
list_alert_incidentsAlert-engine incidents for a range
get_organizationOrg name, plan, trial status, monitor count

Cross-organization monitor IDs return not found, same as the REST API.

get_metrics_history payload shape

Responses are sized for agent context (typically under ~20 KiB even for 7d):

  • series: at most 150 time buckets with rounded fields only — timestamp, state / connected, down_mbps, up_mbps, latency_ms, ping_drop_pct, power_w, obstruction_pct.
  • summary: uptime_pct plus avg/min/max bands for each metric over the returned series.
  • Raw per-bucket min/max columns from the dashboard chart API are omitted.

list_alerts and secrets

MCP alert tools mirror the REST masked alert views:

  • Org and profile webhook signing secrets are never returned.
  • Use webhook_secret_set (true / false) on org settings and on profiles with their own webhook channel.
  • No MCP tool returns API tokens, monitor tokens, or webhook header values.

Usage and limits

MCP traffic counts toward your organization’s monthly API request limit. The usage dashboard shows an MCP source next to Edge, API, and App.

Metering rules:

  • The HTTP /mcp transport records successful calls with counted: 0 for initialize, notifications/initialized, and tools/list (discovery is free).
  • Each tools/call enqueues additional usage rows with source: mcp, mapped to the same area as the underlying REST read (monitors, monitor data, alerts, and so on), with counted: 1 per equivalent read.

Security

  • Keep tokens secret. Rotate the user token from Settings → Account, or revoke and recreate service tokens on the Organization page if exposed.
  • MCP is intended for server-side clients; do not expose tokens in browser extensions.
  • Orbimon does not log Authorization headers.