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

# Connect your agent

> Wire any MCP-capable agent (Claude, Codex, Cursor, or your own) to granvl.

granvl is operated by AI agents. Pages, variants, and copy are built by *your* agent in *your* tools, then pushed to granvl over [MCP](https://modelcontextprotocol.io). granvl exposes its full surface (funnels, variants, weights, analytics, ads, learnings) as MCP tools, and any MCP-capable agent can use them.

The endpoint for every client below:

```
https://app.granvl.com/api/mcp
```

Authentication is granvl's OAuth flow (your client will prompt you to sign in and approve), or a workspace API key from **Settings → API** sent as a Bearer token.

## Setup by client

<Tabs>
  <Tab title="Claude">
    On [claude.ai](https://claude.ai): **Settings → Connectors → Add custom connector**, paste the endpoint URL, and complete the sign-in when prompted. The connector is then available in your chats.
  </Tab>

  <Tab title="Claude Desktop">
    Same as claude.ai: connectors sync to the desktop app. Add it under **Settings → Connectors** with the endpoint URL and approve the OAuth prompt.
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http granvl https://app.granvl.com/api/mcp
    ```

    Run `/mcp` inside a session to authenticate the first time. To pin a workspace instead, use an API key:

    ```bash theme={null}
    claude mcp add --transport http granvl https://app.granvl.com/api/mcp \
      --header "Authorization: Bearer YOUR_API_KEY"
    ```
  </Tab>

  <Tab title="Codex CLI">
    ```bash theme={null}
    codex mcp add granvl -- npx -y mcp-remote https://app.granvl.com/api/mcp
    ```

    Or add it to `~/.codex/config.toml` directly:

    ```toml theme={null}
    [mcp_servers.granvl]
    command = "npx"
    args = ["-y", "mcp-remote", "https://app.granvl.com/api/mcp"]
    ```

    The `mcp-remote` shim bridges Codex's stdio transport to granvl's HTTP endpoint and handles the OAuth sign-in in your browser.
  </Tab>

  <Tab title="Codex (IDE / app)">
    The Codex IDE extension and app read the same `~/.codex/config.toml` as the CLI. Add the `[mcp_servers.granvl]` block from the Codex CLI tab and restart Codex.
  </Tab>

  <Tab title="Cursor">
    Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):

    ```json theme={null}
    {
      "mcpServers": {
        "granvl": {
          "url": "https://app.granvl.com/api/mcp"
        }
      }
    }
    ```

    Cursor will prompt for the OAuth sign-in on first use.
  </Tab>

  <Tab title="Other clients">
    Any MCP client works:

    * **Streamable HTTP support** → point it at the endpoint URL directly.
    * **stdio-only clients** → bridge with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote): `npx -y mcp-remote https://app.granvl.com/api/mcp`.
    * **Headless / server-side** → authenticate with a workspace API key (`Authorization: Bearer …`) instead of OAuth.
  </Tab>
</Tabs>

<Note>
  Workspace scoping: OAuth connections follow your **active workspace**; API keys are pinned to the workspace they were created in. Switch workspaces in the dashboard before connecting if you manage several.
</Note>

## What your agent can do

| Area                | Examples                                                                                                                                                                                                                             |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Pages & funnels** | Create funnels and pages, generate and update variants, publish/unpublish, create preview links                                                                                                                                      |
| **Testing**         | Set traffic weights, duplicate variants, read per-variant stats, record learnings so tests never repeat a dead end                                                                                                                   |
| **Analytics**       | Funnel stats and timeseries, step-by-step drop-off, session journeys, segmented breakdowns                                                                                                                                           |
| **Ads**             | Sync Google Ads entities and spend, record Meta entities and spend (`record_ad_entities`, `record_ad_spend`) while the one-click Meta connection is in review, create campaigns/ad sets/ads, upload creatives, check tracking health |
| **Optimization**    | Pull suggestions, act on them (promote a winner, pause a loser), and log the outcome                                                                                                                                                 |

See the [MCP tool reference](/integrations/mcp-tools) for the full list.

## Prompts that work well

```text theme={null}
Build a lead-capture landing page for [offer] on my [domain] funnel.
Create two headline variants (one benefit-led, one curiosity-led) and
split traffic 50/50.
```

```text theme={null}
Check my funnel stats for the last 7 days. If any variant is clearly
losing (under half the leader's conversion rate with enough sessions),
set its weight to 0 and record the learning.
```

```text theme={null}
Record my latest Meta ad stats, then tell me which ad has the best CPA
against first-party conversions, and which lander variant converts its
traffic best.
```

<Tip>
  The best results come from giving your agent an outcome, not a task list: *"get my cost per lead under \$12 on this funnel"* lets it use stats, variants, and weights together.
</Tip>