Connecting Claude Desktop

This guide walks through connecting Claude Desktop to your OneHazel workflows over MCP. Once done, you can ask Claude to run any workflow you've exposed — in plain English — and it'll call OneHazel and stream back the result.

Before you start

You'll need:

1. Claude Desktop installed — see Anthropic's quickstart for the base MCP setup
2. A OneHazel operator account with at least one published workflow

Step 1 — Mark workflows as MCP-exposed

In the OneHazel dashboard, open a workflow in the editor and toggle Expose to MCP on the workflow toolbar. Only workflows with this flag are visible over MCP, regardless of API key.

Trigger schema becomes the tool input

The MCP tool's inputSchema is derived from the workflow's trigger event schema (the "Expected fields" card on the trigger node). Make sure required fields are marked required and field types are accurate — that's what Claude reads when deciding what to send.

Step 2 — Create an MCP-enabled API key

1. In the dashboard sidebar, expand Account and click API Keys
2. Click Create API Key, give it a descriptive label (e.g. Claude Desktop — Keith's Mac)
3. Copy the key immediately — the plaintext is only shown once

Store the key now

OneHazel stores only a SHA-256 hash. If you lose the key, revoke it and create a new one — there is no recovery path.

4. On the new key's row, click Configure MCP
5. Toggle MCP enabled ON
6. (Optional) Pick a workflow allowlist — leave empty to allow every MCP-exposed workflow, or pick a subset for least-privilege

Save. The key is now usable as an MCP bearer token.

Step 3 — Note your MCP URL

OneHazel hosts a single canonical MCP URL for every operator:

https://api.onehazel.com/mcp-server

Your API key identifies your operator — no operator ID is required in the URL.

Backward compatibility

The legacy per-operator URL https://api.onehazel.com/mcp-server/<your_operator_id> still works. If your config already uses it, no change is required.

Step 4 — Edit claude_desktop_config.json

Claude Desktop reads MCP server configuration from a JSON file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Open the file (create it if missing) and add a mcpServers entry for OneHazel:

{
  "mcpServers": {
    "onehazel": {
      "type": "http",
      "url": "https://api.onehazel.com/mcp-server",
      "headers": {
        "Authorization": "Bearer oh_live_YOUR_KEY_HERE"
      }
    }
  }
}

Substitute:

• oh_live_YOUR_KEY_HERE — the plaintext API key from Step 2

If you already have other mcpServers entries (Filesystem, GitHub, etc.), merge onehazel into the existing block — don't replace it.

Step 5 — Restart Claude Desktop

Fully quit Claude Desktop and reopen. On startup, Claude Desktop reads the config, opens an HTTP connection to OneHazel, and sends an initialize JSON-RPC call. If it succeeds, your workflows show up in the tools menu.

Step 6 — Verify

In a new Claude Desktop conversation, click the tools icon (the hammer/wrench in the input bar). You should see your OneHazel workflows listed by their MCP tool name (the sluggified workflow name).

Try a quick test:

"Use OneHazel to run my refund_lookup workflow for customer cust_123."

Claude picks the right tool, fills in the inputs from your message, and calls tools/call. The result streams back into the conversation.

Troubleshooting

Symptom	Likely cause	Fix
No OneHazel tools in the menu	Config not picked up	Quit Claude Desktop fully and reopen — a window reload isn't enough
AUTH_INVALID	Wrong key, or key was revoked	Recreate the key in Account → API Keys and update the config
MCP_NOT_ENABLED	Key is valid but mcp_enabled=false	Open Configure MCP on the key and toggle MCP on
AUTH_OPERATOR_MISMATCH	Using legacy URL with mismatched operator ID	Switch to the canonical URL https://api.onehazel.com/mcp-server (Step 3) — the bearer key identifies your operator
Tool list is empty	No workflows have mcp_exposed=true	Open a workflow and flip the Expose to MCP toggle
Tool call fails with MISSING_TRIGGER_FIELD	Claude didn't send a required input	Check the workflow's trigger schema — required fields must be filled

For full error code reference, see API Reference → Error codes.

What's next

• Connecting Cursor — same setup for Cursor users
• Security — how allowlists, rate limits, and audit work