MCP tool reference

SearchChamp publishes 54 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_input before the handler runs.
• A site accepts a domain or display name. Call list_sites when unsure. A foreign/missing site returns site_not_found; an ambiguous name returns only your own matching candidates.
• Tool results contain human-readable content and machine-readable structuredContent.
• 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

Evidence and keyword research

These tools let an agent diagnose a page and propose keywords from the evidence SearchChamp already holds, without opening the app. Every read names its source and reporting range, and an unavailable integration is a named state (not_connected, needs_reconnect, read_failed), never an empty success. Nothing in this lane adds keywords, changes tracking, edits a page, publishes, or starts an integration sync; the single spending tool is run_keyword_research, and it starts nothing without the user's explicit confirmation of a previewed scope.

run_keyword_research is a confirmed spend: the preview shows the scope and cost, and the run refuses a scope_hash that does not match it.

Content and publishing

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.

Content Writer and Research Studio editorial tools

These five tools give an AI client the same editorial feed the public REST routes expose, backed by the identical query and authorization code — there is one implementation per capability, so REST and MCP can never drift apart.

status is enforced at the schema boundary, not just inside the handler, so a value outside the documented vocabulary is rejected as invalid_input before anything runs. The accepted target is an allow-list of exactly published: when SearchChamp's internal state machines gain new values, those values do not silently become remotely settable.

Status grouping and what is hidden

status=draft / status=published is a deliberate, stable grouping over internal state machines that have more values and keep growing. Each item's raw value always comes back in its status field.

publishedAt is a SearchChamp timestamp, not a CMS one

Both feeds and both status tools return publishedAt — for research sessions this is research_sessions.published_at, a real column with a real producer. It is null for anything not published, and also null for a session that was published before the column existed.

It records when the status was flipped inside SearchChamp. It is not a CMS publication time, because nothing on this surface talks to a CMS.

Worked example — list drafts, then publish one

Example prompt

Show me the draft articles for example.com, then mark "How to choose SEO tools" as published in SearchChamp. Don't publish it to WordPress.

The client would call list_content_articles to find the id, then set_content_article_status with it.

Step 1 — list_content_articles

curl --fail-with-body 'https://mcp.searchchamp.com/mcp' \
  --header "Authorization: Bearer $SEARCHCHAMP_MCP_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_content_articles",
      "arguments": {
        "site": "example.com",
        "status": "draft",
        "limit": 25,
        "offset": 0
      }
    }
  }'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "37 articles for example.com" }],
    "structuredContent": {
      "articles": [
        {
          "id": "0f2c9c2a-5f6f-4a53-9a1e-2b2a1f5f0c11",
          "title": "How to choose SEO tools",
          "slug": "how-to-choose-seo-tools",
          "status": "ready_for_review",
          "locale": "en",
          "wordCount": 1420,
          "targetKeyword": "seo tools",
          "createdAt": "2026-08-20T09:14:00.000Z",
          "updatedAt": "2026-08-27T16:02:00.000Z",
          "publishedAt": null
        }
      ],
      "total": 37,
      "returnedCount": 1,
      "limit": 25,
      "offset": 0
    }
  }
}

Step 2 — set_content_article_status

curl --fail-with-body 'https://mcp.searchchamp.com/mcp' \
  --header "Authorization: Bearer $SEARCHCHAMP_MCP_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "set_content_article_status",
      "arguments": {
        "article_id": "0f2c9c2a-5f6f-4a53-9a1e-2b2a1f5f0c11",
        "status": "published"
      }
    }
  }'

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{ "type": "text", "text": "Article marked published in SearchChamp." }],
    "structuredContent": {
      "article": {
        "id": "0f2c9c2a-5f6f-4a53-9a1e-2b2a1f5f0c11",
        "status": "published",
        "publishedAt": "2026-08-29T11:02:41.000Z"
      },
      "already_published": false
    }
  }
}

Worked example — read a research session and publish it

Example prompt

Pull up the published research sessions for example.com, read the brief for the Q4 competitor one, and publish the draft session that already has a completed brief.

get_research_session

curl --fail-with-body 'https://mcp.searchchamp.com/mcp' \
  --header "Authorization: Bearer $SEARCHCHAMP_MCP_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_research_session",
      "arguments": { "session_id": "9c1b6f3e-77d4-4c2a-b0aa-3e5c9f2d1a44" }
    }
  }'

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{ "type": "text", "text": "Q4 competitor landscape" }],
    "structuredContent": {
      "session": {
        "id": "9c1b6f3e-77d4-4c2a-b0aa-3e5c9f2d1a44",
        "title": "Q4 competitor landscape",
        "status": "reviewing",
        "publishedAt": null,
        "brief": {
          "briefDocVersion": 1,
          "contentMd": "## Summary\n…",
          "generatedAt": "2026-08-26T13:30:00.000Z",
          "exportedToContentWriter": false
        },
        "pins": [],
        "pinsTruncated": false,
        "keywords": [],
        "keywordsTruncated": false
      }
    }
  }
}

