Matchstick for agents

Version 1.5.0 · All sections

What it is

Connect Matchstick and your agent runs your SEO.

Matchstick watches a site's Search Console, crawls its pages, finds what is costing clicks and drafts the fix as a pull request a person merges. The agent API opens that loop to the agent you already use: over MCP it reads the data, the findings and the changes, starts research, checks and drafts, reviews and, where the site's owner allows it, approves. Everything an agent does is a row on the site's activity page, and nothing changes on a site until a pull request is merged.

The server is at https://matchstick.io/mcp. It speaks the MCP protocol revision 2026-07-28 and the 2025 revisions, with 35 tools, a playbooks resource and a weekly-review prompt. The same calls are available as JSON at https://matchstick.io/api/v1 (OpenAPI).

How to connect

By URL, with OAuth

Add https://matchstick.io/mcp as a custom connector in claude.ai (Settings → Connectors), in ChatGPT (Settings → Connectors, developer mode), in Cursor, or in any client that follows the MCP authorization spec. The client finds the authorization server through https://matchstick.io/.well-known/oauth-protected-resource/mcp, sends you to sign in with Google or GitHub, and shows the consent page: which sites, which permissions, a weekly credit budget. The client identifies itself with a Client ID Metadata Document or registers dynamically; PKCE S256 and the resource parameter are required. Access tokens last an hour and refresh for thirty days; revoke a connection at any time from Settings → Connected agents.

Claude Code and Cursor

claude mcp add --transport http matchstick https://matchstick.io/mcp

Cursor takes the same URL in mcpServers ({ "url": "https://matchstick.io/mcp" }) and completes OAuth on the first call.

With a personal API key

Settings → API keys mints a key (msk_live_…) with the scopes and sites you choose. Send it as a bearer token to /mcp or /api/v1:

curl -H "Authorization: Bearer msk_live_…" https://matchstick.io/api/v1/sites

Scopes

The full list: sites:read, data:read, findings:read, changes:read, reports:read, activity:read, runs:read, findings:write, runs:write, changes:review, changes:approve, changes:deploy, cloudflare:apply.

Tool reference

Read tools are free. Propose tools cost credits (research pass 2, check 4, draft or revert 10, revision 5) from the connection's weekly budget. Every write takes an idempotency_key; the propose tools also take dry_run. Results carry structuredContent (the same object the REST API returns) and a short text summary; a failure is an isError result whose text is the error body below.

The server also serves the resource matchstick://playbooks (the house rules in plain language) and the prompt weekly_seo_review, which walks these tools for one site in the order the weekly loop runs them.

Autonomy and approvals

Each site has an autonomy level, set by the account's owner in Settings → Agents. Whatever the level, a change becomes live only when its pull request is merged and the site is deployed.

Levels 2 and 3 are off by default and lapse when no person has signed in for 30 days. Call get_agent_policy before acting on a site: it says what the credential may do there, the budget left and who the human approvers are.

Approvals

When approve_change needs a person, it returns approval_pending with an approve_url. Give the person the link and stop. They see the change with who asked, approve (which merges as them, with the request recorded on the pull request), deny with a note, or ask for changes. A request is bound to the head you reviewed and stands for 72 hours; if the branch moves it goes stale. A client that declares URL elicitation gets the same round as an input_required result and sees the outcome on its retry.

Gates and budgets

An agent is held by the same gates as Matchstick's own daily triage: the owner's not-now and never, stale Search Console data, protected pages, a page under evaluation from an earlier change (page_frozen, with the date), one live draft per finding, the open-pull-request cap, the agents' drafts per day, the plan's credits and the connection's weekly credit budget (set at consent; the week starts Monday 00:00 UTC). A person in the app is never gated.

Updates and webhooks: noticing new work

Matchstick's tools answer questions; these two paths tell a client that something happened. Both read the same feed, so a poller and a webhook never disagree about what counts: a weekly report finished, a finding became open or open again, a change became ready for review. Daily crawl noise and findings Matchstick handles on its own don't count.

Polling: get_updates_since

Free. Pass since as an ISO 8601 moment or the next_cursor of your previous call (default: the last 24 hours), and a site or none for every site the credential sees. The answer carries reports, findings and changes oldest first, each site's last_report and open_findings by doer (you, matchstick, matchstick_with_approval), server_time and next_cursor. Nothing happened: changed: false and empty lists. The window ends a few seconds behind the clock so a row still committing is never skipped; more: true means the window was cut at the last item and the next call continues from the cursor.

GET https://matchstick.io/api/v1/updates?site=example.com&since=2026-10-25T13:00:00Z

Every site-scoped read also carries last_report_at, last_report_id, last_report_url and open_findings_count (list_sites, list_findings, get_report, the REST mirrors), so a client can tell "a report just finished" from "the same stale items" without a second call.

Webhooks

A person adds a URL on Settings → Webhooks and picks the events. Matchstick POSTs one JSON message per event within about half a minute, oldest first, and signs each one.

