MCP server
Connect Claude Code, Codex or any MCP client to your workspace, and let it read what Recomma measures.
Recomma speaks MCP, so an assistant can read your workspace directly: what the models say about your brand, the chats themselves, which sources they lean on, the action queue, and what your category is worth.
The interesting half is the last one. An assistant sitting in your own repository can ask which audit rules your site fails, get the pages and the markup to change, and make the change — without you copying anything out of a dashboard.
Reads by default, writes only when you say so, and inside one workspace
Every tool calls the same procedures this product’s own screens call, so a connection sees exactly what the person who made it sees, and nothing from another workspace. Reading is what a connection gets. Writing — proposing questions, pausing them, moving tickets — is a second permission you grant separately, and every write previews before it applies. Nothing can delete, and nothing starts sampling without saying first what it will cost.
Connect
The server lives at https://api.recomma.ai/mcp. There are two ways to
authenticate, and clients differ in which they prefer.
The shortest way in is Open in, in the header of every page. It opens Claude or ChatGPT with the prompt already in the box, or copies a prompt written for Claude Code, Codex, Gemini CLI or any other agent. Either way the assistant connects, signs you in, confirms it can see the brand you had open, says what it can do, and asks what you want — a brief, a client report, watches, a fix. The same prompt is in the command palette (⌘K).
Otherwise Settings → Connect AI lists the clients: pick yours — Claude, ChatGPT, VS Code, Claude Code, Codex, Windsurf, Gemini CLI — and it gives you that client’s shortest path, a one-click install where there is one. For any other agent that can run a command or edit a file — Cursor, Cline, Zed, one of your own — Any other agent gives you a prompt to paste into it; the agent sets itself up and asks you to sign in. The steps stay reachable after you connect, for a second machine or a teammate. The same page lists every app you have connected and disconnects one at once.
With your account
claude mcp add --transport http --scope user recomma https://api.recomma.ai/mcpThe first call opens a browser, you sign in as normal, and a screen says what is being connected and what it may read. Approving it returns the client to its own callback with a token. The app then appears under Settings → Connect AI → Connected apps, where disconnecting it stops its very next call.
A token acts as you, in the workspace you last had open in the app. If you belong to several, switch in the app and the connection follows on its next call — there is no separate workspace setting to keep in step.
The screen lists what is being asked for. recomma:read is what every
connection needs and is refused without; recomma:write lets it suggest and
pause prompts and move tickets. The server’s challenge names both, so a client
asks for both, and the screen shows writing as Allow changes, ticked —
untick it and the connection can only read. A request that includes
recomma:write always shows the screen, even from a client that did not ask
for one. A token that carries only identity scopes is refused with a challenge
naming what was missing; a token that may only read and calls a tool that
writes gets a 403 naming both scopes, which a client that supports it turns
into a second approval. One that does not: disconnect it and connect again
with Allow changes ticked.
With a key
For a CI job, an automation like n8n, or any client with no browser to open. Make a key in Settings → Connect AI → API keys; the secret is shown once, along with the config to paste it into.
claude mcp add --transport http --scope user recomma https://api.recomma.ai/mcp \
--header "Authorization: Bearer recomma_YOUR_KEY"export RECOMMA_API_KEY=recomma_YOUR_KEY
codex mcp add recomma --url https://api.recomma.ai/mcp \
--bearer-token-env-var RECOMMA_API_KEYA key issued before the product was renamed starts plinth_ and still
works — nothing about it changed but the prefix on new ones, so there is no
need to rotate a key that is already in a CI secret.
x-api-key works too, for clients that spell it that way. A key belongs to
one workspace, acts as the person who made it, and stops working the moment it
is revoked.
A key can only read unless Allow this key to write was switched on when it was made. It is off by default, every time: a key is the credential most likely to end up in a log or a pasted snippet, and one that can only read cannot break anything. The keys list marks the ones that can write.
The tools
Every tool takes brandId, which comes from list_brands. Shares are
fractions between 0 and 1, money is US dollars per month, and every rate
carries the number of chats it was measured over.
| Tool | What it answers |
|---|---|
list_brands | Which brands this connection can see, and their ids |
get_visibility | How often the models name you, against your rivals, over a window |
get_trend | Which way that is going: a point per day, the window before, and what moved among the sources |
list_prompts | The tracked questions, worst first — where you are losing |
get_prompt | One question in full: its history, how every rival stands on it, what its answers cite, the latest answer per engine |
read_answers | The chats themselves: previews, or one answer in full. you: "named" or "unnamed" keeps only the answers that named the brand, or only those that did not |
list_sources | The sites the chats lean on, and whether they ever name you. you: "unnamed" lists only the ones that never do |
get_source | One site or one page: which questions reach for it, on which engines, and the page’s own words |
list_actions | The work queue, ranked by impact, with a rough effort (low, medium, high) that breaks ties between equal impacts |
get_action | One ticket with its evidence: the questions it would move, the source’s pages, or the rule and the failing markup — and its history, the earlier tickets on the same subject and whether they worked |
get_impact | What the finished work moved: the brand’s line, a verdict per closed ticket with the AI visits and key events its pages took in Google Analytics, and a track record per kind of work |
get_site_findings | Which audit rules your own site fails, with the markup to change |
get_market | What your category is worth, how much of it you cover, how much names you |
get_keywords | The priced keywords behind that figure |
get_referrals | The people an assistant actually sent, from your own Google Analytics: sessions and conversions against the window before, the landing pages, and the channels AI can hide in |
get_brief | What changed between two windows, ranked, each item with the call to make next. The usual first call after list_brands |
get_setup | What a brand still needs before its figures mean much — a plan, engines, questions, enough answers, rivals, the site, Google Analytics, a watch — and for each step, whether the agent can take it or a person must, and where |
get_fix_packet | A ticket as work another agent can carry out: tasks with pages and markup, what it is measured by, and the calls that prove it is done |
check_page | One page of your own site, read now and audited: which rules it fixed, still fails and newly breaks |
get_report | A client-ready report on any period, in Markdown, one self-contained HTML page or JSON; your commentary and branding, Recomma’s figures |
list_watches | The watches on a brand, where they send, and whether deliveries land |
list_events | What the watches raised, read with a cursor |
The list_* tools are the tables; each get_* beside one is the page a row
opens onto. An assistant reads down the same way a person does: the queue,
then the ticket; the sources, then the page.
list_brands also says what the connection was granted — scopes, and
canWrite — so a client can plan around what it may do rather than discover
it from a refusal.
The tools that write
Seven more, each needing recomma:write:
| Tool | What it does |
|---|---|
create_prompts | Proposes questions. They land as Suggested on the Prompts page; nothing is sampled until a person accepts them |
set_prompt_status | Activates or pauses questions. Activating starts sampling, so the preview prices it and refuses the large cases |
set_action_status | Moves a ticket: in progress, done, dismissed, back to open. Done freezes the reading the re-measure is judged against |
suggest_prompts | Has the product write questions itself — from the priced demand no question reaches, or from the brand — and files them as Suggested |
create_watch | Asks to be told when something changes; checked after every pass, delivered to a signed webhook and the event feed. See Recomma for agents |
delete_watch | Stops a watch. The events it raised stay in the feed |
send_test_event | Sends a test through a watch now and returns what the receiver answered |
They share three rules:
- Preview first. Every write tool that changes prompts or tickets except
suggest_promptspreviews by default: the answer says what would change and changes nothing. Passapply: trueto act.suggest_promptshas no preview because the proposals are the preview — they wait for a person either way. - Nothing deletes. A question is paused, never removed; a ticket is dismissed, never removed; a finished ticket is never re-finished or reopened, because the reading frozen when it was marked done is the one it keeps. Anything destructive is done by a person in the product.
- Spending is said out loud, and capped. The only write that spends is activating questions. Its preview says how many would start and roughly what that is per week; a call that would take more than half of what the plan has left is refused and sent to a person on the Prompts page, however it is asked.
Workflows and the glossary
A client that lists prompts is offered six ready-made workflows — a weekly brief, diagnosing a drop, how the rivals win, an audit of the prompt set, a site fix plan, and whether finished work paid off. Each arrives with the brand filled in and names the tools to call in order and how to read what comes back.
Even without picking one, every connection starts with a short set of
instructions: begin from list_brands, quote a rate with its sample, compare
windows rather than days, and write only when asked.
Two resources travel with them: recomma://glossary, every term the tools use
and the field names they use for it, and recomma://methodology/market, how
the market figures are computed and what they are not. They are the docs
pages you are reading, extracted at build time, so the two cannot drift.
Following a figure down
Some questions, and the tools that answer them:
| Ask | Tools |
|---|---|
| “What happened to our visibility this month?” | get_trend — the daily points, the window before, and the delta only when both are readable |
| “Why did we drop on Perplexity?” | get_trend with engine, then list_prompts for the questions that fell, then read_answers for what changed |
| “Which sites keep getting cited without naming us?” | list_sources with silentOnly, then get_source for who they do name and what the page says |
| “Is this ticket worth doing?” | get_action — the questions it targets and how you do on each, or the rule and the pages failing it |
| “Did the work we finished last month change anything?” | get_impact — a verdict per closed ticket, or pending with the date it becomes one |
| “Does any of this turn into visitors?” | get_referrals — sessions an assistant sent and what they did, with state: disconnected rather than zeros until a Google Analytics property is connected |
Reading the answers
read_answers without a runId returns recent chats as previews, each with
the brands it named in order, what it cited, and its runId. Pass one of those
back as runId and you get that chat whole — cut at maxChars, with
truncated: true when it was cut, so a shortened answer is never mistaken for
a complete one.
Acting on your own site
get_site_findings with no rule lists every rule the site currently fails
and how much of the site has been read. With a rule it returns why the rule
exists, the pages that fail it, and for each one the markup as it is beside
what it should be — which is enough for an assistant to make the change in your
repository.
What the figures mean
The tools carry the product’s rules with them, and an assistant reading them should carry them too:
- A rate without its sample is not a reading. Every figure ships with
sampleN. Below about twenty chats a percentage moves several points on one answer — see when a figure is a reading. - Absent is not zero. A prompt nothing has sampled has
visibility: null; a project with no keyword pool getsstate: "missing"rather than a market worth nothing; a window with no answers in it isprevious: null, never a row of zeros that reads as a rise from nothing. - A day is noise; a week is a reading.
get_trendandget_impactmark each daily pointreliableor not. Read the direction over a week rather than the gap between two days. - A verdict that has not been measured is not a verdict. A ticket in
get_impactsayspendingordueuntil it has been re-measured. Neither means “no change”. - Nothing is fetched on demand.
get_sourcereturns a page’s words only when the crawler has already read it, and says so when it has not. - Money and shares are never multiplied.
get_marketgives a category value and, separately, the share of it the answers name you in. There is no “value captured” figure, because being named in an answer is not a click.
Limits
Lists are capped and default small — a client’s context is the scarce resource,
not the database. Every list tool takes limit and offset, and returns a
page alongside its rows:
{ "offset": 0, "limit": 20, "total": 57, "nextOffset": 20 }Pass nextOffset back as offset for the next page; it is null on the
last one. total is the count the page was drawn from — after any filter the
tool applied. The tools return what the screens show rather than an export of
everything behind them.
Reading spends nothing: the read tools return chats that have already been sampled, and adding a connection does not change what a project costs. Of the write tools, only activating questions spends, and it says so before it does.