MCP API Reference

OneHazel's MCP server speaks JSON-RPC 2.0 over HTTP POST. Every request goes to the same canonical endpoint:

POST https://api.onehazel.com/mcp-server
Authorization: Bearer oh_live_<your-key>
Content-Type: application/json

Your bearer token identifies the operator — no operator ID in the URL.

Backward compatibility

The legacy form POST https://api.onehazel.com/mcp-server/<operator_id> still works. The server enforces that the segment matches the bearer's operator and returns AUTH_OPERATOR_MISMATCH if not.

For most operators, you won't write these calls by hand — Claude Desktop, Cursor, or any other MCP client handles the protocol. This page documents the wire format for when you're debugging or building a custom integration.

Protocol overview

• Protocol version: 2025-06-18
• Server name: onehazel
• Server version: see serverInfo.version in the initialize response
• Transport: JSON-RPC 2.0 over HTTP (Streamable HTTP). An SSE channel is mounted at /mcp-server/events for forward compatibility; current behaviour is a single comment frame then close.

The supported methods are listed below. Anything else returns JSON-RPC -32601 Method not found.

---

initialize {#initialize}

Sent by the client when the connection opens. Returns the server's protocol version, declared capabilities, and identity.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": { "name": "claude-desktop", "version": "0.7.0" }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": { "listChanged": false }
    },
    "serverInfo": {
      "name": "onehazel",
      "version": "0.1.0"
    }
  }
}

Notification follow-up

Clients send a notifications/initialized notification after initialize to signal readiness. OneHazel accepts it and returns no response (per JSON-RPC 2.0 §4.1).

---

ping {#ping}

Lightweight liveness check. Returns an empty result.

Request

{ "jsonrpc": "2.0", "id": 2, "method": "ping" }

Response

{ "jsonrpc": "2.0", "id": 2, "result": {} }

---

tools/list {#tools-list}

Returns the set of MCP tools the calling API key can invoke. Each tool corresponds to one OneHazel workflow with mcp_exposed=true. The list is filtered against the key's mcp_workflow_allowlist:

• null allowlist — every MCP-exposed workflow on your operator
• Array allowlist — only the listed workflows (empty array = none)

Request

{ "jsonrpc": "2.0", "id": 3, "method": "tools/list" }

Response

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "tools": [
      {
        "name": "refund_lookup",
        "description": "Look up a refund by customer ID and date range",
        "inputSchema": {
          "type": "object",
          "properties": {
            "customer_id": { "type": "string", "description": "Customer ID to look up" },
            "since": { "type": "string", "format": "date" }
          },
          "required": ["customer_id"]
        }
      }
    ]
  }
}

• name is the workflow's mcp_tool_name — a sluggified, JSON-RPC-safe slug derived from the workflow's display name
• description comes from the workflow's description field (operator-editable)
• inputSchema is derived from the trigger node's effective event schema — fields the workflow expects on its trigger payload, including operator-defined overrides

If you change the trigger schema in the workflow editor, the next tools/list reflects it.

---

tools/call {#tools-call}

Runs a workflow as if a real trigger event had arrived. The call is synchronous from the client's perspective: OneHazel runs the workflow against your live connections and returns the result inline.

Request

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "refund_lookup",
    "arguments": {
      "customer_id": "cust_123",
      "since": "2026-05-01"
    }
  }
}

• params.name — must match a tool returned by tools/list
• params.arguments — must satisfy that tool's inputSchema (required fields present, types matching)

Response

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Workflow completed. 2 refunds found."
      }
    ],
    "isError": false,
    "_meta": {
      "execution_id": "exec_abc123",
      "duration_ms": 412
    }
  }
}

Execution semantics

• tools/call runs the workflow in mode='test' — real API calls, real side effects, persisted to workflow_executions with metadata.source='mcp'
• Failures (missing required input, downstream connector error, quota exceeded) come back as JSON-RPC results with isError: true and the failure detail in content
• The trigger payload validation gate (see Workflows → Trigger schemas) runs before any node executes; missing required fields produce a MISSING_TRIGGER_FIELD error and zero downstream nodes run
• Workflows are billed against the calling operator's quota exactly as any other run — every billable node increments your Actions / AI Actions counters

Real side effects

A tools/call invocation is a real workflow run. If your workflow sends emails, writes to a downstream system, or calls a paid third-party API, it'll do so. There is no dry-run mode on MCP. Use a least-privileged API key with a narrow allowlist when exposing workflows that have external side effects.

---

Error codes

JSON-RPC standard codes (protocol-level):

Code	Name	When
-32700	Parse error	Body was not valid JSON
-32600	Invalid Request	Missing jsonrpc: "2.0", missing method, or malformed envelope
-32601	Method not found	Unknown method name
-32602	Invalid params	Params shape doesn't match the method
-32603	Internal error	Unhandled server-side exception

OneHazel-specific codes (returned as JSON-RPC -32001 with the SCREAMING_SNAKE code embedded in error.message as code: XYZ):

Code	HTTP status	Meaning
AUTH_MISSING	401	Authorization header not present
AUTH_INVALID_FORMAT	401	Header isn't Bearer <token>, or token isn't an oh_live_* key
AUTH_INVALID	401	Key not found or doesn't match hash
AUTH_REVOKED	401	Key exists but is revoked
MCP_NOT_ENABLED	403	Key is valid but mcp_enabled=false — flip the toggle in Configure MCP
AUTH_OPERATOR_MISMATCH	403	URL operator ID doesn't match the key's operator
MISSING_TRIGGER_FIELD	200*	A tools/call argument set is missing a required field from the workflow's trigger schema
QUOTA_EXCEEDED	200*	Operator has hit their Actions / AI Actions quota for the month

*Workflow-execution errors are returned as JSON-RPC results with isError: true and HTTP 200, not as JSON-RPC errors. The SCREAMING_SNAKE code lives inside the result content.

The full OneHazel error taxonomy is enforced by the OH-134 drift guard — every code: '...' literal in Edge Functions is registered in _shared/errors.ts:ERROR_CODES.

---

CORS

OPTIONS preflight is supported on every route. The server echoes the request origin if it's in the configured allowlist (default * for the MCP endpoint; production may narrow this). Required request headers: Authorization, Content-Type. Required response headers are returned automatically.

---

SSE channel

GET https://api.onehazel.com/mcp-server/events?session=<id>
Authorization: Bearer oh_live_<your-key>
Accept: text/event-stream

Returns text/event-stream with a : ping heartbeat every 15s to keep proxies from closing the connection. The channel survives across many JSON-RPC requests.

Clients that want progress notifications during long-running tools/calls should:

1. Open the SSE channel above with a chosen session=<id> query parameter
2. On the sibling POST to /mcp-server include the header Mcp-Session-Id: <id> and _meta.progressToken: "<token>" inside params
3. Receive notifications/progress frames on the SSE channel

Distributed session affinity (OH-461)

Progress events now reliably bridge across Edge Function instances. When the MCP_SSE_REDIS_AFFINITY server flag is on, the SSE GET handler subscribes to an operator-namespaced Upstash Redis pub/sub channel and the sibling POST publishes every notifications/progress frame to the same channel — so clients receive every frame regardless of which instance handled the POST. Heartbeats remain at 15s. The synchronous tools/call response is unchanged. With the flag off, the server falls back to per-instance behaviour (channel opens, heartbeats fire, but cross-instance progress events may not arrive).

Per-operator concurrent session cap is 5. The 6th /events connection returns MCP_SESSION_LIMIT_EXCEEDED.