Headers: X-Matchstick-Event, X-Matchstick-Delivery (the event id, repeated on a retry so a receiver can drop a duplicate), X-Matchstick-Signature: t=<unix seconds>,v1=<hex> where v1 is the HMAC-SHA256 of <t>.<raw body> with the webhook's secret (shown once when it is made; reject a t older than 5 minutes). Answer 2xx within 10 seconds. A failure is retried with a growing wait (1, 2, 4 … 60 minutes) and later events wait behind it, in order; after 20 failures in a row the webhook pauses until a person resumes it. A test delivery (type: "ping", no site) is available from the same page.

{
  "id": "evt_3f9c2a7d1e8b4c6a9d0f1e2b",
  "type": "finding.opened",
  "at": "2026-10-26T13:04:11.512Z",
  "site": {
    "id": "<site id>",
    "domain": "example.com",
    "url": "https://matchstick.io/sites/<site id>"
  },
  "data": {
    "finding": {
      "id": "<finding id>",
      "title": "Request indexing for /about",
      "why": "Google hasn't indexed a page that ranks for its name.",
      "kind": "indexing",
      "doer": "you",
      "confidence": "high",
      "urls": [
        "/about"
      ],
      "status": "open",
      "reopened": false,
      "report_id": "<report id>",
      "url": "https://matchstick.io/reports/<report id>"
    }
  }
}

Limits and errors

• 120 read calls a minute and 20 write calls an hour per key or grant; rate_limited with retry_after_s beyond that.
• Request bodies up to 1 MB on /mcp and /api/v1; 64 KB on the OAuth endpoints.
• search_performance returns at most 1,000 rows over at most 16 months.
• Every write takes an idempotency key (≤ 64 characters, kept 24 hours): the same key with the same arguments replays the first answer; different arguments are idempotency_conflict.
• Access tokens live an hour, refresh tokens thirty days (rotated on use); API keys until revoked.

Errors

Every failure is the same object, as JSON on REST and as the text of an isError result over MCP:

{ "error": { "code": "page_frozen", "message": "…", "retryable": false, "details": { "until": "2026-10-29", "change_id": "…" }, "hint": "…" }, "request_id": "…" }

Quote request_id when you write to us: it is on the activity page too.

Privacy: what a connected client can see

A connected client acts as the person who connected it, on the sites they chose at consent (or that a key was minted for), and sees what that person sees of those sites: Search Console clicks, impressions and positions by page and by query; the crawl's facts about each page; findings and the evidence behind them; changes, their diffs and reviews; weekly reports; and the account's activity trail. It never sees credentials, tokens, other accounts, billing details or the person's sign-in.

Every call is a row on the site's Activity page with the client's name, so the people on the account can see what an agent did. There is no public page of this: nothing about a site is published anywhere. A person revokes a client in Settings → Connected agents (OAuth) or Settings → API keys; revocation ends access immediately.

The data a client receives is subject to its own operator's terms. Matchstick's handling of your data is in the privacy policy; the connection and token design is in security.

Changelog

The MCP server announces version 1.5.0.

1.5.0 · 2026-10-27

• list_needs_you / GET /needs-you: everything the web app's Needs review queue lists, in one free call: changes to review, merged changes not seen live yet (with the last look), checks that ended in needs_you or draft_pr and weren't acted on, findings only a person can do, blocked sites; counts per site and the tools that settle each item. The web queue and the sidebar badge read the same function.
• confirm_deploy / POST /changes/{id}/confirm-deploy (scope changes:deploy): after a merge, say the site is deployed; Matchstick looks at the live pages first and records live, or unverified on the caller's word when nothing is visible from outside, and not_yet with what it saw when the old version is still served. claim: false only looks. evidence (URLs, a note) is kept on the change for a person to audit. get_change lists confirm_deployed among a merged change's allowed_actions.
• The deploy checker reads a change whose point is an error status ("returns 404", "410 Gone", a removed file) as live once the page answers 4xx, instead of "not deployed yet" forever; the owner's Deployed button benefits too.
• acknowledge_check / POST /checks/{id}/acknowledge: a check that ended in needs_you or draft_pr whose next step was done outside Matchstick is marked done with a note and leaves Needs you; the web app's Done on a check runs the same call.

1.4.0 · 2026-10-26

• get_updates_since / GET /updates: what changed since a moment, in one free call: the weekly reports that finished, the findings that became open or open again (kind, doer, confidence, pages, status) and the changes ready for review, oldest first, with every site's last report and open finding counts by doer, server_time and a next_cursor to continue from. Nothing happened → changed: false and empty lists, so a daily routine can poll and stay quiet.
• Every site-scoped read carries last_report_at, last_report_id, last_report_url and open_findings_count (list_sites per site, list_findings, get_report and the REST mirrors), so a client can tell a report that just finished from the same stale open items.
• Webhooks (Settings → Webhooks): a URL receives report.finished, finding.opened (findings whose doer is you or matchstick_with_approval) and change.ready_for_review as signed JSON POSTs with deep links, within about half a minute, oldest first, retried with a growing wait and paused after 20 failures in a row; a test delivery from the same page. Docs: /docs/agents/sync.

1.3.0 · 2026-10-26

