AgentNexusAPI
Documentation home

Build & integrate

MCP gateway

Model Context Protocol JSON-RPC at POST /api/mcp — evaluate and fetch evaluations from MCP clients; mcp_trace on run bundles.

MCP gateway (Model Context Protocol)

AgentNexusAPI exposes a Streamable HTTP–compatible MCP endpoint so AI clients (Cursor, Claude Desktop, custom agents) can call governance as standard tools instead of hand-rolled REST. This complements direct POST /api/v1/evaluate: the MCP path is optimized for agent loops and records MCP trace metadata on evaluations for audit.

Industry momentum: vendors such as Hoop.dev are investing in MCP-centric agent operations; shipping a thin, standards-shaped gateway early keeps integrations portable.

Endpoint

  • URL: POST /api/mcp on your deployment origin (e.g. https://your-app.example/api/mcp).
  • Protocol: JSON-RPC 2.0 over HTTP. This build returns JSON bodies only (no server-sent event stream). Clients must still send MCP’s required Accept header (see below).
  • Auth: Same as REST — Authorization: Bearer <api_key> or x-api-key: <api_key>.

Required headers

Per MCP Streamable HTTP:

  • Accept: application/json, text/event-stream
  • Content-Type: application/json

Security

  • Origin allowlist (recommended in production): set MCP_ALLOWED_ORIGINS to a comma-separated list of allowed Origin values (e.g. https://app.cursor.sh). Empty or unset → origin check skipped (browser Origin may still be absent for non-browser clients).
  • API keys gate every JSON-RPC request (notifications without id are the exception; see below).

JSON-RPC methods

MethodPurpose
initializeReturns protocolVersion 2025-03-26, capabilities.tools, serverInfo.
notifications/initializedNo id field → HTTP 202 empty body (lifecycle ack).
tools/listLists MCP tools (see below).
tools/callInvokes a tool.
pingHealth check; returns {}.

Batch arrays are not supported in this version (send one message per request).

Tools

agentnexus_evaluate

Same semantics as POST /api/v1/evaluate. Arguments:

  • policy_name (string, required)
  • payload_scope (object, required)
  • agent_id (optional)
  • webhook_url (optional)
  • mcp_session_id / mcp_client_name (optional correlation — stored under context_json.mcp_trace and run_bundle.mcp_trace)
  • idempotency_key (optional → forwarded as Idempotency-Key)
  • tool_calls / artifacts (optional, same caps as REST)

The gateway adds gateway, gateway_jsonrpc_id, and gateway_request_id to mcp_trace.

Tool result is JSON text:

{ "httpStatus": 200, "body": { "evaluation_id": "...", "status": "..." } }

On HTTP error, isError is true (MCP tools/call result).

agentnexus_get_evaluation

  • evaluation_id (UUID) — must belong to the API key’s workspace.

Returns evaluation row fields including context_json and run_bundle (can be large).

REST: context.mcp_trace

Even without MCP, you may set context.mcp_trace on POST /api/v1/evaluate with:

  • session_id, client_name, request_id, parent_span_id
  • optional gateway, gateway_jsonrpc_id, gateway_request_id if you proxy through your own gateway

Idempotency: mcp_trace is excluded from the idempotency fingerprint so retries with different trace metadata still match the same Idempotency-Key + payload.

Example: tools/call

POST /api/mcp HTTP/1.1
Host: your-deployment.example
Authorization: Bearer YOUR_API_KEY
Accept: application/json, text/event-stream
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "agentnexus_evaluate",
    "arguments": {
      "policy_name": "payments-default",
      "payload_scope": { "amount": 50, "currency": "USD" },
      "mcp_session_id": "cursor-session-abc",
      "mcp_client_name": "Cursor"
    }
  }
}

Client setup (Cursor, Claude Desktop, stdio)

Copy-and-paste examples and the stdio bridge live in integrations/mcp-stdio-bridge/:

FilePurpose
cursor-mcp.http.json.exampleCursor HTTP MCP: url points at https://…/api/mcp plus headers.
cursor-mcp.stdio.json.exampleCursor stdio MCP: runs agentnexus-mcp-bridge.mjs with env vars.
claude_desktop_config.fragment.json.exampleMerge into Claude Desktop mcpServers (stdio only).
agentnexus-mcp-bridge.mjsForwards each JSON-RPC line from stdin to POST /api/mcp (Node 18+).
README.mdEnv vars, manual test, config paths.

If a Cursor build does not accept remote url servers, use the stdio example and the bridge.

Operational notes

  • The MCP handler forwards to POST /api/v1/evaluate over HTTP using NEXT_PUBLIC_APP_URL (or VERCEL_URL / localhost). Ensure that URL is reachable from the server process (default on Vercel).
  • Rate limits: /api/mcp shares the same Edge evaluate IP bucket as /api/v1/evaluate when Upstash is configured; per–API-key limits still apply inside the evaluate route.

Related