# MCP (Model Context Protocol)

OneHazel exposes your workflows to AI assistants — Claude Desktop, Cursor, and any other client that speaks the [Model Context Protocol](https://modelcontextprotocol.io) — as **callable tools**. Your assistant can read what data shapes your workflows accept and run them on demand, without you wiring up a custom backend per assistant.

## What is MCP?

MCP is an open standard from Anthropic for connecting AI assistants to external tools and data. A client (Claude Desktop, Cursor, etc.) speaks JSON-RPC 2.0 over HTTP to an MCP server; the server advertises tools, and the client lets the LLM call them when the user asks something that lines up with a tool's purpose.

You can think of it like USB-C for AI assistants: one protocol, many integrations.

## How OneHazel fits in

OneHazel hosts a single canonical MCP server URL for every operator:

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

Your API key identifies your operator — the server scopes every request to the operator that owns the key, so you don't paste your operator ID into the URL.

Each of your **workflows** can be flagged as `mcp_exposed` in the workflow editor. Exposed workflows become MCP tools — the trigger's effective field schema becomes the tool's `inputSchema`, and calling the tool runs the workflow end-to-end against your real connections.

Auth is per-API-key: you opt a specific API key into MCP, optionally narrow the allowlist of workflows it can call, and hand that key to your assistant.

::: tip Backward compatibility
The legacy per-operator URL `https://api.onehazel.com/mcp-server/<your_operator_id>` still works. If your assistant is already configured with it, no change is required.
:::

## When to use MCP vs. the REST API

| You want to… | Use |
|---|---|
| Let a human (via Claude / Cursor) trigger a workflow in plain English | **MCP** |
| Have your own code trigger a workflow on a schedule, on a webhook, or as part of a deterministic pipeline | The [REST API](/api-reference/) and [Workflows](/workflows) |
| Let an AI agent in your own product call workflows | Either — MCP if your agent already speaks it, REST otherwise |
| Push raw entities / events / states into OneHazel | The [Data Ingestion API](/data-ingestion/) (MCP is not the right surface for bulk ingestion) |

MCP shines when the workflow inputs are small and human-shaped (a customer ID, a date range, a free-text reason) and the workflow itself does real work — calling supplier APIs, transforming data, writing back to your platform.

## What's on this page set

- **[Connecting Claude Desktop](/mcp/connecting-claude-desktop)** — step-by-step setup
- **[Connecting Cursor](/mcp/connecting-cursor)** — step-by-step setup
- **[API Reference](/mcp/api-reference)** — `initialize`, `tools/list`, `tools/call`, error codes
- **[Security](/mcp/security)** — auth model, allowlists, rate limits, audit

::: tip Prerequisites
You need an active OneHazel operator account with at least one workflow you want to expose. New to OneHazel? Start with [Getting Started](/getting-started) and [Workflows](/workflows) first.
:::

## Protocol version

OneHazel implements MCP protocol version **`2025-06-18`** (server name `onehazel`). The server advertises this in its `initialize` response — see the [API Reference](/mcp/api-reference#initialize).