• update_finding_status / POST /findings/{id}/status: mark a finding done (with a note), dismissed (reason: won't fix, false positive, duplicate), snoozed (for some days) or open again, so work done outside Matchstick (Search Console, Cloudflare, a one-off edit) stops showing up in Needs you and the digest. The note and the reason go to the site's memory; the daily triage reads dismissed as never and snoozed as not now. A finding with a queued, drafting or open change is settled through the change instead.
• verify: true on done lets the evidence decide instead of the claim: an indexing finding is checked against Google's latest stored inspection of its pages (done when every page is indexed by an inspection newer than the finding; otherwise it goes to verifying and the daily run keeps asking Google), a host-variant or email-obfuscation finding is probed live.
• The auto-close loop: an open or verifying indexing finding closes itself when inspect_pages, the daily run or the weekly pass stores an inspection showing every one of its pages indexed; inspect_pages answers the findings it resolved (resolved).
• The web app's Mark done and Not now forms run through the same service call; Not now now takes a reason for never (won't fix, false positive, duplicate) and can mark the item done with the note.

1.2.0 · 2026-10-21

• Coverage on every number: get_performance_totals and get_site_overview say how many days of a range are known (a day with no row inside the stored history had zero impressions, not missing data), carry the previous period even when it was zero, and the stored lifetime totals (history.lifetime); the weekly report's facts and the analyst's rules say the same, so "first clicks ever" can't come from a short window.
• Internal links from the last two weeks of crawls, with coverage against the sitemap: orphan is null (unknown) on a partial crawl, never true; get_page.inlinks and the weekly underlinked detector follow the same rule.
• A trimmed text block now says how to get the rest: the limit to pass and next_cursor to page with; get_indexing pages at 50 by default and says how many sitemap URLs were ever inspected.
• Findings are deduplicated across the report, the daily triage and checks (same title, kind and pages → one item); host-variant and email-obfuscation findings are re-checked daily against the live site and resolved when it passes, and investigate_finding settles them on the spot (status done, free).
• inspect_pages / POST /sites/{site}/inspect: Google's URL Inspection verdicts for up to fifty pages now (free); the daily run inspects new sitemap URLs on its own.
• A change in a shared file freezes the whole site only when a title, description, heading, copy, link, canonical, redirect, sitemap or robots change lands on every page; alt text, structured data, code or config in a shared component freeze only the pages named.
• search_performance and get_performance_totals report the anonymized share (what Google counted for the site or page but attributed to no query); get_content_gaps accepts a lower min_impressions and says how many gaps sit below the floor.

1.1.1 · 2026-10-21

• get_usage and GET /usage scope spent and the ledger to the sites the credential can see (a site-restricted key or grant, a member's teams); the plan's own rows (allowance, top-up, adjustment) stay, the balance and allowance stay the whole plan's, and account.note says so. Ledger rows no longer carry account_id.

1.1.0 · 2026-10-20

• Every tool result's text now carries the whole answer: the one-line summary, a data-freshness line (data_through, synced_at, crawled_at, also fields on every site-scoped object), then the structured object as compact JSON with every id and row (trimmed only when stated).
• search_performance: the query filter applies on every dimension (dimension page with a query lists the pages ranking for it), query_match contains, sort by clicks, impressions, position, ctr or opportunity (missed clicks at positions 5–20), min_impressions, total_rows.
• New read tools: get_performance_totals (site-wide totals with the previous period and the change), get_indexing (Google's verdict per URL with the coverage reason and canonical mismatches), get_cannibalization, get_content_gaps, get_internal_links (inlinks, orphans, depth; one page's sources and targets), get_connection_info (which credential, scopes, site restriction, what each site has connected). REST mirrors under /api/v1.
• get_site_overview adds impressions, CTR, position and the change (delta), names frozen pages with until and change_id, and says which Search Console property kind and how far back the stored data reaches (data_since, history); get_report adds headline, summary, windows, freshness, property and data_since; get_page adds CTR per query, 20 queries, on-page content (word count, headings) and inlinks.
• get_usage tells the plan's credits (account) and this connection's weekly budgets per site (connection) apart and explains a negative balance; get_agent_policy gains budget with the week's start and reset.
• draft_change refuses a fix that is a dashboard setting (Cloudflare), DNS or hosting with not_a_repo_change, naming the exact setting and the matchstick.io page where a person applies it; get_finding adds fix (where the fix lives) and each check's next step with its apply block; get_run shows a check's verdict and next step.

1.0.0 · 2026-10-20

• OAuth 2.1 for MCP clients: connect claude.ai, ChatGPT, Grok and other clients by URL alone; consent per site with a weekly credit budget.
• Propose tools: run_research_pass, investigate_finding, draft_change (with guidance), suggest_finding, request_revert; dry runs; per-connection weekly budgets and a per-day draft budget.
• Human approval flow: approve_change at level 1 returns an approve_url a person opens; level 2 merges low-risk changes itself and returns merge_sha and the verification window.
• The MCP server at /mcp (2026-07-28 and the 2025 revisions) with 23 tools, the playbooks resource and the weekly_seo_review prompt; personal API keys and the REST mirror at /api/v1.