Heading MCP
Attach Heading to Claude Code, Cursor, or any MCP client and read your visibility data where you already work
Heading MCP puts the same data the dashboard shows into the AI tool you already use. Attach it once, then ask questions in Claude Code, Cursor, or anything else that speaks MCP: which prompts are we losing, what is ChatGPT actually saying about us, which sources does it cite, how are we depicted next to our rivals.
It is the same read contract as the REST API, over a different transport. Nothing you can read here is anything you could not already read there. The tools call the same functions the dashboard calls, so an answer in your terminal and a chart in the app cannot disagree.
Read only. No tool creates, changes, or deletes anything in Heading, and there is no write tool to enable. How you connect makes no difference to the tools you get: a Write key, a Read key and a sign-in connection all see exactly the same set.
Every tool says so in its own listing, as the MCP annotations readOnlyHint: true and openWorldHint: false. A client that reads them can run a Heading tool without stopping to ask you to approve a call that cannot change a row, and without treating it as a call out to the wider web: each tool reads your Heading data and nothing else.
Before you start
The endpoint is the same for everyone:
https://mcp.useheading.com/mcpHeading MCP used to be published at https://useheading.com/api/v1/mcp. That address still works with an API key and your existing configuration keeps running, so there is nothing you have to change today. New setups should use mcp.useheading.com, which is also the only address that accepts a sign-in connection.
You can connect two ways, and they read the same data through the same tools.
Sign in with Heading. Your client sends you to Heading in a browser, you approve it once, and it holds a token from then on. Nothing to create, nothing to paste, nothing to rotate. Use this when a person is asking questions in an AI tool.
An API key. A single credential you create and store yourself. Use this when a program runs unattended, in CI or on a schedule, where there is no browser and nobody to approve anything.
One difference is worth knowing before you choose. A key belongs to a team, so it can read every paid property in that team. A sign-in connection belongs to you, so it reads what you can read: every paid property in every team you belong to if you are an owner or admin, and only the properties you have been given if you are a member. If your team restricts who sees which properties, the sign-in connection keeps those restrictions and a key does not.
Connect by signing in
Point your client at https://mcp.useheading.com/mcp with no credential. It will open a browser, ask you to sign in to Heading if you are not already, and show you what it wants to read. Approve it once.
claude mcp add --transport http heading https://mcp.useheading.com/mcpRun /mcp and follow the authentication prompt. After you approve, heading shows as connected with its tools listed.
Add the server to ~/.cursor/mcp.json for every project, or .cursor/mcp.json for one:
{
"mcpServers": {
"heading": {
"url": "https://mcp.useheading.com/mcp"
}
}
}Enable heading under Settings → MCP and complete the sign-in prompt.
Point the client at the endpoint as a remote MCP server over Streamable HTTP, with no credential. Heading answers 401 with a WWW-Authenticate header naming its protected resource metadata, and the client takes it from there: it registers itself, sends you to sign in, and receives a token.
Nothing needs to be arranged with us first. There is no client ID to request and no application to register by hand.
You can see every tool you have connected, and disconnect any of them, from Settings → API in the dashboard. Disconnecting takes effect on the tool's next request.
Connect with an API key
Create the key from Settings → API in the Heading dashboard. Keys use the hdg_sk_live_ prefix and are shown once, at creation. Store the key in your environment or your client's secret store, not in a file you commit.
Add it from the command line:
claude mcp add --transport http heading https://mcp.useheading.com/mcp \
--header "Authorization: Bearer $HEADING_API_KEY"Or commit a project-scoped .mcp.json and keep the key in the environment:
{
"mcpServers": {
"heading": {
"type": "http",
"url": "https://mcp.useheading.com/mcp",
"headers": {
"Authorization": "Bearer ${HEADING_API_KEY}"
}
}
}
}Check it attached with /mcp. You should see heading connected, with its tools listed.
Add the server to ~/.cursor/mcp.json for every project, or .cursor/mcp.json for one:
{
"mcpServers": {
"heading": {
"url": "https://mcp.useheading.com/mcp",
"headers": {
"Authorization": "Bearer hdg_sk_live_your_key_here"
}
}
}
}Then enable heading under Settings → MCP.
Point the client at the endpoint as a remote MCP server over Streamable HTTP, and have it send:
Authorization: Bearer hdg_sk_live_your_key_hereThere is no session to establish. Every request carries the key.
Your first question
Find your properties
Every tool except list_properties needs a propertyId, and list_properties is where those ids come from. Ask your assistant to list your Heading properties, or call the tool directly.
{
"properties": [
{ "id": "…", "name": "Acme Dental", "domain": "acmedental.com" }
],
"total": 1
}Ask about one of them
"Using Heading, how has Acme Dental's visibility moved over the last 28 days, and which competitor gained the most?"
The assistant will call read_visibility_summary and read_leaderboard and answer from the returned figures.
Go to the evidence
"Show me the ChatGPT answers where we were not mentioned last week."
That is read_platform_responses, which returns the answers verbatim. Every score in Heading is computed from these, so this is where a disagreement gets settled.
What you can read
Sixteen read tools, plus list_properties. Every tool takes a required propertyId. Each one also carries a label your client may show instead of its name, so read_visibility_series appears as Visibility over time.
| Tool | What it returns |
|---|---|
list_properties | The properties this key can read: id, name, domain. The scoping handle every other tool needs. |
read_visibility_summary | Headline visibility over a day range: the overall percentage, the per-platform split, prompts and answers measured, and the delta against the prior period. |
read_visibility_series | The day-by-day visibility series, optionally for one platform. Use it to locate when a shift happened. |
read_leaderboard | You and every tracked competitor, ranked by share of AI answers. |
read_platform_responses | The AI answers themselves, with the prompt, the platform, the day, whether you were mentioned, and the cited sources. |
read_prompts | The prompt portfolio: text, status, quality score, latest visibility, volume, tags. |
read_prompt_portfolio | The portfolio as its composite score measures it: each balance factor's score, numeric target, and which side of the target the active set sits on, plus the prompt lists and the tracked-prompt quota. |
read_prompt_changelog | What changed in the tracked prompt set, one net diff per UTC day, with the active prompt count after each day. |
read_confidence | How well Heading understands the business, as last assessed from its context documents: per-dimension coverage, weakest first, each with the questions that would deepen it. |
read_context_docs | The property's context documents — the curated knowledge base Heading's own pipelines read for brand facts. |
read_competitors | Tracked competitors, their share next to yours, and the prompts where they appear and you do not. |
read_cited_sources | The domains and URLs AI cites when it answers about your market, with how often and whose they are. |
read_perception | How AI depicts each brand across the qualities measured for your category, and which of them a rival occupies and you do not. |
read_outcomes | Leads recorded through the property's inbound webhook, alongside the visibility they sit next to. |
read_tasks | The property's task board and its live plans: each task's status, priority, assignee, due day and plan, and each plan's linked objective and open-task count. |
read_research | What this property has looked up in the index of AI answers, and the rows of one cached result: the indexed prompts with their AI search volume, which brands each answer names or cites, the brand leaderboard and the most-cited domains. An indexed prompt is not a tracked prompt. |
read_agent_readiness | The latest Agent readiness Run over the property's own website: each Probe's outcome, the URL it read, the observations behind it, and what to do when it fails. The one tool that measures your site rather than what AI says about it. |
Ranged tools take startDay and endDay as UTC calendar days (YYYY-MM-DD). Both are optional; leave them out for the last 28 days. List tools take limit and offset.
Rules worth knowing before you ask
Paid properties only. A property on the free tier does not appear in list_properties and cannot be read by any tool. Asking for it by id answers Property not found. This is the same rule the REST API applies, and it is deliberate: a property the key cannot see does not exist through the API, so key scope and payment state are not something an outsider can probe.
A property that is not yours answers the same way. Another team's property id, a free property, a cancelled one, and an id that never existed all return Property not found. The message never says which.
Dates are UTC, everywhere. There are no user timezones anywhere in this data. A day is a UTC calendar day.
A range cannot open before your daily tracking did. Daily collection starts on the day the property's subscription starts. Anything before that is point-in-time snapshot data, measured over a different prompt set, and plotting the two together reads as a collapse that never happened. So a range that starts earlier comes back shorter, with a note saying which day it opens on. That is a shorter history, not missing data.
Scores mean the active prompt set. Visibility is measured over the prompts being tracked on the day. If a score moved, read_prompt_changelog is where you find out whether the measurement changed rather than the performance.
Rate limits
100 requests per minute per API key. Each tool call is one request, and so is listing the tools.
Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Over the limit you get a 429 with Retry-After, in the same error shape as every other failure.
Ask for what you need. A tool that returns a list pages by default, and asking for a 90 day range of verbatim answers will fill your context long before it troubles the rate limit.
When something is wrong
The client says the server refused to connect. On a key, check the Authorization header reaches it: a missing header, a malformed one, and a revoked key all return 401. On a sign-in connection, check it has not been disconnected in Settings → API, and reconnect if it has.
The client says the server does not support authentication. It is pointed at https://useheading.com/api/v1/mcp, the legacy address, which takes API keys only. Sign-in connections work at https://mcp.useheading.com/mcp.
A token stopped working after an hour. It was meant to. Access tokens are short-lived and your client refreshes them on its own; if it cannot, reconnect it once and it will hold a refresh token from then on.
list_properties comes back empty. The connection is valid, and no property it covers is on a paid plan. On a key, check the key's property scope in Settings → API. On a sign-in connection, check you can open the property in the dashboard — if you are a team member rather than an owner or admin, you see only the properties you have been given. Then check the property's plan in Billing.
A tool answers Property not found. for a property you can see in the dashboard. Either the connection is scoped to other properties, or the property is on the free tier. Both look the same from here, on purpose.
A range came back shorter than you asked for. The answer includes the day daily tracking began. Nothing was lost.
Which one should I use
Heading MCP and the REST API read the same data under the same rules. Use MCP when a person is asking questions in an AI tool. Use REST when a program is moving data on a schedule. There is no reason to pick one and stop using the other.