> For the complete documentation index, see [llms.txt](https://docs.humblytics.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.humblytics.com/api-access-and-agents.md).

# API Access & Agent Setup

The **Agents** page connects your AI coding agents to live Humblytics data. Open it from **Agents** in the sidebar (under **Agent & data**), or go to `/agent`. It replaces the former separate **API & MCP** page; old `/api` links redirect to the **API keys** tab.

The page opens with the **Connect an assistant** card (MCP sign-in, no key to paste), followed by four tabs:

| Tab                    | What it shows                                                                                                                                                                                                                  |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Activity** (default) | Connected agents (your active account keys with when each was last used), plus placeholders for tests your agents launched and an activity log, which are not recorded yet. Every test, however it started, is in Experiments. |
| **API keys**           | Create, copy and revoke account and property keys, and the per-key **Launch tests** switch.                                                                                                                                    |
| **Skills**             | Optional marketing skills for your agent.                                                                                                                                                                                      |
| **REST reference**     | Example requests against the REST API.                                                                                                                                                                                         |

The page is account-level. Property keys and REST examples use the site chosen with the site picker on the **API keys** tab (or `?site=<propertyId>`).

**MCP server URL** (ChatGPT uses the `/chatgpt` variant):

```
https://mcp.humblytics.com/v1
```

```
https://mcp.humblytics.com/v1/chatgpt
```

**Claude connector**: [claude.ai/connectors/humblytics-mcp](https://claude.ai/connectors/humblytics-mcp)

**REST base URL**:

```
https://app.humblytics.com/api/external/v1
```

***

## Humblytics MCP

The Humblytics MCP server is a [Model Context Protocol](https://modelcontextprotocol.io) server that gives compatible AI agents supported access to Humblytics analytics and experiment-management tools. It is a supporting workflow for teams using Humblytics to connect paid spend, conversion work, and revenue. MCP and API access are included on every plan, including the Free start (the first 5,000 data points and 1 site, no card). Existing Plus accounts retain their current access.

| What it covers        |                                               |
| --------------------- | --------------------------------------------- |
| **Traffic & trends**  | Pageviews, sessions, bounce rate              |
| **Funnels**           | Step-by-step conversion analysis              |
| **A/B tests**         | Create, read, and stop experiments            |
| **Heatmaps & clicks** | Friction and engagement data                  |
| **Setup & billing**   | Add sites, check the install, buy data points |

Once connected, your agent can query supported data and identify test opportunities. Split tests an agent creates arrive as **Awaiting approval** and reach no visitor until you approve them — in chat through the `activate_split_test` tool, or by opening the test in Humblytics and clicking **Activate test**. See [Approval of agent-created tests](https://docs.humblytics.com/split-testing-api.md#approval-of-agent-created-tests). The connection works with Claude, ChatGPT, Codex, Cursor and other agents that support remote MCP servers.

***

## Claude.ai and Claude Desktop (one click)

Using Claude in the browser or the desktop app? Install Humblytics from the Claude connector directory:

[**Add Humblytics to Claude**](https://claude.ai/connectors/humblytics-mcp)

Click **Connect**, sign in to Humblytics and approve access. The connector is then available in every chat. You can disconnect it at any time from Claude's connector settings.

***

## Signing up from your agent

On humblytics.com, **Sign up with your agent** takes you straight into the agent-first setup:

* Onboarding skips the agent-or-app question and goes directly to **Connect your agent**. Accounts that sign up without choosing the agent path (for example, from a platform install page) still see the question.
* If you picked an agent tab (Claude, Claude Code, ChatGPT, Codex, Cursor or another) and typed your site on the marketing site, that agent is preselected and the first message reads `Set up Humblytics on <your site>.`
* The agent path is honoured for one hour after you open the link, so an older visit never changes a later sign-up.
* Your account starts on **Free start** with 5,000 free data points. See [Plan Limits & Upgrades](https://docs.humblytics.com/understanding-your-data/plan-limits-and-upgrades.md) for what happens at the limit and how top-ups work.

***

## Connecting via OAuth (Recommended)

The easiest way to connect is to copy the setup prompt from the **Agents** page in your dashboard and paste it into your agent. If your account has no active agent key yet, the page opens the connection setup for you (you can also open it with `/agent?setup=mcp`). Click **Copy setup prompt**, then paste it into your agent. The page shows the MCP URL and connection options for Claude, ChatGPT, Cursor and Codex. Choose **Skip for now and open my dashboard** if you want to connect later.

If you arrived from a website audit, the prompt also names the audited site and test 1.

If you prefer to pick an agent type and get a key-based prompt, use **Setup Humblytics MCP** on the keys tab (Claude Code, Codex CLI, or Generic).

The prompt instructs your agent to:

1. Call a Humblytics endpoint to start an authorization session — no credentials needed
2. Show you a URL to open in your browser
3. Wait while you sign in (if needed) and click **Approve access**
4. Receive an API key automatically once you approve
5. Register the MCP server with that key — using the right config format for your agent

You don't handle the key yourself at any point. Once connected, the agent uses it on every subsequent request automatically.

The authorization link expires after 15 minutes. If it times out, just paste the prompt again.

{% hint style="info" %}
You can revoke the generated key at any time from the **API keys** tab of the **Agents** page in your Humblytics dashboard.
{% endhint %}

***

## Connect your agent during onboarding

The sign-up wizard has an optional **Connect your agent** step after the tracking script and connectors, before you land on the dashboard. It uses the same OAuth flow described above, so you never paste a key by hand.

1. Pick your client: **Claude**, **ChatGPT**, **Codex**, **Cursor**, or **Other**. The setup prompt and the hint under it change to match.
2. Click **Copy** and paste the prompt into your agent.
3. Open the link your agent shows you, sign in if needed, and click **Approve access**.

The step watches for your agent's first request. When one of your account keys is used after you opened the step, the heading changes to **Your agent is connected**. You can also skip it and connect later from the **Agents** page.

By default an agent can read your numbers, suggest tests and draft them for your approval. In-chat launching can be turned off per key with the **Launch tests** switch on the **API keys** tab; a test can then only be approved from its link in Humblytics.

### Agent-first setup

At the start of the **You** step you can choose how you want to use Humblytics: **With your agent** or **In the Humblytics app**. If you choose **With your agent**, the order changes to: add site → you → **connect your agent** → install the script → goal → campaign. Your agent is connected first, then adds the tracking script for you (see [Let your agent add the script](https://docs.humblytics.com/how-to-get-started/set-up-with-your-ai-agent.md)).

***

## Setting up MCP manually (Alternative)

If you'd rather supply a key yourself — for example in a CI environment or shared machine — you can create one explicitly and configure the MCP server with it directly.

### 1. Create an API key

Go to the **API keys** tab of the **Agents** page and click **Create account key**. Give it a name (e.g. `Claude Agent`, `CI/CD`), and copy the key immediately — it is shown only once.

### 2. Register the MCP server with your agent

Select your agent type below and follow the one-time setup. The server works for every site the key can reach: your agent picks the site per tool call, or finds it with `list_properties`.

#### Claude Code

```
claude mcp add humblytics --transport http https://mcp.humblytics.com/v1 \
  --header "Authorization: Bearer YOUR_API_KEY"
```

#### Codex CLI

The Codex prompt configures a `[mcp_servers.humblytics]` block in your Codex config with the MCP URL and the same `Authorization` header.

#### ChatGPT

Add a custom connector with the URL `https://mcp.humblytics.com/v1/chatgpt` and sign in when asked. The ChatGPT profile is the same server without the billing tools.

#### Generic

For any other agent that supports remote MCP servers:

```
URL: https://mcp.humblytics.com/v1
Authorization: Bearer YOUR_API_KEY
```

{% hint style="warning" %}
The key is only shown once, during creation. Copy it before closing. If you lose it, revoke the key and create a new one.
{% endhint %}

***

## MCP tool catalog

The server exposes 47 tools (44 on the ChatGPT profile, which has no billing tools). Each tool takes a `propertyId` where it applies; the key chooses which sites are reachable.

| Group                        | Tools                                                                                                                                                                                                                                                                                                    |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Setup**                    | `get_account_status`, `create_property`, `delete_property`, `get_install_status`, `report_setup`                                                                                                                                                                                                         |
| **Billing** (not on ChatGPT) | `get_agents_checkout_link`, `buy_data_point_top_up`, `set_auto_top_up`                                                                                                                                                                                                                                   |
| **Properties**               | `list_properties`                                                                                                                                                                                                                                                                                        |
| **Analytics**                | `get_traffic_summary`, `get_traffic_trends`, `get_traffic_realtime`, `get_traffic_breakdown`, `get_entry_exit_pages`, `get_pages_breakdown`, `get_page_details`, `get_clicks_breakdown`, `get_clicks_details`, `get_forms_breakdown`, `get_forms_details`, `aggregate_traffic`                           |
| **Heatmaps**                 | `get_heatmap`                                                                                                                                                                                                                                                                                            |
| **Funnels**                  | `query_funnel`, `get_funnel_sankey`, `get_funnel_suggestions`, `list_saved_funnels`, `save_funnel`, `delete_saved_funnel`                                                                                                                                                                                |
| **Split testing**            | `get_split_test_recommendations`, `create_split_test`, `activate_split_test`, `list_split_tests`, `get_split_test`, `update_split_test`, `stop_split_test`                                                                                                                                               |
| **Ads attribution**          | `get_ads_attribution`                                                                                                                                                                                                                                                                                    |
| **Ads connections**          | `list_google_ads_connections`, `get_google_ads_connection`, `list_google_ads_campaigns`, `list_meta_connections`, `get_meta_connection`, `get_meta_connection_status`, `list_meta_campaigns`, `list_meta_account_campaigns`, `get_meta_daily_insights`, `list_meta_campaign_ads`, `get_meta_ad_creative` |

Every tool maps to an endpoint documented in the [External Analytics API](https://docs.humblytics.com/external-analytics-api.md), [Split Testing API](https://docs.humblytics.com/split-testing-api.md), [Ads Attribution API](https://docs.humblytics.com/ads-attribution-api.md) and [Ads Connections API](https://docs.humblytics.com/ads-connections-api.md). `create_split_test` always creates a draft; `activate_split_test` shows you the changes in your client's confirmation prompt and launches only if you approve (or returns the `approval_url` when the client cannot prompt, or `launch_not_allowed` when **Launch tests** is off for the key). Reads and tool calls are never counted as data points.

### Skill prompts and resources

The 12 marketing skills below are also built into the server as MCP prompts, each taking optional `propertyId`, `page` and `date_range` arguments: `ab-test-generator`, `ad-expert`, `content-strategist`, `copywriting`, `cro-optimizer`, `email-sequences`, `funnel-reporter`, `heatmap-analyst`, `marketing-strategist`, `page-cro`, `revenue-attributor`, `seo-strategist`. Pick one from your client's prompt menu to run it with live data. The same skills, plus the shared CRO benchmarks and frameworks they cite, are readable as resources at `humblytics://skills/<name>`.

***

## API keys

API access is included on every plan, including the **Free start**, the **Agents** plan, **Business**, **Scale**, and **Enterprise**. Existing Plus accounts retain their current access. The page has two key types:

### Account keys

Account keys work across all your properties and are the recommended choice for MCP and agents. Create one with **Create account key**, give it a name (e.g., `Production`, `Claude Agent`, `CI/CD`), and copy it immediately — the full key is displayed once at creation and cannot be retrieved later. Only account keys can add or delete sites and buy data points.

### Property keys

Property keys are scoped to a single property. Choose the site in the site picker on the **API keys** tab (shown when your account has more than one site) before creating one. These are useful when you want to isolate a key to a specific site.

### Launch tests

Each account key has a **Launch tests** switch (on by default). With it on, an agent connected with that key can approve a draft split test in chat through `activate_split_test`. With it off, the agent can still draft tests, but every launch goes through the test's approval link in Humblytics.

### Revoking keys

Click the revoke icon next to any active key. Agents using that key lose access immediately. Revocation cannot be undone, but you can always create a new key. Previously revoked keys appear in the collapsed **Revoked keys** section.

### When your subscription has ended

If your paid subscription is canceled or otherwise in a read-only billing state, the **Agents** page stays open so you can review and revoke keys. **Create account key** and **Create property key** are blocked and route to **Upgrade** (or to the Stripe customer portal when you have an overdue invoice on an active subscription). See [Plan Limits & Upgrades](https://docs.humblytics.com/understanding-your-data/plan-limits-and-upgrades.md#after-your-subscription-ends-read-only).

***

## Marketing skills & REST API

The **Skills** and **REST reference** tabs give you two additional ways to work with Humblytics from an agent.

### Marketing skills

Install 12 Humblytics marketing skills from the open-source [humblytics-marketing-skills](https://github.com/Humblytics/humblytics-marketing-skills) repository. Click **Add 12 skills to your agent** to copy the natural-language setup prompt, then paste it into your coding agent. Agents connected over MCP already have them as prompts (see above).

| Skill                  | Description                                          | API |
| ---------------------- | ---------------------------------------------------- | --- |
| `cro-optimizer`        | Live funnel analysis + scored A/B test hypotheses    | Yes |
| `ab-test-generator`    | Generate & launch no-code split tests from analytics | Yes |
| `heatmap-analyst`      | Click, scroll & rage-click friction analysis         | Yes |
| `revenue-attributor`   | Ad spend to Stripe revenue, ROAS + reallocation      | Yes |
| `funnel-reporter`      | End-to-end SaaS funnel reporting                     | Yes |
| `page-cro`             | 10-point landing page conversion audit               | —   |
| `email-sequences`      | Onboarding, nurture & re-engagement drips            | —   |
| `seo-strategist`       | Keyword research, gaps, on-page + technical SEO      | —   |
| `marketing-strategist` | Funnels, GTM, positioning, growth strategy           | —   |
| `copywriting`          | Conversion copy for pages, emails & ads              | —   |
| `ad-expert`            | Paid ads: Meta, Google, TikTok, LinkedIn             | —   |
| `content-strategist`   | Articles, newsletters, social, video, SEO            | —   |

Skills chain together with natural-language prompts:

| Prompt                                        | Chain                                                      |
| --------------------------------------------- | ---------------------------------------------------------- |
| "Find my worst-performing page and fix it"    | CRO Optimizer → Page CRO → A/B Test Gen                    |
| "Weekly performance report + recommendations" | Funnel Reporter → CRO Optimizer                            |
| "Cut my worst ad & replace the landing page"  | Funnel Reporter → CRO Optimizer → A/B Test Gen → Ad Expert |

Browse the full directory at [humblytics.com/skills](https://humblytics.com/skills).

### REST API reference

The **REST reference** tab shows an example `curl` request against `/traffic/summary` with an **Env var / Literal** toggle. Always use Env var mode for committed commands — Literal is for one-off testing only.

Click **Run test call** to fire a live request against your selected property and confirm the connection returns a 200 OK.

The endpoint reference is grouped by the CRO loop:

| Group       | Tagline                               |
| ----------- | ------------------------------------- |
| **Read**    | Analytics, recommendations & heatmaps |
| **Decide**  | Funnels & split-test results          |
| **Ship**    | Split-tests & variants                |
| **Onboard** | Properties & connectors               |

***

## Security

**OAuth flow**: the key is generated server-side and stored by your agent in its own MCP config. It never appears in conversation or version control — your agent handles it automatically after the one-time authorization.

**Manual key setup**: if you configure the key via `claude mcp add` or a config file, it is embedded in your agent's MCP server registration and handled automatically after that. If you call the API directly from scripts or CI, store your key in a `.env` file listed in `.gitignore`. Never commit the literal value.

Either way: never paste a key into chat, `CLAUDE.md`, `AGENTS.md`, or any committed file. Revoke keys you no longer need.

***

## Related

* [Set up with your AI agent](https://docs.humblytics.com/how-to-get-started/set-up-with-your-ai-agent.md) — step-by-step connection guide per app
* [External Analytics API](https://docs.humblytics.com/external-analytics-api.md) — full analytics endpoint reference
* [Split Testing API](https://docs.humblytics.com/split-testing-api.md) — programmatic A/B testing
* [Agent Onboarding API](https://docs.humblytics.com/agent-onboarding-api.md) — sign up users and add websites from an agent
* [Ads Attribution API](https://docs.humblytics.com/ads-attribution-api.md) — per-campaign funnel attribution
* [humblytics-marketing-skills on GitHub](https://github.com/Humblytics/humblytics-marketing-skills) — open-source agent skills repo
