API & MCP reference

REST endpoints and the MCP tool surface the agent uses

There are two programmatic surfaces and they share one permission model. The REST API is for integrations and automation outside the platform; the MCP endpoints expose the same capabilities as tools for agents. Neither has a capability the other is missing — if you can do it in the UI you can do it through one of them.

REST API

JSON in, JSON out, standard HTTP status codes, and Bearer token authentication. Permissions are the same as those of the user or service account the token belongs to, so an integration cannot do more than its account can.

# List devices
curl -H "Authorization: Bearer $ORCA_TOKEN" \
  https://<instance>/api/devices

# Ingest an alert
curl -X POST -H "Authorization: Bearer $ORCA_TOKEN" \
  -H "Content-Type: application/json" \
  https://<instance>/api/v1/alerts \
  -d '{"source":"custom","severity":"critical",
       "title":"BGP peer down","device":"bom-core-sw-01"}'

Area	Representative operations
Devices	List, filter, create, update; device facts, interfaces, health, backups; test connection
Alerts	Ingest, list, filter, acknowledge, comment, resolve; correlation groups
Tickets	Create, list, update, assign, resolve; timeline, change log, verification result
Automation	List playbooks, trigger a run, read execution status and logs, manage approvals
Agents	List agents, read activity and usage, cancel an in-flight agent run
Settings	Read and write integration configuration; secrets are write-only

Secrets are write-only

A stored secret is never returned by the API — responses carry a mask, and sending the mask back leaves the stored value unchanged. That means a read-modify-write of a settings object will not wipe a key you did not intend to touch.

Pagination and filtering

List endpoints take offset and limit, with a maximum page size, and support a filter expression rather than a growing set of ad-hoc query parameters. Filtering server-side is the difference between an integration that scales and one that downloads everything and sorts locally.

# Page through devices, newest first
GET /api/devices?offset=0&limit=100&filter=status:'online' AND vendor:'cisco_ios'

MCP endpoints

Each integration is a separate MCP server over Streamable HTTP. They are mounted individually so a failure in one does not remove the others, which also means a tool that "does not exist" is usually a tool whose endpoint is not configured.

Endpoint	Path
Core	/api/mcp
Azure	/api/azure-mcp
AWS	/api/aws-mcp
GCP	/api/gcp-mcp
vSphere	/api/vsphere-mcp
Meraki	/api/meraki-mcp
ISE	/api/ise-mcp
Proxmox	/api/proxmox-mcp
UniFi	/api/unifi-mcp

# Health probe — confirms the endpoint is mounted
curl -H "X-API-Key: $ORCA_AGENT_API_KEY" \
  https://<instance>/api/mcp

# List tools (JSON-RPC over Streamable HTTP)
curl -X POST -H "X-API-Key: $ORCA_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  https://<instance>/api/mcp \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Call one
curl -X POST -H "X-API-Key: $ORCA_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  https://<instance>/api/mcp \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"execute_ssh_command",
                 "arguments":{"device_id":42,"command":"show version"}}}'

Tool names are namespaced

A tool is addressed as a server-qualified name, so the same verb on two integrations cannot collide.

mcp__orca-core__execute_ssh_command
mcp__orca-meraki__meraki_list_devices
mcp__orca-unifi__unifi_getInfo
mcp__orca-proxmox__proxmox_power_vm

The advertised list is a budget, not the catalog

The number of tools returned by a listing is capped to fit the configured model and weighted by server, so it is smaller than the total catalog. Every tool remains callable by name, and the discovery tools search the full set. A capped listing is not a missing integration.

Rate limits and errors

Concern	Behaviour
REST rate limit	Per token, with a documented default; 429 on exceed
MCP rate limit	A GET storm is rate-limited so a reconnect loop cannot hammer an endpoint
Vendor rate limits	Respected per vendor — the UniFi Cloud Connector's 100 req/min is enforced client-side
Errors	Standard HTTP status with a machine-readable error code and a human-readable message

Write operations that mutate a device are subject to the same approval policy as the UI. An API client is a first-class actor, not a bypass — it can propose a change, and the approval still belongs to a human.

PreviousDeployment & licensing Next Security & data protection

OrcaMonitor documentation v1.0.0 · Report a problem

Explore the full platform

See every module, pricing tier, and deployment option on the OrcaMonitor overview.

Back to Overview