Each local area page used to take us half a day to create and optimize.
With SEOmatic, we can create hundreds of pages in the same time, which helps our clients make the best use of their budget.
It's transformed how we deliver scalable SEO solutions.
Will Hawkins
Marketing Director, Digi-Business UK
Agents read your Search Console data, do the work, and prove what actually moved. You decide what ships.
14-Day Free Trial. $1 card check, refunded. Cancel Anytime.
A hosted Model Context Protocol server that exposes SEOmatic's tools to any MCP client. Connect over OAuth 2.1, or with a workspace API key as a Bearer token. Tools are annotated read-only or acting, and in hosts that support MCP Apps (ChatGPT, Claude) key tools render interactive UI right in the conversation: file upload, live scan progress, one-click connects, approval cards, and charts.
Every other SEO MCP is read-only. Here, agents stage real fixes, you approve them (approval cards render right in the chat), and approved work executes on your live site within seconds - with full pre-edit state stored, so anything can be rolled back. Nothing publishes without a human.
Every tool description says whether it is free or bills AI credits. Reading your own data - tasks, evidence, Search Console, audits, AI visibility - is free and never triggers paid re-analysis, and get_credit_usage shows exactly where credits went.
An MCP chat stops when you close the window. SEOmatic's agents don't: diagnosis, planning, visibility scans and approved fixes run on schedule server-side. The chat is a window onto a team that is already working - every change still waits for your approval.
In ChatGPT and Claude, key tools render interactive widgets (MCP Apps): upload a CSV where the protocol has no file transport, watch a scan progress live, connect Search Console with one click, approve work with a button, read a trend as a chart. Where the host cannot render them, everything degrades to plain text.
| Field | Value |
|---|---|
| Endpoint | https://app.seomatic.ai/api/mcp |
| Transport | Streamable HTTP (stateless, POST JSON-RPC 2.0) |
| Protocol | 2025-06-18 (2024-11-05 through 2026-07-28 accepted; newer versions negotiate down) |
| Server | seomatic v1.0.0 |
| Auth | OAuth 2.1 (interactive clients) or Authorization: Bearer smk_live_... |
Fastest way: let your agent do it. Copy the prompt below, paste it into whichever AI you want connected, and send it. Agents that can edit config or run commands (Claude Code, Cursor, Cline, Windsurf) will install the server themselves. Chat assistants will hand you the exact clicks for their own app.
Install the SEOmatic MCP server for me.
Server: https://app.seomatic.ai/api/mcp
Transport: Streamable HTTP (stateless JSON-RPC 2.0)
Auth: OAuth 2.1 - the client discovers it automatically, no API key needed.
(Headless setups can instead send: Authorization: Bearer smk_live_...)
What to do:
1. If you can edit MCP config or run commands in this client, install it
yourself now. Reference configs:
- Claude Code: claude mcp add --transport http seomatic https://app.seomatic.ai/api/mcp
- Cursor / Cline / Windsurf (mcp.json or settings JSON):
{ "mcpServers": { "seomatic": { "url": "https://app.seomatic.ai/api/mcp", "type": "streamableHttp" } } }
2. If you cannot, give me the exact clicks for THIS client instead
(for Claude or ChatGPT that is Settings, then Connectors, then add a
custom connector with the URL above).
3. Tell me to finish the OAuth login when the SEOmatic screen appears, and
to pick the site I want connected.
4. In a NEW chat, check the tools menu and confirm SEOmatic is enabled for
that conversation. This step is the one people miss.
5. Then prove it works by calling tools/list and running one read-only tool,
and show me what came back.
Docs if you need them: https://seomatic.ai/developers/mcpPrefer to do it by hand? Three steps, same everywhere: open your assistant's connector settings, paste the SEOmatic URL, then log in and pick your site when the SEOmatic screen appears. No API key to copy. After installing, one step people miss: in a NEW chat, open the tools menu in the message box and make sure SEOmatic is enabled for that conversation.
Two things that look like problems but are not: the consent screen asks you to log in or create a SEOmatic account (free works), and the connector is separate from any SEOmatic skill you may have installed. The skill needs the connector to reach your data.
Find your client:
Requires: A paid Claude plan.
Settings -> Connectors -> Add custom connector Name: SEOmatic URL: https://app.seomatic.ai/api/mcp Then click Connect and approve in the SEOmatic consent screen.
Requires: Nothing extra.
claude mcp add --transport http seomatic https://app.seomatic.ai/api/mcp # then inside a session: /mcp -> seomatic -> Authenticate
Requires: Plus or higher, with Developer mode enabled. The Apps menu only appears on paid plans.
Settings -> Apps -> Advanced settings -> enable Developer mode Then: Settings -> Connectors -> Create Name: SEOmatic URL: https://app.seomatic.ai/api/mcp Auth: OAuth, then approve in the SEOmatic consent screen.
On Business and Enterprise, an admin must allow custom MCP connectors first.
Requires: A SEOmatic API key (Settings -> API keys; a free workspace works). Muse is US-only for now.
Tell Muse: "Connect to the SEOmatic MCP server at https://app.seomatic.ai/api/mcp (streamable HTTP). Use my API key as a Bearer token." Paste the key when Muse asks; it stores it in its credential vault, tests the tools, and saves the integration as a reusable skill.
Muse renders results as text (it is not an MCP Apps host): every tool works, the interactive widgets simply do not apply. Muse asks you before anything that changes or spends.
Requires: Nothing extra. Use OAuth, not an API key.
// mcp.json
{
"mcpServers": {
"seomatic": { "url": "https://app.seomatic.ai/api/mcp" }
}
}Cursor starts the OAuth flow and does not send a configured Authorization header, so pasting an API key here silently does nothing. Approve the browser prompt instead.
Requires: Nothing extra.
// settings JSON
{
"mcpServers": {
"seomatic": {
"url": "https://app.seomatic.ai/api/mcp",
"type": "streamableHttp",
"headers": { "Authorization": "Bearer smk_live_..." }
}
}
}Agent-guided setup: point the agent at github.com/Minh42/seomatic-mcp.
Requires: An x.ai bot. Bearer fallback: create an API key in Settings, AI Agents, API Keys.
Add a custom MCP server: URL: https://app.seomatic.ai/api/mcp (Streamable HTTP, OAuth)
Full always-on template (instructions plus weekly routines): github.com/Minh42/seomatic-mcp/tree/main/grok-bot
Requires: Copilot enabled in VS Code. Agent mode for tool calls.
// .vscode/mcp.json
{
"servers": {
"seomatic": {
"type": "http",
"url": "https://app.seomatic.ai/api/mcp"
}
}
}Then open the Chat view in Agent mode and pick the SEOmatic tools. Sign in when prompted.
Requires: A paid Gemini API key or a Gemini Code Assist licence.
gemini mcp add --transport http seomatic https://app.seomatic.ai/api/mcp # headless or container? use a key instead of the browser flow: gemini mcp add --transport http seomatic https://app.seomatic.ai/api/mcp \ --header "Authorization: Bearer smk_live_..."
The OAuth flow needs a local browser and a localhost redirect, so it will not complete over SSH or inside a container. Use the Bearer form there.
Requires: A Devin plan. This is where Windsurf went.
// Devin uses serverUrl, NOT url
{
"mcpServers": {
"seomatic": {
"type": "http",
"serverUrl": "https://app.seomatic.ai/api/mcp"
}
}
}Devin marks a server connected as soon as the transport is up and only authenticates on the first tool call, so a connected badge does not yet mean authorized.
Requires: Nothing extra.
// settings.json -> context_servers
{
"seomatic": {
"source": "custom",
"url": "https://app.seomatic.ai/api/mcp"
}
}Setting an Authorization header here makes Zed skip the OAuth flow entirely. Use one or the other, never both.
Discovery follows the MCP spec: the endpoint returns 401 with a WWW-Authenticate pointing at /.well-known/oauth-protected-resource (RFC 9728), whose authorization server metadata lives at /.well-known/oauth-authorization-server (RFC 8414). PKCE (S256) is required; tokens are bound to this resource. Dynamic client registration and client-id metadata documents are both supported.
Once connected, the server ships three ready workflows. In Claude they appear in the prompt picker (the / menu or the plus button); other clients surface them wherever they list MCP prompts. Picking one is the fastest way to get a real answer out of your own data on day one.
| Prompt | What it does |
|---|---|
seo-audit | Run a complete, data-grounded SEO audit of the connected site and rank the fixes by impact. |
striking-distance | Find the keywords the connected site is one push away from ranking on page 1 for. |
traffic-drop | Work out why organic traffic dropped, who took the clicks, and what to fix first. |
Listing and expanding a prompt costs nothing: no credits, no free questions. Only the tool calls it then makes are metered. The server also exposes two static reference documents over resources/list that an agent can attach for context: seomatic://guides/connect (how to connect Search Console, Analytics, Ads, Business Profile and a CMS) and seomatic://guides/audit-method (the audit sequence the tools are built around). Neither contains workspace data.
For headless agents and clients that take a static token, mint a workspace API key and send it as a Bearer token. This is also how the Claude Messages API connector authenticates, via its authorization_token field.
Mint it under Settings → AI Agents → API Keys. The section needs the admin role on that workspace, so if you do not see it, check which workspace is selected and whether you are an admin on it rather than a member.
{
"mcpServers": {
"seomatic": {
"url": "https://app.seomatic.ai/api/mcp",
"headers": { "Authorization": "Bearer smk_live_..." }
}
}
}Two requests prove the whole surface: list the tools your key can call, then call one. Failures come back as isError results with a plain-language reason, never opaque transport errors.
curl -s https://app.seomatic.ai/api/mcp \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'curl -s https://app.seomatic.ai/api/mcp \
-H "Authorization: Bearer smk_live_..." \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
"name":"keyword_research",
"arguments":{"action":"metrics","keywords":["seo tools"]}}}'Every successful call returns the payload twice: content (text, for every client) and structuredContent (a JSON object conforming to the declared outputSchema, for clients that want typed data).
| Method | What it does |
|---|---|
initialize | Negotiate the protocol version and get serverInfo. |
tools/list | The scope-filtered tool roster this key can call. |
tools/call | Invoke a tool. Failures return as an isError result, not a transport error, so the agent can react. |
prompts/list | The starter workflows below. Free: no quota, no credits. |
prompts/get | Expand one prompt into the user message that triggers its tool flow. |
resources/list | Static context documents (the connect guide, the audit method). |
resources/read | Fetch one by URI. Same content for every caller: no workspace data. |
ping | Liveness check. Returns an empty result. |
notifications/initialized | Accepted and acknowledged with 202. No body, per the spec. |
The tools/listroster is filtered to the key's scopes, so a client only ever sees tools it can actually call.
| Scope | Lane | Tools it unlocks |
|---|---|---|
read:gsc | Free | Direct Search Console reads. |
chat:ask | Free | All insight tools: GSC, keywords, backlinks, SERP, analytics, ads, Business Profile, datasets, templates. |
agents:act | Paid | The acting tools: SEO tasks, campaigns, bulk edits, blog authoring, skills. Works on any paid plan over MCP. |
Acting over MCP works on any paid plan; the same acting tools over the REST API require Infrastructure.
In hosts that support MCP Apps - ChatGPT and Claude today - 8 tools render interactive UI directly in the conversation instead of describing what to do. Each widget exists because the protocol alone cannot do the job: MCP has no file transport, no navigation, and no way to show progress on async work. Hosts without MCP Apps support get the same tools with plain text results; nothing requires the widgets.
| Tool | What renders |
|---|---|
upload_csv | File picker that reads a CSV in your browser and stages it as a dataset - the file transport MCP itself lacks. |
run_ai_visibility_scan | Live scan progress that polls until results land, then renders per-engine visibility. |
generate_article | Article progress card that polls until the article is ready, with a buy button when prepaid units run out. |
show_connect_card | One-click connect buttons that open Search Console, Analytics, or CMS OAuth in your browser. |
show_approval_cards | Approve/Dismiss cards for proposed tasks and campaigns - the button click is the human decision. |
show_trust_facts_card | One-tap Confirm buttons for the business facts found on your own pages - confirmed facts are the only credentials the agents may claim. |
task_manage | A confirm card before any destructive execution, showing the exact target and consequence. |
gsc_performance | An inline clicks-and-impressions trend chart when a date breakdown is returned. |
The server serves 36 tools: 16 consolidated outcome tools documented in this section, plus 20 single-purpose tools listed in the next one. Each consolidated tool takes an action that selects the operation. Every tool carries MCP annotations, so a client knows at a glance whether it only reads (readOnlyHint) or can stage a change. Nothing is destructive by default: acting tools stage proposals a human approves in SEOmatic. This reference is generated from the server's real catalog, so it is exactly what tools/list serves. Every tool is already scoped to the connected workspace and its site; the few tools that accept a domain default to your own site when it is omitted, and analyze a competitor when you pass one.
gsc_performanceRead-onlyFreeInteractiveRead Google Search Console performance (clicks, impressions, CTR, position) by query, page, dimension, or period comparison. Your own connected property; data is Google-finalized with a ~2-3 day lag. days/dates bound every action, and compare_periods contrasts the window with the one immediately before it. For diagnosis (cannibalization, CTR outliers) use gsc_insights rather than recomputing here.
Cost: FREE - reads your connected/stored data, no AI credits.
| Action | What it does | Parameters |
|---|---|---|
top_queries | top search queries | days, limit |
top_pages | top pages | days, limit |
dimension_breakdown | by device/country/date | dimension*, days, filterQuery, filterPage, limit |
query_page_matrix | cannibalization / query-to-page map | days, maxRows |
compare_periods | decay/growth vs the prior period | dimension, days, limit |
trend | daily clicks/impressions over time | days |
discover_news | Discover / News / Image / Video surfaces | surface, days |
folder_rollup | performance by URL folder / site section | days, depth |
fresh | provisional today/yesterday numbers (hours-old data) | none |
days (number) Look-back window in days (defaults ~28). 1-90 for most actions; 7-90 for trend.limit (number) Row cap. top_queries/top_pages/dimension_breakdown default 50; compare_periods rows per period default 500. Ignored by query_page_matrix (use maxRows) and trend.dimension (string) REQUIRED for dimension_breakdown (device|country|date). For compare_periods: query|page (default page). Ignored otherwise. One of: device, country, date, query, page.filterQuery (string) dimension_breakdown only: restrict to one exact query.filterPage (string) dimension_breakdown only: restrict to one exact page URL.maxRows (number) query_page_matrix only: max query-page pairs (default 2000).surface (string) discover_news only: which surface (default discover). One of: discover, news, image, video.depth (number) folder_rollup only: path depth to group by (1-3, default 1).gsc_indexingRead-onlyFreeCheck Google index status and coverage diagnostics for one URL or a batch of URLs (coverage state, crawl status, robots/canonical issues). Batch inspection caps at 50 URLs per call (Google allows ~2,000/day per property) and reports each URL independently - one failed URL never fails the batch.
Cost: FREE - reads your connected/stored data, no AI credits.
| Action | What it does | Parameters |
|---|---|---|
inspect | one URL, full diagnostics | url* |
batch_inspect | many URLs, summary each | urls* |
url (string) inspect only: the fully-qualified URL to inspect.urls (array) batch_inspect only: the URLs to inspect.gsc_insightsRead-onlyFreeDerived analyses over your Search Console data: keyword cannibalization, brand vs non-brand split, CTR outliers (pages under-earning their position), rich-result appearance performance, 16-month seasonality verdicts, and sitemap health. Analyses read your captured Search Console history (finalized weekly), so verdicts lag live Google by a few days. Use gsc_performance for raw metrics; use this for the diagnosis layer.
Cost: FREE - reads your connected/stored data, no AI credits.
| Action | What it does | Parameters |
|---|---|---|
cannibalization | queries split across competing pages | days, minImpressions |
brand_split | brand vs non-brand performance | days, brandTerms |
ctr_outliers | pages under-earning their position (title/meta candidates) | days, minImpressions |
search_appearance | rich results / enhanced appearance breakdown | days |
seasonality | 16-month YoY verdict: real change vs seasonal dip | none |
sitemaps | sitemap errors, warnings, pending, staleness | none |
days (number) Look-back window in days (7-90, default 28).minImpressions (number) cannibalization/ctr_outliers: minimum impression volume to judge (defaults 100/200).brandTerms (array) brand_split only: brand words/variants, lowercase. Defaults to the domain name.keyword_researchRead-onlyBills AI creditsResearch keyword demand: search volume, difficulty, CPC, and intent, plus keyword ideas, Google Trends interest and related queries, and Google Ads keyword performance. Volume and difficulty come from a live keyword vendor: a workspace without vendor credits gets an explanatory error with the path forward, never fabricated numbers. Use for what to target and how much demand exists; for who ranks today use serp_competitors.
Cost: metrics and suggestions bill AI credits (live vendor data at actual cost); trends, related_queries, compare and performance are FREE (Google Trends / your connected Google Ads).
| Action | What it does | Parameters |
|---|---|---|
metrics | volume/difficulty/CPC/intent | keywords* |
suggestions | keyword ideas from seeds | keywords*, limit |
compare_trends | Trends interest, keywords side by side | keywords* |
trend | Trends interest over time for one keyword | keyword* |
related | Trends related queries | keyword* |
ads_performance | Google Ads keyword performance | days, limit |
keywords (array) metrics/suggestions/compare_trends: the seed or target keywords.keyword (string) trend/related: the single keyword to analyze.days (number) ads_performance: look-back window in days.limit (number) suggestions/ads_performance: max results.keyword_clustersRead-onlyFreeThe agent's cached keyword-cluster map built from the workspace's GSC query universe (pillar, cannibalization, gap, and covered clusters). A stored lookup, not a recomputation: it reflects the last refresh and is empty until GSC history exists. For live demand numbers use keyword_research.
Cost: FREE - reads your connected/stored data, no AI credits.
| Action | What it does | Parameters |
|---|---|---|
list | none |
backlink_profileRead-onlyBills AI creditsRead the backlink profile of your own site or any competitor: referring domains, anchor-text distribution, link velocity, and link-prospect intersects. Read from the link index at call time; a domain with no indexed links returns an empty profile, not an error. Use for authority and link questions; for rankings use serp_competitors.
Cost: bills AI credits per call (live vendor data at actual cost); reads of your own stored data elsewhere are free.
| Action | What it does | Parameters |
|---|---|---|
summary | totals, referring domains, rank/spam | domain |
anchors | anchor-text distribution | domain, limit |
velocity | monthly new vs lost referring domains | domain, months |
referring_domains | top linking domains | domain, limit |
link_prospects | link intersect: linking to competitors but not to us | competitors*, limit |
domain (string) The domain to analyze, e.g. "example.com". Omit it to analyze the connected workspace's own site (the server fills it in); pass it only to analyze a competitor.limit (number) anchors (default 25) and referring_domains (default 50).months (number) velocity only: months back (default 6).competitors (array) link_prospects only: 1-3 competitor domains to intersect against.serp_competitorsRead-onlyBills AI creditsInspect the live search landscape: which SERP features (AI Overview, snippet, PAA, local pack, video) appear for a keyword, plus domain-level top rankings, visibility distribution, and competitor domains. Results are fetched from the live SERP at call time, capped by limit per action. Use for who ranks and why; for keyword demand use keyword_research.
Cost: bills AI credits per call (live vendor data at actual cost); reads of your own stored data elsewhere are free.
| Action | What it does | Parameters |
|---|---|---|
features | which SERP features appear for a keyword | keywords* |
domain_rankings | top keywords a domain ranks for | domain, limit |
domain_overview | organic visibility distribution | domain |
domain_competitors | domains ranking for similar keywords | domain, limit |
keywords (array) features only: the keyword(s) to inspect.domain (string) domain_rankings/domain_overview/domain_competitors: the domain. Omit for the connected workspace's own site (the server fills it in); pass only for a competitor.limit (number) max results where applicable.ai_citationsRead-onlyFreeThis site's OWN first-party AI-citation data, the part no scan can see. observed_citations: citations recorded in REAL logged-in AI answers (ChatGPT, Perplexity, Gemini, Copilot, Claude, AI Overviews) by the user's browser extension, with per-engine counts and best rank - engines personalize and gate their APIs, so a server-side scan sees a de-personalized view while this sees what a real human was shown. brand_facts: the canonical business facts this site publishes for AI engines, plus internal-link health; use them to spot an AI answer contradicting the owner's own declaration. Counts only, never prompt or answer text. scan_results reads the latest server-side SCAN instead: per-engine brand visibility, the prompts where the brand was MISSED and who won them, competitors, and the sources engines cite. Observed vs scanned is the key distinction - observed is what a real logged-in human saw, scanned is a clean de-personalized baseline comparable over time. For AI traffic per page use traffic_analytics.
Cost: FREE - reads your connected/stored data, no AI credits.
| Action | What it does | Parameters |
|---|---|---|
observed_citations | real logged-in AI answers that cited this site | days |
brand_facts | declared canonical facts + internal-link health | none |
scan_results | latest scan: per-engine visibility, missed prompts, competitors, cited sources | scanId |
days (number) look-back window in days (1-90, default 28).scanId (string) scan_results only: a specific scan id from recentScans. Omit for the latest completed scan.traffic_analyticsRead-onlyFreeGoogle Analytics (GA4) traffic and Google Ads account, campaign, and search-term performance. overview/sources/landing_pages/top_pages read GA4; the ads_* actions read Google Ads - each names its missing connection instead of returning empty data. GA4 sessions and Search Console clicks measure different things: for search clicks use gsc_performance. ai_pages is first-party AI engagement (answer-crawler fetches and AI-referred visits per page) that GA4 cannot attribute - it files that traffic as "Direct".
Cost: FREE - reads your connected/stored data, no AI credits.
| Action | What it does | Parameters |
|---|---|---|
overview | GA4 sessions/users/pageviews/bounce | days |
sources | GA4 sessions by channel | days |
landing_pages | GA4 top entry pages | days, limit |
top_pages | GA4 most-viewed pages | days, limit |
ads_account | Google Ads account totals | days |
ad_campaigns | Google Ads campaign performance | days, limit |
ads_search_terms | actual search terms that triggered Ads | days, limit |
ai_pages | first-party AI engagement per page: crawler fetches + AI-referred visits | days, limit |
days (number) look-back window in days.limit (number) max rows where applicable.local_presenceRead-onlyBills AI creditsRead the local search presence of the connected business: Business Profile locations, local ranking for money keywords, and review ratings. Available actions depend on what is connected for this workspace. Use for local and map-pack questions; for national rankings use serp_competitors.
Cost: list_locations and reviews read your connected Business Profile and are FREE; visibility bills AI credits (live local SERP data at actual cost).
| Action | What it does | Parameters |
|---|---|---|
list_locations | GBP locations on the account | none |
visibility | local organic position for keywords | keywords* |
reviews | average rating + review count | location* |
keywords (array) visibility only: the money keywords to measure.location (string) reviews only: the Business Profile location id.visibility_manageCan stage changesBills AI creditsManage the workspace's AI-visibility monitor: list the tracked prompts scans ask every engine, add/edit/remove prompts, and set the scan cadence. Reads of scan RESULTS live in ai_citations action scan_results. Running a FRESH scan is not available over MCP; point the user at the dashboard. Config changes apply directly (no staging) but are plan-capped, and cadence is a spend lever - 'daily' multiplies recurring scan cost ~7x and needs the user's explicit ask.
Cost: all actions are FREE config changes; each ACTIVE prompt raises the recurring scan cost when scans run, and cadence 'daily' is ~7x weekly spend - disclose before setting.
| Action | What it does | Parameters |
|---|---|---|
list | tracked prompts + plan allowance + cadence | locationCode, languageCode |
addstages | track a new buyer question (plan-capped) | prompt*, locationCode, languageCode |
updatestages | rename / pin / (de)activate a prompt | promptId*, text, pinned, active |
removestages | delete a prompt permanently (confirm with the user) | promptId* |
set_cadencestages | weekly / daily / manual - daily is ~7x spend, explicit user ask only | cadence*, locationCode, languageCode |
prompt (string) add: the buyer question to track, in the customer voice.promptId (string) update/remove: the prompt id from list.text (string) update: new prompt wording.pinned (boolean) update: pin the prompt.active (boolean) update: false pauses scanning (keeps history), true re-activates (re-checks the plan cap).cadence (string) set_cadence: how often scans run. 'daily' ~7x weekly spend. One of: weekly, daily, manual.locationCode (integer) Locale location code (default: primary monitor).languageCode (string) Locale language code, e.g. "en".site_pagesRead-onlyFreeAnalyze pages: on-page SEO score and critical issues for a URL, raw crawl metadata (title, meta, headings, links), and the page inventory of the site. analyze and crawl fetch the LIVE page at call time (an unreachable URL returns the fetch error); inventory reads the stored index, synced daily, so brand-new pages can lag a day. Use for page-level diagnosis; for search performance of those pages use gsc_performance.
Cost: FREE - reads your connected/stored data, no AI credits.
| Action | What it does | Parameters |
|---|---|---|
score_draft | score a pasted DRAFT pre-publish (deterministic, free) | content*, contentType |
analyze | SEO score + critical issues | url* |
crawl | title/meta/headings/links | url* |
inventory | the user's real synced pages | limit |
content (string) score_draft: the draft HTML or plain text/markdown.contentType (string) score_draft: guide|tutorial|listicle|review|roundup|comparison|case_study|research|opinion (default guide).url (string) analyze/crawl: the URL to inspect.limit (integer) inventory only: max pages to return.dataset_libraryRead-onlyFreeThe dataset library and page templates that power programmatic pages: list datasets, sample rows, list templates, and read one template. Reads stored data as-is: sample rows are capped, and an empty library returns empty lists, not an error.
Cost: FREE - reads your connected/stored data, no AI credits.
| Action | What it does | Parameters |
|---|---|---|
list_datasets | available datasets | none |
dataset_rows | sample rows from one dataset | datasetId*, limit |
list_templates | built-in page templates | none |
get_template | one template in full | templateId* |
datasetId (string) dataset_rows only: the dataset to sample.templateId (string) get_template only: the template to read.limit (integer) dataset_rows only: how many rows to sample.strategy_insightsRead-onlyFreeThe agent's cached diagnosis for this workspace: a compact snapshot, the current strategy, one raw signal in full, and AI-search content scores. Signals refresh nightly; the strategy itself updates on the agent's weekly cycle. A workspace the agent has never diagnosed says so rather than inventing one.
Cost: FREE - reads your connected/stored data, no AI credits.
| Action | What it does | Parameters |
|---|---|---|
snapshot | compact brief of cached signals | none |
strategy | themes + ranked big plays | none |
signal | one cached signal in full | signal* |
content_scores | AI-search scores for generated articles | none |
signal (string) signal only: which cached signal to read (e.g. index_coverage, backlink_profile).task_manageCan stage changesBills AI creditsInteractiveThe agent's full task lifecycle: read the plan board, stage proposals (create accepts up to 5 per call), approve/dismiss (decide), run approved tasks (execute), and undo applied changes (rollback). Staging never runs anything; every mutation is human-approval-gated - decide records the human's decision (auto-executable standalone tasks then dispatch within seconds; the response says whether they did), execute force-runs a task the instant path declined or releases held work with a staged-content reviewToken, rollback is drift-guarded.
Cost: list/get/create/decide are FREE (create only STAGES proposals, nothing runs). rollback is FREE but UNDOES a live change - it is an action, not a read. execute runs the agent and bills AI credits when the work runs (a title/meta/H1 fix is typically a few hundred credits); approving auto-dispatches that run. Inspecting tasks, evidence and statuses never triggers re-analysis.
| Action | What it does | Parameters |
|---|---|---|
list | the plan board (filterable) | status, type |
get | one task in full detail | taskId* |
createstages | stage up to 5 task proposals | tasks* |
decidestages | approve or dismiss a staged proposal (the approval loop) | taskId*, decision*, confirmDestructive |
executestages | run an approved task now; a reviewToken releases staged holds | taskId*, reviewToken, confirmDestructive |
rollbackstages | undo an executed task's live change (drift-guarded) | taskId*, force |
status (string) list only: filter by task status (proposed, approved, ...).type (string) list only: filter by task type.taskId (string) get/decide/execute/rollback: the task to act on.decision (string) decide only: approve releases the task to the gated pipeline; dismiss archives it. Approving an indexation-destructive type (noindex, redirect) also requires confirmDestructive: true. One of: approve, dismiss.confirmDestructive (boolean) decide/execute: required true for indexation-destructive types (noindex, redirect). Attestation that the human explicitly signed off on this specific task after seeing its URL and consequence - never set it on your own judgment.reviewToken (string) execute only: from get's stagedReview block. Releases a staged hold (first rewrite / money page); pass it ONLY after the human explicitly approved the staged content itself.force (boolean) rollback only: undo even though the live page drifted from what the agent wrote. Set ONLY after the user explicitly confirmed overwriting their newer edit.tasks (array) create only: up to 5 task objects to stage as proposals (see the SEOmatic docs for the task shape).campaign_manageCan stage changesBills AI creditsRead campaigns and stage page-scale, content-sweep, or bulk-edit campaigns and blog articles. All staging is proposal-based and approval-gated; nothing publishes without the user.
Cost: list/get reads are FREE. Creating/approving a campaign bills AI credits per page only as the staged work actually executes; nothing is spent at staging time.
| Action | What it does | Parameters |
|---|---|---|
list | campaigns with status + task counts | status |
managestages | approve/pause/resume/abandon/update a campaign | campaignId*, manageAction*, confirm, brief |
propose_page_scalestages | programmatic landing pages at scale | title*, kind*, brief*, rowSourceKind*, rowPrompt, rows, libraryDatasetId, rowTarget, allowGenText, publishAsDraft, pageTemplate |
propose_content_sweepstages | N distinct blog articles as a campaign | title*, topics*, brief |
propose_bulk_editstages | one instruction across many pages | taskType*, instruction, title, selectorKind, urls, pathPrefix, segments, maxPages |
write_articlesstages | direct N-article staging | topics*, autoPublish |
save_articlestages | save a full article draft (pass title/content/slug) for one-click publish | title*, content*, slug*, excerpt*, metaTitle, metaDescription, featuredImagePrompt* |
status (string) list only: filter campaigns by status. One of: proposed, approved, active, paused, done, abandoned.campaignId (string) manage only: the campaign to act on.manageAction (string) manage only: what to do to the campaign. approve releases the campaign to execution (the USER must have explicitly said yes first). One of: approve, pause, resume, abandon, update_brief.confirm (boolean) manage only, approve + abandon: must be true - attests the user explicitly asked for this (approve releases work + spend; abandon is irreversible).brief (string) manage+update_brief: replacement brief. Also propose_page_scale (template brief) and propose_content_sweep (shared direction).title (string) propose_page_scale (required), propose_content_sweep (required), propose_bulk_edit (optional).kind (string) propose_page_scale only (required): page kind, e.g. "location pages".rowSourceKind (string) propose_page_scale only (required): where page rows come from. One of: ai, user, library, gbp_locations.rowPrompt (string) propose_page_scale, rowSourceKind=ai: dataset to generate.rows (array) propose_page_scale, rowSourceKind=user: one object per page.libraryDatasetId (string) propose_page_scale, rowSourceKind=library: dataset id to attach.rowTarget (integer) propose_page_scale only: target number of rows/pages.allowGenText (boolean) propose_page_scale only: allow per-row AI text (costs credits).publishAsDraft (boolean) propose_page_scale only: publish pages as drafts.pageTemplate (string) propose_page_scale only: built-in template id.topics (array) propose_content_sweep (required, up to 50) and write_articles (required, 2-50). One distinct article per topic.taskType (string) propose_bulk_edit only (required): the sweep type, e.g. ctr_fix, schema, content_refresh.instruction (string) propose_bulk_edit only: shared per-page brief.selectorKind (string) propose_bulk_edit only: how to select pages. One of: urls, path_prefix, all_pages.urls (array) propose_bulk_edit, selectorKind=urls: the pages.pathPrefix (string) propose_bulk_edit, selectorKind=path_prefix: the prefix.segments (array) propose_bulk_edit: advanced mixed-template selectors (overrides selectorKind/instruction).maxPages (integer) propose_bulk_edit only: cap the sweep size.autoPublish (boolean) write_articles only: default false (stage as drafts).content (string) save_article only (required): full Markdown body.slug (string) save_article only (required): the URL slug.excerpt (string) save_article only (required): the excerpt.metaTitle (string) save_article only: meta title.metaDescription (string) save_article only: meta description.featuredImagePrompt (string) save_article only (required): image prompt.* = required for that action. The complete fine-grained tool list behind these, with each input schema, is in the REST reference.
Alongside the consolidated set, the server serves these single-purpose tools. They take direct parameters instead of an action, and the same annotations apply: read-only tools never change anything, and cost is stated per tool.
get_ai_visibilityRead-onlyFreeRead the latest completed AI-search visibility scan: per-engine brand visibility (ChatGPT, Claude, Gemini, Perplexity, Grok, Google AI Overviews), the prompts where the brand was missed and who won them, top competitors, and the sources engines cite.
Cost: FREE - reads your connected/stored data, no AI credits.
run_ai_visibility_scanActs or spendsPaidInteractiveStart a fresh AI-search visibility scan: queries the live AI engines with buyer-intent prompts and measures whether the brand appears. Scans your own site by default, or any competitor domain via the domain parameter. Returns a scanId immediately; results arrive in a few minutes via get_ai_visibility. Limited to one assistant-triggered scan per hour.
Cost: bills AI credits from the workspace pool (comparable to generating a few articles). Reading an existing scan with get_ai_visibility is free.
site_auditRead-onlyFreeSite-wide technical SEO audit: crawls up to 30 pages and aggregates cross-page issues a single-page check cannot see - duplicate titles and metas, thin content, noindex leaks, canonical mismatches, slow pages, and broken internal links.
Cost: FREE - crawls with SEOmatic’s own crawler at call time, no AI credits.
get_credit_usageRead-onlyFreeWhere the workspace’s AI credits went in the current billing period: customer-language groups plus the raw per-feature ledger with event counts. Totals reconcile with the plan meter; refunds show as negative credits.
Cost: FREE - reads your connected/stored data, no AI credits.
get_referral_linkRead-onlyFreeYour personal SEOmatic referral link and reward status: the share URL, your referral funnel (referred, activated, converted), and rewards earned. Both sides earn free questions once the person you invite reaches their first win (not at signup), plus a larger bonus if they subscribe.
Cost: FREE - reads your connected/stored data, no AI credits.
generate_articleActs or spendsPaidInteractiveWrite one in-depth SEO article on a topic, research-grounded against live rankings, quality-gated, delivered as markdown and HTML. Generation is async: returns an article_id to poll with get_article. With no prepaid units it returns the price and a buy link instead of failing.
Cost: consumes 1 prepaid pay-as-you-go article unit ($9 each, never expires); no subscription required.
get_articleRead-onlyFreeFetch a pay-as-you-go article by id (poll after generate_article), or omit the id to list recent articles and the prepaid balance. A ready article carries both markdown and HTML.
Cost: FREE - reads your connected/stored data, no AI credits.
pay_for_articlesActs or spendsPaidPay for prepaid units with a Stripe Shared Payment Token, for agent platforms whose users approve spends in a Link wallet (Meta Muse, ChatGPT agentic checkout). Products: articles ($9, default), question packs ($5 for 50 assistant questions), AI-visibility scans of your own site ($19), and competitor scans ($19). The token is single-use and amount-capped by Stripe; prices are fixed server-side. Hosts that cannot mint SPTs use the buy links from the payment_required payloads instead.
Cost: charges the approved payment method (product-priced); consumes no AI credits.
upload_csvActs or spendsFreeInteractiveStage CSV text so it can be imported as a dataset. Exists because MCP has no file transport: in MCP Apps hosts a file-picker widget reads the file in the browser and passes its text here, minting the same attachmentId a chat upload would. Pass that id to import_attachment_as_dataset.
Cost: FREE - stages the file text, no AI credits.
show_connect_cardRead-onlyFreeInteractiveRender inline one-click connect buttons for data sources the workspace has not linked yet (Search Console, Analytics, Ads, Business Profile, CMS). Already-connected integrations are filtered out server-side.
Cost: FREE - reads your connected/stored data, no AI credits.
show_trust_facts_cardRead-onlyFreeInteractiveRender the Trust Profile card: harvested-but-unconfirmed business facts with one-tap Confirm buttons (MCP Apps hosts), or an Open-settings link when the profile is empty. Confirmed facts are the only credentials/experience/review claims the agent's writers may make - an empty profile means humbler content, never invented authority.
Cost: FREE - reads your connected/stored data, no AI credits.
confirm_trust_factActs or spendsFreeRecord the USER'S confirmation of one harvested trust fact, allowing writers to claim it. The click is the consent: call ONLY when the user explicitly confirmed that exact fact (the widget's Confirm button is the intended caller). Never confirm on your own judgment.
Cost: FREE - reads your connected/stored data, no AI credits.
get_trust_factsRead-onlyFreeThe workspace's Trust Profile: the provenance-tracked, verifiable business facts (credentials, experience, awards, review counts, guarantees) the agent's writers are allowed to claim in E-E-A-T work, each with its source URL and confirmation status. An empty profile means the agent writes around trust claims rather than inventing them.
Cost: FREE - reads your connected/stored data, no AI credits.
import_attachment_as_datasetActs or spendsFreePromote a spreadsheet uploaded in the conversation (CSV/Excel) into a private dataset in the workspace library, ready to drive a pages-at-scale campaign.
Cost: FREE - writes the dataset, no AI credits.
get_ai_crawler_activityRead-onlyFreeWhich AI bots (GPTBot, ChatGPT-User, PerplexityBot, ClaudeBot and more) visited the site, classified by purpose (answer-time retrieval, AI-search indexing, model training), with per-bot trends, top crawled pages, and the crawl-to-citation funnel.
Cost: FREE - reads your connected/stored data, no AI credits.
get_trust_entitiesRead-onlyFreeThe trust entities AI engines consult when answering questions about the market, mined from the actual fan-out queries scans capture. Every entity carries the cross of queried vs cited, surfacing the outreach list of sources engines check but never cite the brand from.
Cost: FREE - reads your connected/stored data, no AI credits.
get_ai_funnelRead-onlyFreeThe full AI-search funnel per page, joined across three measurements: cited (engines named the page as a source), crawled (AI bots actually fetched it), and referred (GA4-measured assistant-referred visitors), with unmeasured columns flagged honestly rather than shown as zero.
Cost: FREE - reads your connected/stored data, no AI credits.
show_approval_cardsActs or spendsFreeInteractiveRender inline Approve/Dismiss cards for existing proposed tasks and campaigns, bringing the approval decision into the conversation instead of sending the user to the dashboard.
Cost: FREE - reads your connected/stored data, no AI credits.
get_task_rollbackRead-onlyFreeWhat the pipeline can restore for an executed task: every live edit stores the page’s full pre-edit state before writing. Returns which fields are recoverable, original embed code verbatim, and how to trigger the one-click restore.
Cost: FREE - reads your connected/stored data, no AI credits.
resume_page_publishingActs or spendsPaidResume a page campaign paused by the scale governor (the drip stops itself when the first published pages earn essentially no search appearances). Requires the resumeToken from the hold, so resuming is always an explicit, informed decision.
Cost: resuming is free; each released page bills AI credits as it generates and publishes, same as campaign execution.
A free workspace's tool calls draw from the same monthly question quota as ChatSEO, shared across chat, MCP, the REST tool bridge, and the CLI, so there is one meter everywhere. initialize and tools/list are always free; only tools/call consumes a question. Your first connect banks 10 bonus questions on top of the monthly allowance, enough for a full first audit. When the quota is exhausted the call returns an isError result carrying a one-click upgrade link, plus a referral link that banks extra free questions for both sides. Paid workspaces are not question-metered.
Independent of plan, each key is rate-limited to 60 tool calls per minute and 1,000 per hour, enough for any real session and a backstop against runaway loops. To revoke access: remove the connector in your assistant, or revoke the key or OAuth grant in SEOmatic Settings. Either kills the connection immediately.
domain default to your own site when it is omitted.agents:act: the roster only shows what the key can call. Acting tools appear on any paid plan.isError results with a plain-language reason the model can act on, never as opaque transport errors.