> 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 **MCP & API Access** page connects your AI coding agents to live Humblytics data. Open it from the sidebar under **Data → API**.

> **MCP server URL**: `https://mcp.humblytics.com/v1` **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 any compatible AI agent live, read-write access to your analytics. It is live and available to all Plus accounts and above.

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

Once connected, your agent can query live data, identify test opportunities, and launch experiments — without you having to copy-paste numbers. Works with Claude Code, Cursor, Codex CLI, and any agent that supports remote MCP servers (\~36 tools, no property lock-in).

To get started, click **Setup Humblytics MCP** on the page. This opens the key creation dialog and walks you through generating a key and copying the setup prompt for your agent.

***

## API keys

API access requires the **Plus** plan or higher. 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.

### Property keys

Property keys are scoped to a single property. Switch to the correct property using the site selector before creating one. These are useful when you want to isolate a key to a specific site.

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

***

## Setting up MCP with your agent

Click **Setup Humblytics MCP** (or **Create** next to Account Keys) to open the key creation dialog. After the key is created, the dialog shows your MCP setup prompt with the key already filled in.

Select your agent type using the tabs — **Claude Code**, **Codex CLI**, or **Generic** — and copy the setup prompt.

### Claude Code

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

For a property-scoped connection, the prompt also includes:

```
  --header "X-Humblytics-Property-Id: YOUR_PROPERTY_ID"
```

### Codex CLI

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

### Generic

For any other agent that supports remote MCP servers, the prompt provides the server URL and the headers to send:

```
URL: https://mcp.humblytics.com/v1
Authorization: Bearer YOUR_API_KEY
X-Humblytics-Property-Id: YOUR_PROPERTY_ID
```

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

***

## Marketing skills & REST API

The **Skills, REST API & reference** section (collapsed by default) gives 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.

| 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 API Reference** card 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

**MCP setup**: the key is embedded in your agent's MCP server registration (e.g., the `claude mcp add` command). After that, just ask your agent — the key is handled automatically and never appears in conversation.

**REST API**: 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

* [External Analytics API](/external-analytics-api.md) — full analytics endpoint reference
* [Split Testing API](/split-testing-api.md) — programmatic A/B testing
* [Agent Onboarding API](/agent-onboarding-api.md) — sign up users and add websites from an agent
* [Ads Attribution API](/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