Heading MCP

The Heading MCP puts your Heading data into any AI tool that speaks the Model Context Protocol (MCP). Connect it once, then ask in plain words: which prompts are we losing, what does ChatGPT say about us, which sources does it cite, how are we described next to our competitors. It can also make changes for you: add and pause prompts, file tasks, update context documents, track a competitor.

The tools call the same code as the dashboard, so a figure in your AI tool and the same figure on a dashboard page cannot disagree.

The address

https://mcp.useheading.com/mcp

It is a remote MCP server over Streamable HTTP. There is nothing to install or run on your machine.

Two ways to connect

Both give you exactly the same tools. They differ in who the connection belongs to.

Sign in with Heading (OAuth). Your client opens Heading in a browser, you sign in and approve it once, and the client holds a token from then on, refreshing it on its own. There is nothing to create, paste or rotate. Use this when a person asks questions in an AI tool. A sign-in connection belongs to you: it reaches every brand you can open in the dashboard, in every team you belong to. If you are a team member rather than an owner or admin, that is only the brands you have been given.

An API key. A key you create under Settings → API in the dashboard and send as Authorization: Bearer hdg_sk_live_…. Use it where no browser is available, such as a script or a scheduled job, or in a client that cannot sign in. A key belongs to a team and reaches every brand in the team that is on a paid plan or a trial. Each key has an access level, chosen when you create it: a Read key can call every tool and is refused every change; a Write key can also make changes.

Scopes and consent

Your client decides which scopes it asks for. The consent screen lists what it asked for, and you approve or deny all of it at once. Heading has two scopes, and the consent screen describes them in these words:

• mcp:read: "Read your brands, prompts, visibility, responses, sources, competitors, perception and audits."
• mcp:write: "Make changes for your brands: tracked prompts, tags, saved views, competitors, brand settings, context docs, tasks, plans and objectives, and pulling prompt candidates, which can spend credits."

Write access needs a client that asks for mcp:write. A client that names no scopes gets the default set, which leaves mcp:write out. A connection without mcp:write can read everything and change nothing: a change answers forbidden, naming the missing scope. To add write access, connect again from a client that asks for mcp:write, and approve it.

You can see every connected tool, and disconnect any of them, under Settings → API. A disconnect takes effect on the tool's next request.

Who a change is made as

Every change is made as a person, and the dashboard's own rules apply to that person on every call:

• A sign-in connection changes things as you.
• A Write key changes things as the team member who created it. Heading reads that person's membership and role again on each call. When they leave the team or lose the access a change needs, the key stops making changes; create a new one.

So a team member can change only the brands they have been given, and a change only owners and admins may make in the dashboard (the competitor set, tags, tag folders, saved views and some brand settings) is refused to everyone else. Each change is recorded where the same change made in the dashboard is recorded, naming the person, and the key when one was used.

Which brands you can reach

Brands on a paid plan or a trial. A brand on the free tier does not appear in list_brands and cannot be reached by any tool.

A brand you cannot reach answers Brand not found. Another team's brand, a free brand, a brand outside your access and an id that never existed all answer the same way. The answer never says which.

Start here

1. Install it in your AI tool.
2. Ask your assistant to list your Heading brands. That calls list_brands, which every conversation starts with: every other tool takes a brandId from it.
3. Ask a question about one brand, for example: "Using Heading, how has Acme's visibility moved over the last 28 days, and which competitor gained the most?" The assistant calls get_visibility_report with compare on, then with breakdown: ["brand"] for the competitors.
4. Go to the evidence: "Show me last week's ChatGPT answers, and which of them did not name us." That is list_answers filtered to ChatGPT; the assistant reads mentioned: false on each answer that does not name the brand, and get_answer reads any one answer in full.

In this section

• Install: step by step for Claude, Claude Code, ChatGPT, Cursor and VS Code.
• Tools reference: every tool, its arguments, what it returns and an example call.
• Metrics: what each figure means, and the rules every figure follows.
• Writes and limits: how changes work, the rate limit, credits and errors.

When something is wrong

The client says the server refused to connect. With a key, check the Authorization header reaches the server: a missing header, a malformed one and a revoked key all answer 401. With a sign-in connection, check it was not disconnected under Settings → API, and connect again if it was.

The client says the server does not support sign-in. It is pointed at the legacy address, https://useheading.com/api/v1/mcp, which takes API keys only. Use https://mcp.useheading.com/mcp.

A token stopped working after an hour. Access tokens are short-lived and your client refreshes them on its own. If it cannot, connect it again once.

list_brands comes back empty. The connection works, and no brand it reaches is on a paid plan or a trial. With a sign-in connection, check you can open the brand in the dashboard. Then check the brand's plan under Billing.

A change answers forbidden. The answer says why: a Read key, a sign-in without mcp:write, a key whose creator has left the team, or a change only owners and admins can make.

MCP or the REST API

The REST API reads the same measurement under the same rules, and is read only. Use the MCP when a person works with Heading through an AI tool, and when you want changes made. Use REST when a program moves data on a schedule.