SearchChampMCP Documentation
MCP tool reference
Parameters, returned data, scopes, costs, and availability for every SearchChamp MCP tool.
SearchChamp publishes 38 tools from one versioned registry. OAuth clients receive the full catalog; each call still checks scope and role. User-generated tokens receive only the tools marked in the Token column, filtered by the organization's current plan and the token's scope.
Input and result rules
- Inputs are strict: unknown fields, wrong types, out-of-range numbers, and malformed UUIDs return
invalid_inputbefore the handler runs. - A
siteaccepts a domain or display name. Calllist_siteswhen unsure. A foreign/missing site returnssite_not_found; an ambiguous name returns only your own matching candidates. - Tool results contain human-readable
contentand machine-readablestructuredContent. - A missing product prerequisite is normally a valid
{ setup_required: true, reason, next_step }result, not an exception. - Credits are debited after a handler runs. Denied/invalid calls do not debit a successful tool call.
Core SEO reads
| Tool | Required input and optional bounds | Returned data | Scope | Credits | Token |
|---|---|---|---|---|---|
list_sites | None | Addressable sites: slug, domain, workspace | mcp:read | 1 | All paid plans |
get_daily_brief | site; date? as YYYY-MM-DD | Headline, findings, open actions, or setup guidance | mcp:read | 1 | OAuth only |
get_site_snapshot | site | Rank/AI Visibility/audit/credit rollup plus open actions, goals, and strategy cards | mcp:read | 1 | OAuth only |
get_rank_movers | site; days? 1–90 (default 7), limit? 1–100 (default 10) | Keywords ordered by movement, including baseline/current ranks and delta | mcp:read | 1 | OAuth only |
get_rankings | Same as get_rank_movers | Same rank-mover data under the token-catalog name | mcp:read | 1 | All paid plans |
get_ai_visibility | site | Score, prompt coverage, appearance/share-of-voice summary, or setup guidance | mcp:read | 1 | All paid plans |
get_opportunities | site; limit? 1–100 (default 10) | Top active opportunities with title, lane, and impact | mcp:read | 1 | OAuth only |
get_audit_summary | site | Latest completed audit scores and severity counts, or setup guidance | mcp:read | 1 | OAuth only |
get_audit_issues | site; limit? 1–100 (default 20) | Actual severity-ordered findings: title, page URL, description, kind/lens, and fix availability | mcp:read | 1 | Business/Pro+ token |
get_backlinks_summary | site | Active total, 30-day gained/lost, spam count, top referring domains | mcp:read | 1 | Business/Pro+ token |
get_tracked_keywords | site; limit? 1–500 (default 50) | Current positions, unranked flags, volumes, and cluster labels | mcp:read | 1 | OAuth only |
get_bot_access_report | site | Latest AI Access Score, per-bot verdict/evidence, grouped coverage, recent history; { report: null } if no scan | mcp:read | 1 | OAuth only |
get_volatility | site; days? 1–90 (default 30) | Volatility score and most-volatile keywords, or setup guidance | mcp:read | 1 | Business/Pro+ token |
Content and publishing
| Tool | Required input and optional bounds | Returned data / effect | Scope | Credits | Token |
|---|---|---|---|---|---|
get_content_drafts | site; limit? 1–100 (default 25) | Draft/ready article identifiers, slugs, statuses, and titles | mcp:read | 1 | Business/Pro+ token |
list_draft_articles | site; limit? 1–100 (default 25) | Drafts plus MCP claim state: unclaimed, claimed/lease, or published/verification | mcp:read | 1 | OAuth only |
get_article_content | article_id | Markdown/HTML body, SEO metadata, slug, hero image, and publisher JSON-LD graph | mcp:read | 1 | OAuth only |
get_page_recommendations | site; url? | Audit issues and opportunities reshaped as rewrite guidance | mcp:read | 1 | OAuth only |
get_brand_voice | site | Composed tone, do/don't lists, banned phrases, audience, and available named voices | mcp:read | 1 | OAuth only |
start_publish | article_id | Claims a draft for 30 minutes; returns claimed/reclaimed/already-claimed state | mcp:act | 10 | OAuth only |
report_publish | article_id, canonical_url on the site's domain | Records the external publish and queues independent verification; idempotent for article+URL | mcp:act | 10 | OAuth only |
publish_article | article_id, provider (wordpress or shopify); as_draft? default false | SearchChamp enqueues its standard CMS publisher and returns job_id; feature-enable and CMS gates apply | mcp:act | 10 | OAuth only |
start_publish/report_publish are for a coding agent that performs the site write itself. publish_article asks SearchChamp to perform the CMS write. Poll get_job after publish_article.
Custom-site publication artifacts
| Tool | Required input and optional bounds | Returned data | Scope | Credits | Token |
|---|---|---|---|---|---|
list_pending_publication_pages | site; limit? 1–100 (default 25), offset? 0–10,000 | Exact total and bounded page of Content Writer pages awaiting custom-site publication | mcp:read | 1 | Business/Pro+ token |
get_pending_publication_page | site, article_id UUID | Source/proposed versions and a drift-safe ChangeArtifactV1 | mcp:read | 1 | Business/Pro+ token |
list_internal_link_edits | site; limit? 1–100 (default 25), offset? 0–10,000 | Exact total and bounded pending edits without full page bodies | mcp:read | 1 | Business/Pro+ token |
get_internal_link_edit | site, suggestion_id UUID | Exact-context, drift-safe ChangeArtifactV1 | mcp:read | 1 | Business/Pro+ token |
Page Optimizer apply and verification
| Tool | Required input and optional bounds | Returned data / effect | Scope | Credits | Token |
|---|---|---|---|---|---|
list_approved_changes | site; approved status?; limit? 1–100 (default 25) | Approved changes with page/section identity, summary, lifecycle status, and verification timestamps | mcp:read | 1 | Business/Pro+ token |
get_change | id | Exact approved before/after HTML, page URL, anchor, heading, kind, summary, selector hints, and status | mcp:read | 1 | Business/Pro+ token |
mark_applied | id | Reports a live application and triggers an independent re-crawl; settles verified or applied-unverified | mcp:act | 10 | OAuth only |
list_approved_changes defaults to approved but not conclusively verified work (accepted, applied, and applied_unverified). mark_applied never accepts HTML from the caller and is rate-bounded/idempotent; the agent's report is not the final verification.
llms.txt
| Tool | Required input and optional bounds | Returned data / effect | Scope | Credits | Token |
|---|---|---|---|---|---|
get_llms_txt | site | Current configuration/content and latest generation state | mcp:read | 1 | Business/Pro+ token |
generate_llms_txt | site, idempotency_key 1–128 chars | Creates or reuses a generation job | mcp:spend | 20 | Business/Pro+ Full token |
get_llms_txt_job | site, run_id UUID | One site-scoped generation job | mcp:read | 1 | Business/Pro+ token |
list_llms_txt_versions | site; limit? 1–100 (default 25), offset? 0–10,000 | Exact total and bounded generated-version list | mcp:read | 1 | Business/Pro+ token |
diff_llms_txt_versions | site, from_version_id, to_version_id UUIDs | Exact unified diff between two versions from the same site | mcp:read | 1 | Business/Pro+ token |
The caller supplies a stable idempotency_key so reconnects/retries do not enqueue equivalent generation work twice.
Actions, natural-language answers, and jobs
| Tool | Required input | Returned data / effect | Scope | Credits | Token |
|---|---|---|---|---|---|
list_actions | site; status? | Site agent actions, optionally filtered | mcp:read | 1 | OAuth only |
approve_action | action_id | Audited, idempotent approval. Eligible CMS meta writes can execute only when mcp:act is also granted and execution is enabled; spending runs otherwise remain proposed for in-app approval | mcp:approve | 5 | OAuth only |
decline_action | action_id | Audited, idempotent decline | mcp:approve | 5 | OAuth only |
ask_atlio | site, message | Grounded answer plus suggested actions (capability, params, billing preview, action class); spending commands are proposed, not silently run | mcp:read | 20 | OAuth only |
get_job | job_id | Status, stage, percent, partial summary, and poll_after_ms; poll until succeeded/failed/canceled | mcp:read | 1 | OAuth only |
ask_atlio requires editor-or-higher access to the addressed site. Although it requires the read scope, it is LLM-backed and costs 20 credits. The server's published cost is authoritative if this table and a live tools/list ever differ.
Token catalog summary
User-generated tokens intentionally expose a smaller catalog:
- Every paid plan:
list_sites,get_rankings,get_ai_visibility. - Business/Pro and higher: also
get_audit_issues,get_backlinks_summary,get_content_drafts,get_volatility, the approved-change read tools, custom-publication artifact reads, and llms.txt reads. - Business/Pro and higher Full tokens: also
generate_llms_txtthroughmcp:spend. - Approval, action-decision,
ask_atlio,mark_applied, and publishing tools are OAuth-only.
The organization plan is evaluated at call time. Downgrading can immediately reduce a token's visible catalog; upgrading expands it without reminting the token.