Skip to main content

​
Operate Nora over MCP

Run the Nora MCP server so Claude Code, Claude Desktop, Cursor, or any MCP client can deploy, inspect, and operate your agent fleet — “Claude, why is my agent stopped?” becomes a tool call against your own control plane.
The @noraai/mcp-server package exposes Nora’s public REST API as Model Context Protocol tools over stdio. It authenticates with the same workspace API keys the REST API and CLI use, so workspace scoping and scope-based permissions apply unchanged.

​
Prerequisites

  1. A running Nora control plane reachable over HTTPS.
  2. A workspace API key (Workspace → API Keys, or via the admin API). Scopes determine what the MCP tools can do:
    • agents:read + monitoring:read — all read tools
    • agents:write — deploy and lifecycle tools
  3. Node.js 20+ on the machine running the MCP client.

​
Connect a client

claude mcp add nora \
  --env NORA_API_URL=https://nora.example.com \
  --env NORA_API_KEY=nora_xxxxxxxx \
  -- npx -y @noraai/mcp-server
The nora command comes from @noraai/cli (npm install -g @noraai/cli).

​
Configuration

VariableRequiredPurpose
NORA_API_URLyesBase URL of your Nora deployment (the public origin, e.g. https://nora.example.com)
NORA_API_KEYyesWorkspace API key (nora_…)
NORA_MCP_ALLOW_DESTRUCTIVEnoSet true to register the delete_agent tool. Off by default.
When NORA_API_URL/NORA_API_KEY are unset, the server falls back to NORA_HOST/NORA_TOKEN and then to the CLI’s ~/.nora/config.json, so nora login is sufficient setup for local use.

​
Tools

Read (require agents:read / monitoring:read):
ToolWhat it returns
list_agentsAll agents in the key’s workspace with status, runtime family, deploy target, resources
get_agentOne agent with live-reconciled container status
get_agent_versionsConfiguration version history
get_platform_metricsFleet counts by status plus provisioning queue depth
list_monitoring_eventsRecent platform/agent events with type, search, and time filters
get_agent_metricsTime-series CPU/memory/network/disk/token metrics
get_agent_metrics_summaryAggregated metrics for one agent
get_agent_costPricing-aware token-cost rollup (default last 30 days)
Write (require agents:write):
ToolEffect
deploy_agentProvision a new runtime (name, runtime family, deploy target, sandbox profile, vCPU/RAM/disk)
start_agent / stop_agent / restart_agentLifecycle control
redeploy_agentRe-provision the container with current config
delete_agentPermanent removal — only registered when NORA_MCP_ALLOW_DESTRUCTIVE=true
Tool output is the raw REST JSON, so anything the API reference documents is available to the model.

​
Example prompts

  • “List my agents and tell me which ones aren’t running.”
  • “Deploy an OpenClaw agent named research-assistant with 2 vCPU and 4 GB RAM, then watch it until it’s running.”
  • “What did agent X cost in the last 7 days, and what model was the spend on?”
  • “Show the last 20 events for the fleet and summarize anything unusual.”

​
Security notes

  • The MCP server is a pure client of the REST API — it adds no endpoints and stores nothing. Revoking the API key cuts off access immediately.
  • Use a key with only the scopes you need; a read-only key (agents:read, monitoring:read) makes every tool safe.
  • delete_agent stays unregistered unless explicitly enabled, so a model can’t be talked into destroying an agent by default.