Skip to content
MCP server · remote

Query your measurement
data from Claude

The Serge MCP server connects Claude, Cursor, or a backend integration to your workspace. Nine operations read measurement and install data. The only write, create_site, registers a domain idempotently and succeeds only with an API key carrying sites:write.

Connection guideGitHubDeveloper hub
Jump
Connect in minutes

Use OAuth for read-only questions, or mint a scoped API key for read-only access or site provisioning.

Jump
Scoped by credential

Nine operations are read-only. Only create_site writes, and it requires an API key with sites:write.

Jump
Ten focused tools

Nine read operations cover setup and measurement; one idempotent operation registers a site.

Connect your client

Two ways to authenticate. Pick one — you do not need both.

Option A — API key

Mint an API key in Settings → API keys. For measurement, grant traffic:read. For AgentSolo provisioning, choose the preset that grants exactly sites:write + traffic:read.

Add this to your client config. The Claude Desktop config path is below; Cursor uses the same shape under its MCP settings.

macOS ~/Library/Application Support/Claude/claude_desktop_config.json
Windows %APPDATA%\Claude\claude_desktop_config.json

Restart your client. The Serge tools appear in the tool picker.

Option B — OAuth connector

In Claude, add https://mcp.serge.ai as a custom connector and sign in with your Serge account. Claude walks the OAuth flow and binds the connection to your workspace — no API key to paste or rotate.

OAuth remains read-only: it can inspect sites and measurement, but it cannot call create_site. Automated provisioning requires an API key with sites:write.

Tools your client receives

Ten workspace-scoped tools: nine read operations and one idempotent write, create_site. Your client picks the right one from the task.

list_sites

List the sites registered under your workspace, with their domains and IDs. Start here when you're unsure which domain a tool expects.

create_site

Register a tenant domain and return its existing or newly created site ID, public token, and ready-to-paste snippet. This is the only write tool; retries are safe and it requires sites:write.

check_install

Check matching-Origin ingest telemetry. Heartbeats confirm request acceptance, not browser execution or ownership; reject Origins are unverified public claims.

get_traffic_overview

Summarize AI-assistant traffic on a site over a window: sessions, platforms (ChatGPT, Claude, Perplexity, Gemini), outcomes, and top entry pages.

get_purpose_split

Split assistant sessions into buy-intent, informational, and crawler traffic, so you can tell real customer demand from bots.

get_traffic_sources

Break down AI-assistant and tagged acquisition sources over a selected period, using the same first-party session instrument throughout.

get_verification_breakdown

Show, per platform, how many sessions were verified by either a valid HTTP message signature or a source IP in the vendor's published range, versus only self-declared.

find_failing_sessions

List sessions classified as abandoned or as a short single-page bounce, with entry/exit pages and timing. These labels do not identify a cause or prove a task was attempted.

get_session_journey

Drill into one session — its page-by-page path, time per page, interactions, and outcome.

whoami

Confirm which workspace and scopes the connection has. Call this first when a tool can't see your data.

Scopes

An API key carries explicit scopes. Keep provisioning keys narrow; scope grants are fixed at creation and changed by rotating to a replacement.

traffic:readAllows the eight install and measurement reads. whoami remains available on any authenticated connection.
sites:writeAllows create_site to register domains in this workspace. Grant it only to a trusted server-side provisioner.

OAuth grants read scopes only. It can use the nine read operations, but never create_site; provisioning needs an API key with sites:write.

Example prompts

Paste these into your connected client. It maps each to the right tool and fills in the rest.

Which AI assistants sent traffic to yourstore.com this week?

What share of assistant traffic on yourstore.com was real buy-intent versus crawlers in the last 7 days?

Show me the sessions on yourstore.com classified as abandoned or a short bounce, with their entry and exit pages.

Which platforms were verified on yourstore.com by a valid HTTP message signature or a vendor-published source IP range, and which only declared themselves?

Troubleshooting

A tool can't see your data

Ask your client to call whoami. For measurement it should show traffic:read. For AgentSolo provisioning it must show both sites:write and traffic:read.

site_not_found

The domain is not registered under your workspace, or it was typed differently. Read-only connections should call list_sites; a provisioning key can call create_site, install the returned snippet, then call check_install.

How it fits with Serge

Nine MCP operations read the same install and measurement data you see in Serge. The tenth, create_site, is a narrow provisioning operation for trusted backends and requires its own write scope.

Serge supports one managed ad workflow today: ChatGPT through your own OpenAI ads account. The MCP server exposes your separate first-party measurement data, including recorded sessions and supported acquisition markers; it does not expose OpenAI's platform report or campaign status.

Next

→ Open the step-by-step connection guide→ Open the developer hub