set_research_session_status

curl --fail-with-body 'https://mcp.searchchamp.com/mcp' \
  --header "Authorization: Bearer $SEARCHCHAMP_MCP_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "set_research_session_status",
      "arguments": {
        "session_id": "9c1b6f3e-77d4-4c2a-b0aa-3e5c9f2d1a44",
        "status": "published"
      }
    }
  }'

When a status change is refused

Both status tools accept only a resource already in a publishable state.

A refusal names the current state as data rather than prose, and adds a reason when the status alone does not explain it: empty_body for an article, no_brief for a session. Calling again on an already-published resource is not a refusal — it succeeds, reports already_published, and leaves the original publish time untouched.

Search Console, GA4, and keyword research

These ten tools let an AI client diagnose a page and propose keywords from evidence, without the user switching to the SearchChamp app. Nine are read-only. One — run_keyword_research — spends credits, and only after the end user explicitly confirms a scope they were shown.

Data sources, freshness, and "no data"

Every Search Console and GA4 result names its source, the property, and the exact reporting_range, so a client can always say where a number came from and which dates it covers.

A connection problem is always a named state, never an empty result:

A metric of null means the provider had no data for it. Never read null as zero.

Search Console sync

Search Console performance is read live, so it does not depend on a sync. get_integration_health reports the last manual sync as never_synced, in_progress, ok, partial, or failed, and whether another is possible. A manual sync calls Google on the workspace's quota, so it stays a user-approved action: an Editor or above chooses Sync now on the Search Console page in the app. No MCP tool starts one.

The keyword research workflow

Candidate provenance. A recorded originating provider stays attached when keyword suggestions are reused from cache. A suggestion served through SearchChamp's data gateway returns provenance.provider: "DataForSEO" only when the gateway reports that item's own source as DataForSEO. Gateway results without a per-item source, an unknown source, and older cached suggestions without originating-provider metadata return provenance.provider: null; the app shows provider unavailable. A source label such as “Keyword suggestions” or a transport label such as “cache” is not provider attribution. A cache fetch time is not a measurement date: missing reporting dates remain data_date: null. Re-reading an existing research result preserves its recorded evidence; it does not retroactively infer a provider or refresh its data.

Research is a two-step workflow so that a credit is never spent without the user's agreement.

1. Check what exists. Call get_keyword_inventory (and get_page_keyword_coverage for a specific page) so you do not research what the site already has.
2. Preview. Call preview_keyword_research with the seeds, target market, and optional page URL. Nothing is spent.
3. Ask the user. Show them the scope and the cost (see What research costs).
4. Run, only on a yes. Call run_keyword_research with the same seeds, market, and URL, user_confirmed: true, and the preview's scope_hash. If anything changed since the preview, the call returns confirmation_mismatch and spends nothing — preview again. A scope_hash is valid only on the UTC day it was previewed.
5. Review. Poll get_keyword_research_result with the job_id, and read its result field.

What research costs

The preview's estimated_cost separates three charges, because they are not all known in advance:

Tell the user both parts: the credits to start, and that a successful run records additional usage-based credits.

The target market is never guessed. Give a country and language, or leave both out to use the site's stored keyword market. If the site has no keyword market set, the preview returns market_required rather than researching a default country. English, Spanish, and Arabic markets are supported; any other market returns unsupported_market, and that research is run from the Keywords page in the app instead.

Relevance and location checks. The research uses the same rules as the Keywords page in the app. A term that does not match the seed topic is rejected as off_topic. A term that names a place outside the target market — for example a New York term in a United Arab Emirates run — is rejected as off_market, unless the user named that place in a seed. Rejected terms are listed in outcome.rejected_sample with their reason; they are never returned as recommendations.

An empty result always has a reason. Read result, not status: a run that finds nothing new is recorded as failed internally so that its start credit is returned, and it comes back as result: "empty". outcome.reason and outcome.explanation say which of these happened:

outcome.stage_counts reports how many terms were proposed, unique, rejected (unobserved, off-topic, off-market), duplicated (within the run, or already in the library), and accepted.

Worked example — preview, confirm, and run research

Example prompt

Find new keywords for our iOS app development page in Dubai. Tell me what it costs before you run anything.

Step 1 — preview_keyword_research

