# Connecting Claude Desktop

This guide walks through connecting [Claude Desktop](https://claude.ai/download) 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](https://modelcontextprotocol.io/quickstart/user) 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.

::: tip 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

::: warning 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.

::: tip 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:

```json
{
  "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](/mcp/api-reference#error-codes).

## What's next

- [Connecting Cursor](/mcp/connecting-cursor) — same setup for Cursor users
- [Security](/mcp/security) — how allowlists, rate limits, and audit work