> ## Documentation Index
> Fetch the complete documentation index at: https://www.orwel.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Claude, Cursor and other agents with MCP

> Give Claude Code, Claude Desktop, Cursor, Windsurf or VS Code access to your Orwel leads, visitors and campaigns through the Orwel MCP server, with copy and paste configs and example questions.

The Orwel MCP server lets a coding or chat agent read your workspace the way you would in the dashboard. Instead of exporting a CSV and pasting it into a chat, you ask "which campaign brought qualified leads this month" and the agent calls Orwel, reads the answer and explains it.

It speaks the [Model Context Protocol](https://modelcontextprotocol.io), so the same server works in every client that supports remote MCP servers.

## At a glance

| | |
| - | - |
| Endpoint | `https://api.orwel.io/mcp` |
| Transport | Streamable HTTP, stateless (no SSE stream to keep open) |
| Auth | `Authorization: Bearer orwel_sk_...`, an [API key](https://www.orwel.io/docs/authentication.md) with the `mcp` scope (plus `leads:write` or `lists:write` for the tools that write) |
| Data it can reach | Only the workspace that owns the key. No tool takes a workspace id, so an agent cannot wander into another workspace. |
| Plan | Needs an active subscription or trial |

> [!NOTE]
>
> Only secret keys (`orwel_sk_`) work here. The production API key (`orwel_...`) that lives in your website and the development key (`orwel_dev_`) are rejected with `401`, because both are meant to be public.

## Step 1: create a key for the agent

Open **Settings, API keys**, create a key, give it the `mcp` scope and mark it as **server only**. Name it after the agent that will use it ("Claude Code, laptop", "Cursor, shared repo").

With only `mcp` the agent can use every read tool. To let it write, give the key the matching scope too:

| Scope | Unlocks |
| - | - |
| `mcp` | Every read tool, and `manage_lists` with `action="list"` |
| `leads:write` | `create_lead` and `send_lead_to_hyperflow` |
| `lists:write` | `manage_lists` with `action="create"` or `action="add_member"` |

A write tool called without its scope returns a tool error naming the missing scope, so the agent can tell you what to add.

One key per agent pays off later: the keys list shows when each one was last used, and you can revoke one agent without breaking the others.

## Step 2: add the server to your client

Replace `orwel_sk_...` with the key from step 1.

> [tab] Claude Code
>
> From your project folder:
>
> ```bash theme={null}
> claude mcp add --transport http orwel https://api.orwel.io/mcp \
>   --header "Authorization: Bearer orwel_sk_..."
> ```
>
> Claude Code asks you to approve the `orwel` server the next time it starts. Run `claude mcp list` to confirm it shows as connected. Add `--scope user` to make it available in every project instead of only this one.

> [tab] Claude Desktop
>
> Open **Settings, Developer, Edit Config** and add the server to `claude_desktop_config.json`. Claude Desktop reaches remote servers through `mcp-remote`, so Node.js must be installed.
>
> ```json claude_desktop_config.json theme={null}
> {
>   "mcpServers": {
>     "orwel": {
>       "command": "npx",
>       "args": ["-y", "mcp-remote", "https://api.orwel.io/mcp", "--header", "Authorization:${ORWEL_AUTH}"],
>       "env": { "ORWEL_AUTH": "Bearer orwel_sk_..." }
>     }
>   }
> }
> ```
>
> Write `Authorization:${ORWEL_AUTH}` with no space after the colon. On Windows, Claude Desktop splits arguments on spaces, and a space there ends as "Server disconnected". Quit Claude Desktop completely (also from the tray) and open it again after saving.

> [tab] Cursor
>
> Add a global server in **Settings, Cursor Settings, MCP**, or commit `.cursor/mcp.json` at the root of the project so the whole team gets it:
>
> ```json .cursor/mcp.json theme={null}
> {
>   "mcpServers": {
>     "orwel": {
>       "url": "https://api.orwel.io/mcp",
>       "headers": { "Authorization": "Bearer orwel_sk_..." }
>     }
>   }
> }
> ```
>
> If you commit the file, do not commit the key. Keep the real value in each developer's global config instead.

> [tab] Windsurf
>
> Open **Windsurf Settings, Cascade, MCP servers, View raw config** and add:
>
> ```json mcp_config.json theme={null}
> {
>   "mcpServers": {
>     "orwel": {
>       "serverUrl": "https://api.orwel.io/mcp",
>       "headers": { "Authorization": "Bearer orwel_sk_..." }
>     }
>   }
> }
> ```
>
> Press refresh in the MCP panel after saving.

> [tab] VS Code
>
> Create `.vscode/mcp.json` in the workspace. VS Code prompts for the key once and stores it, so it never lands in the file:
>
> ```json .vscode/mcp.json theme={null}
> {
>   "inputs": [
>     { "type": "promptString", "id": "orwel-key", "description": "Orwel API key (orwel_sk_...)", "password": true }
>   ],
>   "servers": {
>     "orwel": {
>       "type": "http",
>       "url": "https://api.orwel.io/mcp",
>       "headers": { "Authorization": "Bearer ${input:orwel-key}" }
>     }
>   }
> }
> ```
>
> Then open Copilot Chat in agent mode and enable the `orwel` tools.

> [tab] Other clients
>
> Any client that supports remote servers over streamable HTTP with custom headers works. Point it at the endpoint and send the header on every request:
>
> ```json theme={null}
> {
>   "url": "https://api.orwel.io/mcp",
>   "headers": { "Authorization": "Bearer orwel_sk_..." }
> }
> ```
>
> From your own code, the Anthropic API accepts the same server in the `mcp_servers` parameter with the key as `authorization_token`.

> [!WARNING]
>
> Custom connectors in claude.ai (the browser app) only support OAuth for now, so a Bearer key cannot be used there yet. Use Claude Code, Claude Desktop, Cursor, Windsurf, VS Code or the API.

## Step 3: check that it works

Ask the agent: **"Use the orwel tools to tell me which workspace you are connected to."** It should call `get_workspace_context` and answer with your workspace name and domain. If it answers from memory instead, the server is not connected; see [When something fails](#when-something-fails).

## What to ask

The agent picks the tools by itself. These questions work well because each one maps to data Orwel already has:

| You ask | What the agent does |
| - | - |
| "Who are my best leads this week, and why do they score high?" | `search_leads` sorted by score with a date range, then `get_lead` on the top ones |
| "Which source brings the leads with the highest score?" | `get_lead_analytics`, which breaks leads down by source with the average score |
| "How did my ad campaigns do in the last 30 days?" | `get_campaigns` with impressions, clicks, cost, conversions and CTR |
| "Show me everything about [maria@company.com](mailto:maria@company.com)" | `get_lead` with the email: company, persona, sessions, conversions and events |
| "Did anyone convert today? What did they do before?" | `get_conversions` for today, then `get_lead` for the history |
| "Are identified visitors coming back this week?" | `get_visitors` with `identified_only` |
| "Is anything broken or unusual in my funnel?" | `get_issues_and_signals` |
| "Put my top 10 SaaS leads in a list called Q4 outreach" | `search_leads`, then `manage_lists` to create the list and add each member |
| "Add the lead from this email thread" | `create_lead` with the email, name and message |
| "Send this lead to our CRM" | `send_lead_to_hyperflow`, when the Hyperflow integration is connected |

Questions about the business ("is this lead a good fit for us?") work better after the agent reads `get_workspace_context`, which includes your business description and ideal customer profiles. Fill those in **Settings** to get sharper answers.

## Tools

| Tool | What it returns or does | Parameters |
| - | - | - |
| `get_workspace_context` | Workspace name, domain, business context, ideal customer profiles and landing page. | none |
| `search_leads` | Leads by recency or score, or matching a name, email, company, source or keyword. | `query`, `source`, `date_from`, `date_to`, `sort` (`recent` or `score`), `limit` (max 50), `offset` |
| `get_lead` | Full profile: identity, company, persona and engagement, recent sessions, conversions and events. | `identifier` (lead id, email or name) |
| `get_lead_analytics` | Totals (all time, 7 and 30 days), leads by source with average score, score distribution, conversion rate and a 12 week trend. | `date_from`, `date_to` |
| `get_visitors` | Recent visitor sessions, anonymous or identified. | `limit`, `date_from`, `date_to`, `identified_only` |
| `get_conversions` | Conversion events, for the workspace or one lead. | `identifier`, `date_from`, `date_to`, `limit` |
| `get_campaigns` | Ad campaigns with 30 day totals: impressions, clicks, cost, conversions and CTR. | `status` |
| `get_issues_and_signals` | Issues Orwel detected (anomalies, funnel drops) and the signals configured in the workspace. | `status`, `limit` |
| `manage_lists` | Visitor lists: `list` them with member counts, `create` one, or `add_member`. | `action`, `name`, `description`, `color`, `list_id`, `identity_id` |
| `create_lead` | Creates a lead with an email identity, reusing the visitor when the email already exists. | `email`, `name`, `message`, `source`, `code`, `properties` |
| `send_lead_to_hyperflow` | Sends a lead to Hyperflow CRM through the workspace integration. | `lead_id` |

Dates use ISO 8601 (`2026-06-01`). Every tool except `manage_lists`, `create_lead` and `send_lead_to_hyperflow` only reads data. Those three also need a write scope on the key, see [Step 1](#step-1-create-a-key-for-the-agent).

## Keeping it safe

* **Read only unless you allow writes.** Three tools write: `manage_lists`, `create_lead` and `send_lead_to_hyperflow`. They only work when the key also has `lists:write` or `leads:write`, so a key with only `mcp` cannot change anything. Most clients also ask before each tool call; keep that confirmation on.
* **Keys stay out of repos.** Use the client's global config, an environment variable or the VS Code input prompt. A key committed by mistake should be revoked, not just deleted from the file.
* **Rotate without downtime.** Create the new key, update the client, confirm it works, then revoke the old one in **Settings, API keys**. A revoked key stops working on the next request.
* **Shared data.** The agent sees the same leads you see, including emails and names. Treat the chat history like any other export of customer data.

## When something fails

| What you see | Cause and fix |
| - | - |
| `401 unauthorized` | The key is missing, mistyped, revoked, or it is the production (`orwel_...`) or development (`orwel_dev_...`) key. Create a secret key with the `mcp` scope. |
| `403` | The key exists but lacks the `mcp` scope (`insufficient_scope`), it was called from a browser (`origin_not_allowed`), or the workspace has no active subscription (`plan_not_allowed`). |
| A tool says "missing the required scope" | The key has `mcp` but not the write scope for that tool. Scopes cannot be edited after creation: create a new key with `mcp` plus `leads:write` or `lists:write`, update the client, then revoke the old key. |
| `429` | Rate limit. The MCP server shares the limit of the key, so a busy integration on the same key slows the agent down. Give the agent its own key. |
| "Server disconnected" in Claude Desktop | Usually the space after `Authorization:` in the args, or Node.js not installed. Check the [Claude Desktop config](#step-2-add-the-server-to-your-client). |
| The agent answers without calling Orwel | The server is not enabled in this chat or project. In Claude Code run `claude mcp list`; in Cursor and VS Code check that the `orwel` tools are switched on. |

When a single tool call fails, the error comes back as the tool result with a reason ("No lead or visitor found for that identifier in this workspace"), so the agent can fix the parameters and try again on its own.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.