Workflows, security, and troubleshooting

Example prompts

Address a site by exact domain when possible:

List my SearchChamp sites, then summarize the latest ranking movers, AI Visibility, audit findings, and opportunities for example.com. Tell me which data is not set up yet.

For example.com, list draft articles ready to publish. Pull the full content for the strongest one and check it against the site's brand voice before suggesting edits.

List approved Page Optimizer changes for example.com. For each accepted change, show the exact before/after content and selector hints, but do not claim it is applied until the live deployment is complete.

Show the current llms.txt configuration and the latest two versions for example.com, then return their exact diff. Do not generate a new version.

Direct JSON-RPC calls

Most people should let an MCP client negotiate and call tools. For protocol debugging, a bearer-token request looks like this:

export SEARCHCHAMP_MCP_TOKEN='atl_mcp_your_token_here'

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": "get_rankings",
      "arguments": {
        "site": "example.com",
        "days": 14,
        "limit": 10
      }
    }
  }'

A tool response is nested inside the JSON-RPC result:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "Rank movers for example.com" }
    ],
    "structuredContent": {
      "days": 14,
      "movers": []
    }
  }
}

Notifications without an id return HTTP 202 with no body.

Recommended workflows

Start a diagnostic session

OAuth: list_sites → get_site_snapshot → drill into get_rank_movers, get_audit_issues, get_opportunities, or get_ai_visibility.

Token: list_sites → get_rankings and get_ai_visibility; on Business/Pro+, add the catalog's audit, backlink, content-draft, and volatility reads.

Publish from a coding agent

OAuth only:

1. list_draft_articles with the site.
2. get_article_content with the selected article UUID.
3. get_brand_voice and optionally get_page_recommendations.
4. start_publish immediately before editing/publishing; this creates a 30-minute claim.
5. Publish to the customer's own repository or CMS.
6. report_publish with the article UUID and canonical URL on that site's domain.
7. Let SearchChamp independently verify the live page.

To have SearchChamp publish through a connected WordPress or Shopify integration, call publish_article and poll get_job. The server may return feature_disabled or a connection/plan refusal; never interpret those as a successful publish.

Apply a Page Optimizer change

1. list_approved_changes → select accepted or applied_unverified work.
2. get_change → use the exact before/after bytes; selector hints are suggestions, not guaranteed selectors.
3. Edit, test, and deploy the customer's source.
4. OAuth only: call mark_applied after the public page contains the deployed change.
5. SearchChamp re-crawls independently and returns verified or applied_unverified with a reason.

Generate llms.txt safely

Call get_llms_txt first. If generation is needed, use a stable idempotency_key such as your own job UUID with generate_llms_txt, then poll get_llms_txt_job. Reusing the same key reuses equivalent work rather than creating duplicates.

Security model

• OAuth identity: the access token is signature/issuer/client/expiry verified, the consented organization is recovered server-side, and site access follows the signed-in user's current grants.
• Token identity: atl_mcp_... is hashed at rest and resolves to one organization plus an optional hard site lock. It is not tied to the minter's future user permissions.
• Tenant isolation: every data read carries explicit organization/workspace/site predicates. Foreign and nonexistent IDs receive indistinguishable not-found results where disclosure would leak existence.
• Least privilege: scope checks and token catalog gates run before argument handling and tools. Unknown scopes/tools fail closed.
• Approval boundary: natural-language spending commands are proposed rather than silently run. Publish/apply tools require mcp:act, and product/CMS enablement gates still apply.
• Independent verification: report_publish and mark_applied are claims, not proof. SearchChamp fetches the live URL itself before settling verification.
• No secrets in logs: never put a token in prompts, arguments, URLs, screenshots, or tickets. Store it in an environment variable or secret manager.

Limits and usage

Every served tool has a non-zero credit cost shown in the tool reference. The organization-wide monthly usage ceiling applies across MCP and other metered SearchChamp work. Cheap reads are still metered; invalid/denied calls do not debit successful tool work.

Rate-limit failures return HTTP 429 with { "error": "rate_limited", "scope": "token" | "org" }. Pause and retry with backoff. Do not mint multiple tokens to evade a limit.

Errors and fixes

Client-specific troubleshooting

• OAuth loop: remove the connector from the AI app, add the fresh URL from SearchChamp, and sign in again. Stale sessions on either side are the common cause.
• Tools work but the client cannot see a new one: start a new conversation or reconnect so the client refreshes tools/list.
• Claude Desktop token config fails: confirm Node/npm is installed for npx mcp-remote, retain the exact Authorization:${AUTH_HEADER} argument, and restart the desktop app.
• Cursor rejects the config: remove type; Cursor uses url + headers.
• Claude Code/VS Code rejects the config: include "type": "http".
• Codex cannot authenticate: export SEARCHCHAMP_MCP_TOKEN in the same shell that launches Codex and check that the configured bearer-token variable name matches.
• Unexpectedly small token catalog: check the current organization plan, token read versus full scope, and optional site lock. Token catalogs are intentionally smaller than OAuth.

Revoke access

• OAuth: remove the active connection under Settings → Connect your AI apps. Revocation is immediate; remove the connector from the AI client as a separate cleanup step.
• Token: revoke it under Settings → MCP Tokens. Any later call with that bearer returns unauthorized. Create a replacement because plaintext tokens cannot be recovered.

If a token may have leaked, revoke it first, rotate the consumer, then inspect the token's Last used timestamp and relevant activity/audit logs.