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.

With your account

claude mcp add --transport http --scope user recomma https://api.recomma.ai/mcp

The 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.

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 is asked for only by a client that intends to change things, and the screen says so in different words when it is. A token that carries only identity scopes — because a client never asked to read the workspace — is refused with a challenge naming what was missing; a token that may read and calls a tool that writes gets the same kind of challenge naming recomma:write, which a client that supports it turns into a second approval rather than a failure.

With a key

For a terminal, a CI job, or any client with no browser to open. Make a key in Settings → API keys; the secret is shown once.

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_KEY

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
`list_sources`	The sites the chats lean on, and whether they ever name you
`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
`get_action`	One ticket with its evidence: the questions it would move, the source’s pages, or the rule and the failing markup
`get_impact`	What the finished work moved: the brand’s line, and a verdict per closed ticket
`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

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

Four 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

They share three rules:

Preview first. Every write tool except suggest_prompts previews by default: the answer says what would change and changes nothing. Pass apply: true to act. suggest_prompts has 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 five ready-made workflows — a weekly brief, diagnosing a drop, how the rivals win, an audit of the prompt set, a site fix plan. Each arrives with the brand filled in and names the tools to call in order and how to read what comes back.

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 gets state: "missing" rather than a market worth nothing; a window with no answers in it is previous: null, never a row of zeros that reads as a rise from nothing.
A day is noise; a week is a reading. get_trend and get_impact mark each daily point reliable or 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_impact says pending or due until it has been re-measured. Neither means “no change”.
Nothing is fetched on demand. get_source returns 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_market gives 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.