> ## Documentation Index
> Fetch the complete documentation index at: https://orwel-22af1265.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/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 theme={null}
    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 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_..." }
        }
      }
    }
    ```

    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 theme={null}
    {
      "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 theme={null}
    {
      "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](mailto: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.


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