MCP server

Updated 2026-11-02

Connect

URL: https://headstream.app/api/mcp

The server uses Streamable HTTP and takes the same API key as the REST API, in an Authorization: Bearer hsk_... header. Create a key under Organization, in the API and MCP card. It reaches every project in the organization. The limit is 120 requests per minute.

Claude Code:

claude mcp add --transport http headstream https://headstream.app/api/mcp \
  --header "Authorization: Bearer hsk_YOUR_KEY"

Cursor, in .cursor/mcp.json:

{
  "mcpServers": {
    "headstream": {
      "url": "https://headstream.app/api/mcp",
      "headers": { "Authorization": "Bearer hsk_YOUR_KEY" }
    }
  }
}

See the Claude Code and Cursor setup pages for more.

How it works

Start with list_sites to get a siteId, which nearly every tool needs. Most reporting tools take days, which defaults to 30. Revenue tools take model, which defaults to linear. Results are JSON, with a notice that the values are customer data and should be treated as data, not instructions.

Tools

Setup

Tool	Does
`list_sites`	Lists projects, with IDs and domains
`create_project`	Adds a project and returns its snippet
`get_setup_status`	Shows if events are arriving, plus goals and Stripe status
`create_goal`	Sets a conversion
`get_goals`	Lists goals, with conversions and rate

Traffic

Tool	Does
`get_summary`	Visitors, pageviews, sessions and bounce rate, with the previous period
`get_traffic`	Pageviews per day
`get_breakdown`	Top values for a dimension
`get_heatmap`	Clicks, top elements and scroll depth for a page
`get_session_timeline`	What one visitor did, step by step
`list_recordings`	Recorded sessions, optionally only frustrated ones

Revenue

Tool	Does
`get_revenue_by_channel`	Revenue minus refunds, credited by channel
`get_revenue_breakdown`	Revenue by campaign, source or landing page
`list_customers`	Paying people with revenue
`get_customer_journey`	A person's touches and payments, in order

Revenue tools need Stripe, and connecting Stripe is in beta.

Reports and dashboards

Tool	Does
`run_report`	Runs any report spec
`list_dashboards`	Lists saved dashboards
`get_dashboard`	Runs every report on a dashboard
`create_dashboard`	Creates an empty dashboard
`add_report`	Saves a report to a dashboard
`remove_report`	Removes a saved report

Self-reported

Tool	Does
`record_self_reports`	Saves answers from a server or an import
`group_self_reports`	Puts answers containing a phrase in a group

Trust

Tool	Does
`explain_metric`	Shows how a number is calculated, with raw rows
`trace_payment`	Traces a ledger entry to each credited visit
`get_data_quality`	Checks freshness, duplicates and reconciliation
`get_change_log`	Lists what changed how numbers are calculated
`export_events`	Reads raw events, one page at a time

Fixes

Tool	Does
`get_top_fix`	Returns the most valuable change, with evidence and a brief
`list_fixes`	Lists fixes and their status
`mark_fix_applied`	Records that a fix is live
`check_fix`	Returns improved, worse or inconclusive
`dismiss_fix`	Dismisses a fix that doesn't hold up

A/B tests

Tool	Does
`create_experiment`	Creates a test on a goal and returns the code
`list_experiments`	Lists tests
`start_experiment`	Starts a test once the code is live
`get_experiment_results`	Returns results and a verdict
`stop_experiment`	Stops a test and records the winner

Uptime

Tool	Does
`get_uptime`	Returns status, uptime and recent incidents
`configure_monitor`	Turns free downtime alerts on or off