Skip to main content

MCP endpoint

Nerve exposes a Model Context Protocol endpoint so an AI agent can inspect the gateway the way an operator would — answering "is Nerve reaching the broker right now?" without a shell, a dashboard login or a metrics scrape.

Reference: Invoke a Model Context Protocol tool.

Listing the tools​

curl -X POST https://api.nervly.io/v1/mcp \
  -H "Authorization: Bearer $NERVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "method": "tools/list" }'
{
  "jsonrpc": "2.0",
  "result": {
    "tools": [
      {
        "name": "gateway_status",
        "description": "Inspect real-time edge gateway performance metrics and NATS status"
      },
      {
        "name": "idempotency_inspect",
        "description": "Check idempotency cache storage size and active keys"
      }
    ]
  },
  "id": 1
}

Calling a tool​

curl -X POST https://api.nervly.io/v1/mcp \
  -H "Authorization: Bearer $NERVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "method": "tools/call", "params": { "name": "gateway_status" } }'
{
  "jsonrpc": "2.0",
  "result": {
    "service": "nerve-gateway",
    "uptime": 86400,
    "nats_status": "CONNECTED",
    "idempotency_keys": 0
  },
  "id": 1
}

Behaviour worth knowing​

tools/call ignores which tool you asked for

Both advertised tools return the same combined status object. params.name is accepted and not read, so gateway_status and idempotency_inspect are currently indistinguishable. Agents should read the fields they need out of the single result rather than relying on tool selection.

Unsupported methods return 200

An unrecognised method returns 200 with {"result": {"error": "Unsupported MCP method"}} rather than a JSON-RPC error object or a non-2xx status. Check for result.error — a 200 does not mean the call did what you asked.

id is always 1, not echoed from your request, so it cannot be used to correlate concurrent calls.

Security​

This endpoint sits behind the same bearer API key as the rest of /v1, which means an agent holding a key to call it also holds a key that can send notifications to any of your subscribers. Scopes are not enforced per endpoint.

Do not hand a production key to an agent for read-only inspection

There is no read-only key today. If you want an agent to inspect gateway health, either use a key from a non-production workspace, or proxy the call through your own service and give the agent access to that instead.

Next​