Your agent

Connecting

The endpoint is https://mcp.cogbird.com/mcp, and there are two ways to reach it. Whichever you use, ask your agent for get_site_overview to confirm it works — it answers with how fresh the data is and what is waiting.

Let the agent connect itself

Point any client that speaks OAuth at the endpoint and it will do the rest: it discovers the authorization server, registers itself, and opens a page where you pick a site and approve it. Nothing is copied and pasted, and no secret passes through you.

The one thing you do is read that page. Any client may register under any name, so the name on it is the client’s own claim and not something we have checked — the screen says so, and it says which site and which permissions are being asked for. Approve only what you started.

Grants are listed on your account page and withdrawing one takes effect on the next request.

Or issue a token yourself

Open your site’s settings and issue an agent token. The secret is shown once and revoking it takes effect immediately. The dialog gives you both forms:

• Claude Code — a claude mcp add --transport http line to run in your project.
• Anything else — the equivalent mcpServers block, with the token as a bearer header.

Read, and write

Both routes issue a token carrying one or both of two permissions. read is every measurement on the site and changes nothing. write is the decisions — approve, dismiss, snooze — and report_shipped.

Full access is the default and usually the right one: an agent that can read the inbox but cannot report what it shipped leaves the engine unable to measure anything, which is the one thing it exists to do. Read-only is worth choosing when the token is going somewhere you do not operate. A call outside a token’s permissions is refused with a sentence naming the scope it lacks, and nothing is changed.

Neither permission lets anything edit your site. The engine has no write access to your pages, and that is a property of the product rather than of the token.

The first two calls of any session

get_updates first, on any session that is not the first: it reports what changed since a timestamp — verdicts that landed, suggestions that appeared, findings that resolved themselves, and page changes nobody explained.

Then get_brief before editing any page. It is the obligation the engine owes an agent and the one thing no other SEO tool provides: what may I not touch, what would I break, and what is missing. A page is usually already earning something, and a rewrite that does not know what will quietly destroy it.

What can be asked for

The state of things

get_site_overview, get_baseline, get_updates, get_context. How much data there is and how fresh, the declared → crawled → indexed → earning funnel and which step loses most, and what the engine has been told about the business.

The work list

list_suggestions and get_suggestion for the ranked items and the evidence behind one. approve_suggestion, dismiss_suggestion, snooze_suggestion, acknowledge_diagnostic and reopen_suggestion are the decisions, and they mean exactly what they mean in the app.

The queue

list_suggestions answers what did you find. get_queue answers what happens next, which stopped being the same question when the queue became a list somebody can edit: it is the order the engine works down, with the day each row is expected to move and — where a row will not move — the engine’s own sentence about what is holding it.

pin_suggestion puts one at the end of that queue and unpin_suggestion takes it out; move_in_queue reorders, by direction or straight to a to_place. A row the engine cannot write keeps its place and does not hold up the rows behind it, so a queue whose first entry is frozen until September still ships tonight. Ordering is all any of these do — every readiness gate still applies, and run_now is the one that changes when rather than in what order.

Before an edit

list_pages to pick one, get_page for everything known about it, get_brief before changing it, check_edit_risk to re-check a page cheaply or sweep several.

Demand and competition

get_query for one search term, get_answers for the AI Overview standing above your results and whose sentence it is quoting, get_competitors and get_competitor for who else holds the demand you draw on, list_proposals and get_proposal for demand you never had, and list_link_prospects for domains linking to rivals and not to you.

After shipping

report_shipped — the important one. Then report_published for a page a proposal asked for, report_link_acquired for a backlink that is now live, get_ledger for what has worked here, and get_changes for edits the engine observed but nobody reported.

get_decision_history is the other half of that record — counts of approved, dismissed and shipped per kind of work. A site that has dismissed every metadata suggestion and shipped every link suggestion is telling you something no detector measured, and it is worth reading before proposing work rather than after.

Planning

plan_shipping_batch for which of a set can ship together and still all be measured, project_position_change for what a ranking move is historically worth on this site, and setup_indexnow to have every report also notify the engines that accept it.

Telling it something

set_context is the one write here that is not a decision about a suggestion: what this business sells, what is launching, what has been deprioritised. refuse_link_proposal is the narrower one — this anchor phrase is a heading, a component prop or legal text, so stop proposing it.

How often it can be called

By default 120 calls a minute and 20,000 a day, counted against the token rather than the workspace. A plan can carry its own ceilings, so treat these as the floor rather than the number.

Going over returns a 429 carrying retry-after, which of the two limits was hit, and how many calls the token has made. Waiting it out loses nothing. The daily limit sits where ordinary work does not reach it, so hitting that one almost always means an agent is looping — and polling in a loop cannot return anything new anyway, because this data moves once a night.

Being told, instead of asking

This data moves once a night, so polling cannot return anything new and the daily rate limit exists partly to say so. Point a webhook at yourself instead — site settings, Webhooks — and the engine tells you when something happened. Four events:

• run.completed — the nightly pass finished and everything is current as of that moment. This is the one that makes polling unnecessary. It fires on a failed pass too, carrying which step failed, because “nothing changed” and “nothing ran” need different reactions.
• suggestion.surfaced — something entered the inbox, with its severity and what it proposes.
• suggestion.resolved — the evidence behind one is gone, so it has left the inbox. Usually somebody fixed it, sometimes without telling us.
• verdict.landed — a measured change reached its verdict, inconclusive ones included, with the effect size and the window.

Every delivery is signed. Failures are retried on the next pass rather than dropped, and an endpoint that fails ten times in a row is stopped with the reason kept.

Setting a site up without a browser

Everything above needs a site and a token, and neither can be created over MCP — every tool there authenticates with the credential those two steps produce. So there is a small HTTP API for exactly that, and for nothing else.

Create a workspace key under Workspace → Keys. It is not an agent credential and MCP refuses it; it exists to make these calls:

• POST /v1/sites — claim a domain for your workspace.
• POST /v1/sites/{siteId}/tokens — mint the agent token for it, with the permissions you choose.
• GET /v1/sites/{siteId}/suggestions — the inbox as plain JSON, for a dashboard or a cron job rather than an agent. Agents should use list_suggestions, which carries the judgement around the list as well as the list.

Search Console is deliberately not on that list. It is a Google grant against a property you administer, and no key of ours substitutes for it — a site created this way has no search data until somebody signs in and connects it.

What it will not do

The engine has no write access to your site and never will. It measures and explains; your agent edits and reports back. Assisted mode is the one place it writes anything itself, and it writes to a branch — that division is why there is nothing here that could deploy something you did not read.

Writes are also refused on a workspace that is not paying — reads keep working, so nothing you have collected is held hostage.