Connect Claude, Cursor and other agents with MCP

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, 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 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

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.

From your project folder:

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.

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.

claude_desktop_config.json

{
  "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.

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:

.cursor/mcp.json

{
  "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.

Open Windsurf Settings, Cascade, MCP servers, View raw config and add:

mcp_config.json

{
  "mcpServers": {
    "orwel": {
      "serverUrl": "https://api.orwel.io/mcp",
      "headers": { "Authorization": "Bearer orwel_sk_..." }
    }
  }
}

Press refresh in the MCP panel after saving.

Create .vscode/mcp.json in the workspace. VS Code prompts for the key once and stores it, so it never lands in the file:

.vscode/mcp.json

{
  "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.

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:

{
  "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.

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.

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”	`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.

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

Get Started

SDK

Developers

Integrations

Agents

Core Concepts

Connect Claude, Cursor and other agents with MCP

At a glance

Step 1: create a key for the agent

Step 2: add the server to your client

Step 3: check that it works

What to ask

Tools

Keeping it safe

When something fails

​At a glance

​Step 1: create a key for the agent

​Step 2: add the server to your client

​Step 3: check that it works

​What to ask

​Tools

​Keeping it safe

​When something fails

At a glance

Step 1: create a key for the agent

Step 2: add the server to your client

Step 3: check that it works

What to ask

Tools

Keeping it safe

When something fails