curl --fail-with-body 'https://mcp.searchchamp.com/mcp' \
  --header "Authorization: Bearer $SEARCHCHAMP_MCP_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "preview_keyword_research",
      "arguments": {
        "site": "example.ae",
        "seeds": ["iOS app development Dubai"],
        "country": "AE",
        "language": "en",
        "url": "https://example.ae/ios-app-development-dubai"
      }
    }
  }'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "Preview only — nothing was spent. Researching 1 seed(s) for AE / en costs 2 credit(s) to start (the start credit is returned if nothing new is found), plus usage-based credits if candidates are found. Ask the user to confirm this scope and cost before calling run_keyword_research." }],
    "structuredContent": {
      "action": "preview",
      "scope": {
        "site": "example.ae",
        "seeds": ["iOS app development Dubai"],
        "market": { "country": "AE", "location_code": 2784, "language_code": "en", "source": "explicit" },
        "target_url": "https://example.ae/ios-app-development-dubai"
      },
      "estimated_cost": {
        "start_credits": 1,
        "tool_call_credits": 1,
        "minimum_total_credits": 2,
        "recent_usage_credits": { "completed_runs_last_90_days": 4, "average": 3.6, "maximum": 5.2 }
      },
      "daily_runs": { "limit": 20, "used": 3, "remaining": 17 },
      "existing_coverage": {
        "keywords_in_this_market": 57,
        "seeds": [{ "seed": "iOS app development Dubai", "already_in_library": true }]
      },
      "can_run": true,
      "blockers": [],
      "confirmation": { "scope_hash": "5f0c9c2a5f6f4a539a1e2b2a1f5f0c11" }
    }
  }
}

The client now tells the user the scope, the 2 credits to start, and that a run returning candidates also records usage-based credits (recently about 3.6 on this site) — and waits for a yes.

Step 2 — run_keyword_research, after the user confirms

curl --fail-with-body 'https://mcp.searchchamp.com/mcp' \
  --header "Authorization: Bearer $SEARCHCHAMP_MCP_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "run_keyword_research",
      "arguments": {
        "site": "example.ae",
        "seeds": ["iOS app development Dubai"],
        "country": "AE",
        "language": "en",
        "url": "https://example.ae/ios-app-development-dubai",
        "user_confirmed": true,
        "scope_hash": "5f0c9c2a5f6f4a539a1e2b2a1f5f0c11",
        "idempotency_key": "ios-dubai-2026-10-06"
      }
    }
  }'

Step 3 — get_keyword_research_result

curl --fail-with-body 'https://mcp.searchchamp.com/mcp' \
  --header "Authorization: Bearer $SEARCHCHAMP_MCP_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_keyword_research_result",
      "arguments": { "site": "example.ae", "job_id": "9c1b6f3e-77d4-4c2a-b0aa-3e5c9f2d1a44" }
    }
  }'

Limits

• run_keyword_research is OAuth only. A user-generated token can preview research and read a result, but cannot start a run, because a token has no signed-in user to give the confirmation.
• Research runs are capped per site per day; the preview reports how many remain.
• get_integration_health does not contact Google, so it cannot tell that an authorisation was revoked. A performance read reports that as needs_reconnect.
• get_page_keyword_coverage reads stored data. status: "no_stored_data" means nothing is stored for that page — the integration may not be connected, the nightly join may not have run yet, or the page may have no impressions. Use get_integration_health and get_search_console_performance to tell which.
• Page tools accept only a URL on the addressed site's own domain. Anything else returns url_not_on_site.

Custom-site publication artifacts

Page Optimizer apply and verification

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

The caller supplies a stable idempotency_key so reconnects/retries do not enqueue equivalent generation work twice.

Actions, natural-language answers, and jobs

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, llms.txt reads, the editorial reads list_draft_articles, get_article_content, list_content_articles, list_research_sessions, and get_research_session, and — with mcp:act — the two status tools set_content_article_status and set_research_session_status.
• Business/Pro and higher: also the ten Search Console, GA4, and keyword read tools — get_integration_health, get_search_console_performance, get_ga4_performance, get_keyword_inventory, get_keyword_clusters, get_page_keyword_coverage, get_keyword_page_coverage, get_page_diagnosis, preview_keyword_research, and get_keyword_research_result.
• Business/Pro and higher Full tokens: also generate_llms_txt through mcp:spend.
• run_keyword_research remains OAuth-only even for a Full token: it spends on the end user's explicit confirmation, and a token has no signed-in user.
• Approval, action-decision, ask_atlio, mark_applied, and CMS publishing tools (start_publish, report_publish, publish_article) remain OAuth-only. The two set_*_status tools are not CMS publishing and are available to Business/Pro+ tokens holding mcp:act.

The organization plan is evaluated at call time. Downgrading can immediately reduce a token's visible catalog; upgrading expands it without reminting the token.