# MCP for agents

> Connect Claude, Cursor or any MCP client to your Orwel workspace and ask about leads, visitors and campaigns.

Orwel runs a remote [Model Context Protocol](https://modelcontextprotocol.io) server. Connect an agent to it and it can answer questions like "who are my best leads this week and why" or "which campaign brought qualified leads", using your workspace data.

| | |
| --- | --- |
| Endpoint | `https://api.orwel.io/mcp` |
| Transport | Streamable HTTP (stateless, no SSE) |
| Auth | `Authorization: Bearer orwel_sk_...` with an [API key](/docs/authentication) that has the `mcp` scope |
| Scope of data | The workspace that owns the key. Tools never take a workspace parameter. |

<Note>
  The MCP server needs an active Orwel subscription or trial. The production API key (`orwel_pk_`) and the development key (`orwel_dev_`) are not accepted.
</Note>

## 1. Create a key

In **Settings, API keys**, create a key with the `mcp` scope and choose **server only**. Use a separate key per agent, so you can see when each one was last used and revoke it on its own.

## 2. Connect your client

<Tabs>
  <Tab title="Claude Code">
    Run this in your project folder. The first time Claude Code starts it asks you to approve the `orwel` server.

    ```bash
    claude mcp add --transport http orwel https://api.orwel.io/mcp \
      --header "Authorization: Bearer orwel_sk_..."
    ```
  </Tab>
  <Tab title="Claude Desktop">
    In Claude Desktop open **Settings, Developer, Edit Config** and add the server to `claude_desktop_config.json`. It needs Node.js, because it runs through `mcp-remote`.

    ```json
    {
      "mcpServers": {
        "orwel": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://api.orwel.io/mcp", "--header", "Authorization:${ORWEL_AUTH}"],
          "env": { "ORWEL_AUTH": "Bearer orwel_sk_..." }
        }
      }
    }
    ```

    Keep `Authorization:${ORWEL_AUTH}` with no space after the colon: on Windows Claude Desktop splits arguments on spaces, and a space there shows up as "Server disconnected". Quit Claude Desktop completely and open it again after saving.
  </Tab>
  <Tab title="Cursor">
    In Cursor open **Settings, Cursor Settings, MCP** and add a global server, or create `.cursor/mcp.json` at the root of your project:

    ```json
    {
      "mcpServers": {
        "orwel": {
          "url": "https://api.orwel.io/mcp",
          "headers": { "Authorization": "Bearer orwel_sk_..." }
        }
      }
    }
    ```
  </Tab>
  <Tab title="Other clients">
    Any MCP client that supports remote servers over streamable HTTP with custom headers works. Use the endpoint above and send the `Authorization` header on every request.

    ```json
    {
      "url": "https://api.orwel.io/mcp",
      "headers": { "Authorization": "Bearer orwel_sk_..." }
    }
    ```
  </Tab>
</Tabs>

<Warning>
  claude.ai in the browser only supports custom connectors with OAuth, so a Bearer key does not work there yet. Use Claude Code, Claude Desktop, Cursor, or the `mcp_servers` parameter of the Anthropic API.
</Warning>

## 3. Ask

- "Who are my top leads this month and why do they score high?"
- "How did my campaigns perform in the last 30 days?"
- "Show me the full profile of maria@company.com"
- "Create a list with my highest scoring SaaS leads"

## 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` | Lists leads by recency or score, or searches by name, email, company, source or keyword. | `query`, `source`, `date_from`, `date_to`, `sort` (`recent` or `score`), `limit` (max 50), `offset` |
| `get_lead` | Full lead 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), breakdown 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, optionally for one lead. | `identifier`, `date_from`, `date_to`, `limit` |
| `get_campaigns` | Ad campaigns with 30 day totals (impressions, clicks, cost, conversions, CTR). | `status` |
| `get_issues_and_signals` | Issues detected by Orwel (anomalies, funnel drops) and the workspace's configured signals. | `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 if the email exists. | `email`, `name`, `message`, `source`, `code`, `properties` |
| `send_lead_to_hyperflow` | Sends a lead to Hyperflow CRM through the workspace's Hyperflow integration. | `lead_id` |

Dates are ISO 8601 (`2026-06-01`).

## Errors

| Status | Meaning |
| --- | --- |
| `401 unauthorized` | Missing or invalid key, or a public or development key. |
| `403` | The key lacks the `mcp` scope, or the workspace has no active subscription (`plan_not_allowed`). |
| `429` | Rate limit. The MCP server shares the rate limit of the key. |

Inside a tool call, errors come back as a tool result with an explanation (for example "No lead or visitor found for that identifier in this workspace"), so the agent can adjust and retry.