Connecting Rankability to AI assistants with MCP

Connect Claude, Codex, or another MCP-compatible assistant to Rankability in a few clicks, then ask it where your clients are missing from AI answers and search results.

Rankability hosts a remote Model Context Protocol server, so there is nothing to install. Your assistant signs in to Rankability and gets scoped access to your organization’s clients, reports, and tools.

Connect Claude

Rankability is listed in Claude’s connector directory.

1. In Claude, open Customize → Connectors and select Discover.
2. Enter Rankability in Search connectors, open the listing, and select Connect to Claude.
3. Sign in to Rankability and approve access.

On Team or Enterprise, an Owner selects Connect for your team first. Members then connect with their own Rankability sign-in.

Claude refreshes access automatically. The connection stays tied to the Rankability organization you were signed in to when you approved it.

Try your first prompt

Paste this into a new conversation, replacing the client name:

Use Rankability to show where Acme Plumbing is missing from AI answers and top search results, and which pages I should target first.

It works once the client has at least one Tracker report. It reads your existing results and does not start new scans. Before you approve any action that runs new work or uses credits, the assistant shows the cost and asks you to confirm.

To check which organization the assistant is connected to first, ask: Use Rankability to show my organization and usage limits without starting any work.

Hosted MCP endpoint

For assistants that are not in a directory, add this endpoint as a custom connector or remote MCP server:

https://app.rankability.com/mcp

The endpoint supports OAuth sign-in and Rankability API keys that begin with rk_live_. Settings → API keys → Connect Claude or Codex checks the endpoint and copies the configuration for you.

Connect Codex with OAuth

1. In the Codex desktop app or IDE extension, open Settings → MCP servers → Add server.
2. Choose Streamable HTTP, enter https://app.rankability.com/mcp, save, restart, and select Authenticate.
3. Use /mcp to confirm Rankability is active.
4. Run the read-only verification prompt shown in Rankability.

Rankability can copy this OAuth configuration for you:

[mcp_servers.rankability]
url = "https://app.rankability.com/mcp"
auth = "oauth"
default_tools_approval_mode = "writes"

Connect v0 with OAuth

1. In v0, open the + menu in the prompt box and select MCPs → Custom MCP.
2. In Add Custom MCP Connection, enter Rankability as the Name and https://app.rankability.com/mcp as the URL, then choose OAuth under Authentication.
3. Select Authorize, sign in to Rankability, and approve access on the consent screen.
4. Make sure Rankability is enabled for the chat, then ask, for example: Use Rankability to audit this page for SEO and AI search visibility.

v0 uses Rankability’s tools while it generates. The code v0 writes can’t call Rankability directly.

Use a scoped API key when OAuth is unavailable

OAuth is the preferred connection. For a client that requires a Bearer token, create a key under Settings → API keys with only the scopes the assistant needs and store it as a secret.

{
  "mcpServers": {
    "rankability": {
      "url": "https://app.rankability.com/mcp",
      "headers": {
        "Authorization": "Bearer rk_live_YOUR_API_KEY"
      }
    }
  }
}

Store the key as a secret. Never commit it or put it in browser-delivered code.

For Codex, Rankability can copy an environment-variable configuration that reads the secret from RANKABILITY_API_KEY rather than placing it in the file.

Current tools

The server registers 131 general-account tools. Entity-only research is available to all Rankability organizations. Account terms, granted scopes and deployment enablement still control whether a call is authorized. The MCP surface also includes client campaign records, Serena consultation, saved Prospector, backlink-profile reads and confirmed refresh, GBP-audit, Batch URL Analyzer, Routine, publishing evidence and confirmed draft delivery, durable job reconciliation, and structured manifests alongside clients, Knowledge, usage, GSC, Researcher, Copywriter, Optimize, Tracker, Help Center, Crawler, Search Intelligence, Page Auditor, and Site Auditor.

Clients and account

• list_clients, resolve_client, get_client, get_client_overview, create_client, update_client_profile, delete_client, and create_client_connect_link
• get_client is the lightweight identity and configuration read. It includes the effective Copywriter brand/profile, approved workspace Tracker aliases, the connected primary GBP name, plus do_not_use, blocked_keywords, and excluded_topics. update_client_profile patches the client, can update approved workspace Tracker aliases, and can merge selected Knowledge fields without clearing omitted nested settings. A Tracker report’s explicit GBP name remains a project setting managed with update_tracker_project; changing workspace aliases does not retroactively re-score stored history.
• list_client_sources, get_client_source, get_client_source_contradictions, create_client_source, import_client_source_file, update_client_source, and delete_client_source manage Knowledge sources. Lists return compact metadata only; request one source in full when its body is needed. A source can contain up to 250,000 characters and remains one logical source while Rankability chunks it for indexing. create_client_source handles pasted text. import_client_source_file accepts the complete UTF-8 text of one .md, .markdown, or .csv file; the assistant reads the local file and sends its text, while Rankability never receives or opens the local path. Both tools can classify sources as research, competitor context, entity facts, and the other existing Knowledge roles; mark internal research as usage=reference_only; and use upsert_by_name=true to update one exact-name match or create it when absent. Duplicate matches fail closed. Reference-only sources remain readable but are not inserted into automatic Copywriter prompts, even when selected or priority. Create, import, and content-changing update responses expose usage, current indexing state, and a durable contradiction-check receipt. When that receipt is scheduled, poll get_client_source_contradictions for a completed zero-result, skipped reason, failure, or findings.
• get_client_overview adds Tracker, content, and audit state and reports brand_alignment. Treat divergent as a configuration warning: Tracker and Copywriter may be measuring or generating for different brand names.
• get_usage_and_limits for the connected organization (id and name), pooled percentage windows, and recovery times
• get_usage_events for a paginated audit trail of completed outcomes. Shared-credit accounts include signed credit amounts and resulting balances. Pooled accounts identify included work without inventing per-action prices or exposing internal capacity units.
• estimate_usage_impact for a read-only standard/high workload estimate
• Use get_usage_and_limits for the active contract; do not substitute an older credit-balance endpoint

Serena consultation

• consult_serena asks Serena one strategic question scoped to a required client workspace.
• Serena can ground the answer in the client’s selected Knowledge sources, saved workspace evidence, durable client memory, Rankability methodology, relevant SOP skill guidance, and canonical Help Center articles.
• The tool is read-only. It does not start scans, run audits, modify projects, publish, or perform live web research. Use separate scoped tools and their normal confirmation flow for actions.
• Ordinary consultation uses bounded excerpts, not certified whole-document inspection. get_client_source_section reads exact original sections. Where enabled, review_knowledge_document starts an explicitly confirmed, usage-bearing background review; get_knowledge_document_review reads its saved coverage and completed answer. See Serena consultation for limits and completion semantics.

Tracker performance and attribution

• get_search_performance reads saved, filtered Google or Bing performance. get_search_performance_catalog lists properties, retained dates, dimensions and sync state; get_search_performance_views lists views owned by the current user or API key.
• export_search_performance explicitly prepares a private CSV for the selected view. Use a stable idempotency key and poll get_search_performance_export. The download requires the same authenticated identity and expires after one hour.
• get_website_analytics reads connected GA4 AI Assistant and Organic Search cohorts, landing pages, key events and eligible attribution credit. get_website_analytics_catalog discovers the client’s connected property and outcome definitions. These are reporting reads; they do not change collection or recover hidden AI referrals.
• get_agent_analytics reads independent saved crawler requests, Tracker citations and GA4 outcomes. get_agent_analytics_catalog lists saved analyses and source availability. Automatic crawler collection is deferred; these tools do not connect providers, ingest logs or start analyses. A crawler request or citation does not establish that it caused a visit or conversion.

These tools preserve workspace authorization and report missing coverage and unsupported filters explicitly. Search-performance reads and exports do not start source syncs or scans. GA4 reporting reads may call the connected reporting API.

Researcher

• researcher_run starts an asynchronous keyword-research job in discover, trending, reddit, youtube, or ecommerce mode
• researcher_get polls one job; use the default status view while work is running, then request full after completion
• researcher_list returns bounded, compact job history
• list_researcher_projects and get_researcher_project read saved Researcher projects; project keywords are paginated, and saved projects are separate from Agent API job results

Before starting research, resolve the client when client Knowledge or GSC should ground the run. Call get_usage_and_limits, then estimate_usage_impact with operation: "researcher_run"; show the result, obtain approval, set confirm_usage: true, and provide a stable idempotency_key. A reusable cache hit can complete immediately without usage. Otherwise the job runs asynchronously. Do not repeatedly request the full result while polling.

Copywriter and Autopilot

• list_content_projects, get_content_project, get_content_artifacts, and get_copywriter_queue_status
• create_content_auto, create_content_stepped, and approve_brief
• update_content_brief edits a stepped-mode brief before approval; replace_content_draft replaces a settled project’s complete body; delete_content_project permanently removes one project and its artifacts
• create_content_autopilot and get_autopilot_status

Before starting any generated content workflow, choose the client workspace and page structure. The three creation tools require client_id plus page_contract (article or commercial_service). create_content_auto, create_content_autopilot, and approve_brief require an approved usage-impact estimate and confirm_usage: true. The deprecated confirm_cost alias remains compatible, but new integrations should use confirm_usage. For retryable automations, provide a stable idempotency_key so a reconnect does not start duplicate work.

Copywriter reads preserve project provenance. creation_source: "agent_api" identifies an Agent-created job and supplies mode: "auto" | "stepped" (including the legacy default when only the originating API key was recorded). creation_source: "web_app" returns mode: null. A web project saved before generation reports status: "draft" with progress.stage: "not_started"; queued is reserved for an Agent API handoff waiting for background processing.

get_content_artifacts can also request blocks or gutenberg for a structured publishing handoff. Brief edits, complete draft replacement, and deletion require an explicit confirmation plus a stable idempotency key. Draft replacement refuses an actively running job and clears score and review artifacts that belonged to the prior body.

Entity-only research

• estimate_entity_research checks the existing Quick/Optimize usage contract for 1–5 topics without starting work. Show its estimate and obtain approval before extraction.
• extract_entities researches 1–5 distinct topics for an owned client using the selected research sources and shared entity engine. Supply confirm_usage: true and a stable idempotency_key. Optional location and content intent guide relevance. Each topic creates one saved research report; no outline or draft is generated.
• get_entity_research polls one returned job ID. Completed results default to a compact list of prioritized entities, aliases, writing eligibility, source counts, and coverage. It starts no new work. Use view: "full" to retrieve literal source evidence. Reads return up to 50 entities by default; use limit (1–100) and offset, and follow entity_pagination.has_more to read the remaining entities. Incomplete coverage is distinct from an exhaustive report.

For requests such as “extract entities for this keyword,” use these entity-only tools. A content brief and brief approval are not required. get_content_artifacts also returns compact entities by default; use entity_view: "full", entity_limit, and entity_offset when reading detailed entity evidence from an existing content project.

Keep the same request and idempotency key when retrying a partially accepted batch: accepted IDs are reused and only unaccepted topics start. Requests remain scoped to the organization that authenticated the connection. A readable historical report can require revalidation before new writing; merely retrieving it does not revalidate or charge it.

Tracker and optimization

• list_tracker_projects, get_tracker_project, get_tracker_results, get_tracker_trends, get_tracker_matrix, get_tracker_sources, get_tracker_citation_analysis, get_tracker_competitors, get_tracker_summary, get_tracker_seo_performance, get_tracker_brand_summary, get_visibility_summary, compare_visibility, get_client_visibility_gaps, and get_notifications
• tracker_capabilities performs the read-only entitlement and client dependency preflight. Its capacity block reports the organization’s report limit, how many reports count against it, and the remaining slots, using the same check that create and upsert enforce, so check remaining_slots before creating a batch of reports. upsert_tracker_project is the preferred declarative write: run it first with dry_run: true, then confirm the exact desired configuration and repeat with the same idempotency key. It updates an exact client/topic report in place, preserves history, and does not start a scan.
• get_tracker_project defaults to a compact summary without the duplicated provenance snapshot. Request full only when run-attempt provenance is needed, or select specific top-level fields. get_tracker_results likewise defaults to compact measurements; its full view adds complete AI answers, citations, sentiments, and provider diagnostics.
• get_visibility_summary reports a client’s AI mention and citation rates (overall, per platform, and per project), organic positions, local pack position, top competitors, and most-cited domains from existing results, with no scan and no usage. It matches the brand name, aliases, and GBP location name, and excludes failed or unscanned cells from rates. compare_visibility compares two dates like for like and lists gained or lost mentions and citations, position changes, and new or lost competitors. Both are compact by default; request full for per-cell evidence.
• get_tracker_results also accepts view: summary, a platforms filter, include_all_results for the full Google, Bing, DuckDuckGo, Brave, and Local Pack lists (capped by all_results_limit), and client_missing_only. Local Pack grids collapse to one representative cell with grid coverage unless local_grid is points or all. Every response names project_id, client_id, and keyword.
• get_tracker_matrix returns a bounded client keyword × platform table in one call. It preserves position, mention, citation, URL, freshness, data_state, and comparison_state rather than requiring one detail request per keyword. view: summary returns per-project counts and missing platforms; client_missing_only keeps only completed checks where the client is absent.
• get_client_visibility_gaps answers “where is this client missing?” in one call: every ranking or AI-cited page across the client’s reports that does not mention the client, deduplicated and classified (directory list, “best of” list, review platform, info page, community thread, competitor site, lead-gen doorway), matched to the client’s market, and prioritized, plus AI answers that omit the client and queries outside the organic top 10 or Local Pack top 3. Check ready before treating the list as final. While it is false, source_check_progress shows what is checked or pending and when to repeat the same request. Doorway, wrong-city, and off-topic pages are hidden unless include_excluded is set, and pages the app could not read are marked unverified. By default it reads the client’s scheduled reports (the same ones Serena counts), or every active report when none are scheduled. Scope it with project_ids or a campaign_id to include exactly those reports. It is compact and paginated by default.
• get_tracker_sources lists every ranking and AI-cited page from a scan with whether it mentions the client, plus its page type, market match, and opportunity; client_missing_only finds pages that rank or are cited without mentioning the client. get_tracker_citation_analysis and get_tracker_competitors return the saved citation analysis and the top organic competitors the Tracker report shows.
• A check that failed, including a search that returned an empty results list, reads data_state: failed. It is never reported as not ranked or counted as missing; re-run it instead.
• create_tracker_project, update_tracker_project, and delete_tracker_project expose the existing organization-scoped Tracker lifecycle. One project represents exactly one keyword. Creation does not run an immediate scan and defaults to benchmark mode (auto_track_enabled: false); recurring tracking must be explicitly approved. Every mutation requires a stable idempotency_key and its matching confirmation field. Permanent deletion also requires the exact current keyword returned by get_tracker_project.
• The older list_reporter_projects, get_reporter_project, and get_reporter_summary names remain compatibility aliases. Tracker is the product name; reporter remains only in legacy tool IDs, scopes, and API paths.
• trigger_scan and optimize_page; estimate first, obtain approval, set confirm_usage: true, and provide a stable idempotency_key for retries
• optimize_page returns an optimization_id immediately. Poll optimization_get with view: "status", then retrieve summary or full after completion. optimization_list returns bounded saved history and can filter by attributed client, status, keyword, or URL.
• get_gsc_search_performance reads connected Search Console evidence at query, page, or query-page grain. It defaults to 28 days, caps a request at 120 days and 100 rows per page, and reports impression-weighted position plus sync freshness.

Client campaigns

• list_campaigns, get_campaign, create_campaign, update_campaign, append_campaign_log, save_campaign_snapshot, compare_campaign_snapshots, and attach_campaign_document
• A campaign is the shared record for a bounded piece of client work, such as 12 weeks to become the best plumber in one city. It holds the goal, market, dates, facts, rules, open questions, and a prompt set that points at existing Tracker reports (one cluster or a list of reports). Creating or updating a campaign never creates, schedules, or scans a report. Writes require a confirmation where noted and a stable idempotency_key.
• get_campaign is compact by default: week N of M, each report’s latest scan status, the latest snapshot’s headline numbers, recent log entries, and open decisions and handoffs. Request include_log_detail only when you need the full text.
• append_campaign_log records actions, decisions, notes, and handoffs. Decisions start as proposed. Approve or reject one, or close a handoff, by appending a new entry with resolves_entry_id; earlier entries are never rewritten.
• save_campaign_snapshot freezes a labeled reading (Week 0 first, then Week N) from data Rankability already stores: the Tracker visibility summary for the prompt set, with its caveats, plus the Search Console clicks and impressions and GA4 organic sessions and key events that the SEO performance dashboard shows for the same dates. Each source records how many days in the range had data; when data is missing, the total is marked partial and is not compared with other snapshots. Snapshots saved before this change summed stored rows, so they are marked partial with an explanation. It never starts a scan or sync and uses no usage. compare_campaign_snapshots compares the baseline with the latest snapshot by default, and compare_visibility accepts saved snapshots as before_snapshot_id and after_snapshot_id.
• Serena sees a short summary of each active campaign in client chat, so teammates and agents work from the same goal, decisions, and handoffs.

Page and site auditing

• page_audit_run, page_audit_batch_upsert, page_audit_get, page_audit_list, and page_audit_delete; every run requires a stable idempotency_key. Use the batch tool’s dry_run before confirming usage, then poll its returned ID with jobs_status.
• jobs_status reconciles one or up to 50 job IDs with normalized progress, terminal reasons, output IDs, timestamps, and polling guidance. Pass client_id instead to see every Tracker scan for a client in one call, with each project’s scan_state (queued, running, complete, partial, failed_needs_rerun, canceled, or never_scanned). audit_manifest_get inventories client Tracker, audit, research, and content artifacts with explicit lifecycle and comparison state. exports_get returns either that manifest or paginated Page Audit, Site Audit-page, and Tracker result rows as JSON or CSV without browser export clicks.
• site_audit_estimate, site_audit_run, site_audit_get, site_audit_get_page, site_audit_list, site_audit_cancel, and site_audit_delete; a run requires confirm_usage: true plus a stable idempotency_key, while reads default to bounded status/summary views and paginate full inventories
• site_audit_get returns grouped issue-type totals and bounded affected-URL samples. Its full view accepts explicit page_fields and omits analyzed page text by default. Use site_audit_get_page for one page’s body or duplicate-content evidence instead of loading every page body.

Prospector outreach lists

• prospector_list_lists and prospector_list_items read bounded saved client outreach state, including pipeline counts and optional status filtering.
• prospector_create_list, prospector_add_item, prospector_update_item, prospector_delete_item, and prospector_delete_list require explicit confirmation and stable idempotency keys.
• Adding an item canonicalizes and de-duplicates its URL within that list. Updating status records identified, contacted, in_discussion, won, or passed only; Rankability does not send outreach from these tools.
• These tools do not run live backlink analysis, prospect discovery, enrichment, scraping, email, or contact actions. Those capabilities remain separate and unavailable through this MCP contract.

Backlink profile

• get_backlink_profile reads one saved summary, history, anchors, or top_pages section for a client and reports the snapshot timestamp and freshness.
• backlink_profile_refresh creates or refreshes the four saved aggregate sections for one domain variant. Estimate first, obtain approval, confirm usage, and reuse a stable idempotency key. Snapshots newer than six hours are reused without duplicate provider work.
• History is limited to 1–12 months; anchor and top-page rows are paginated at no more than 100 rows per call. Missing saved evidence is data_state: "unavailable", not zero.
• The read tool never invokes the provider. The refresh tool cannot load the individual backlink list or export rows; those capabilities remain unavailable through MCP.

Saved GBP and Batch URL artifacts

• gbp_audit_list and gbp_audit_get read saved audits. Summary excludes raw review/question bodies; full adds only bounded checkpoints and competitor aggregates.
• batch_url_list and batch_url_get read saved run history and paginated URL rows. Null stays null, rows report complete/partial/error state, and legacy credit units are omitted.
• These tools never resolve a listing, call external search-data services or connected Google services, start an audit, or analyze URLs. New GBP and Batch URL runs remain unavailable through MCP.

Routines and publishing

• routine_list and routine_get read recurring content and Knowledge-monitor Routine state. Topics and source IDs are bounded; previously published and suggested topic bodies remain omitted.
• publishing_list_connections returns connection status, safe target identity, capabilities, and requirements without credentials. Legacy destinations whose target is stored with encrypted credentials return target: null.
• publishing_prepare_artifact creates or reuses an immutable destination-specific snapshot of a saved Copywriter draft. It does not contact the destination or create a remote item.
• publishing_list_deliveries and publishing_get_delivery read saved delivery receipts, preflight and validation defect categories, source currency, safe HTTP(S) remote identity, and validation state without evidence summaries, article bodies, or diagnostic messages.
• publishing_preflight checks one saved article against a connected destination’s field mapping and readiness rules before anyone attempts a delivery. It is read-only: it never creates a delivery, contacts the destination, uses credits, or approves live publishing.
• publishing_request_draft_delivery requires the same reviewed connection and artifact IDs, a stable idempotency key, and confirm_delivery: true. It can create only a destination draft or reviewable GitHub pull request; GitHub also requires the exact preview hash returned by preflight. MCP does not expose live publishing.
• These tools cannot create, edit, enable, disable, or run a Routine; test or reconnect a destination; publish content live; validate a remote item; or retry a delivery.

Help Center

• search_help_center searches the canonical published Help Center by text, category, or slug
• Compact results include titles, summaries, categories, and canonical URLs. Request full only for the small set of article bodies needed for the current task.

Crawler and Search Intelligence

• get_crawler_usage reads the current instance-level daily page quota without starting work
• scrape_page fetches one public page and can return a query-focused excerpt of at most 8,000 characters; an eligible freshness-cache hit is organization-scoped
• start_crawl starts a bounded asynchronous crawl of at most 200 pages and depth 5; get_crawl uses status, summary, and paginated field-selected full views
• extract_page_data produces a grounded answer, highlights, or caller-defined fields from exactly one URL, organization-owned crawler page, or supplied text. Missing evidence remains null or explicitly unanswered.
• search_intelligence_run fans one query out to selected Google and AI search providers; search_intelligence_get reads the saved run. Summary view reports completion and counts without answers, citations, organic results, or raw payloads. Full normalized results and raw upstream payloads are separate opt-ins.

These operations can invoke fetchers, browsers, extraction models, or search providers. Read usage and crawler quota, estimate crawler_scrape, crawler_crawl, crawler_extract, or search_intelligence_query, show the scope, obtain approval, and reuse a stable idempotency key. Crawler page IDs and caches are organization-scoped; a foreign page is returned as not found.

Built-in workflows and references

MCP clients that expose server prompts can discover sixteen read-first workflows, including client_baseline, ai_visibility_gap, keyword_diagnosis, stale_data_sweep, brief_first, monthly_client_report, portfolio_leaderboard, and tracking_setup_plan. Consequential workflows stop after the usage-impact estimate; they do not start work in the same prompt step.

Clients that expose resources can lazily load Rankability’s SPI methodology, Tracker glossary, free-first workflow guide, live usage/price contract, client directory, and templated client or Tracker summaries. The price resource calls the current usage endpoint rather than embedding a stale price table.

Usage and limits

MCP uses the same pooled usage as the Rankability application. Call get_usage_and_limits to read the rolling percentage windows, then call estimate_usage_impact before consequential work. For Researcher, pass operation: "researcher_run"; for a Tracker scan, pass operation: "trigger_scan" plus the Tracker project_id. These reads do not start work. Creating a benchmark Tracker project also starts no scan. Enabling recurring tracking schedules protected future work, so show and confirm the exact schedule before creation or update. Run and write tools require explicit confirmation and a stable idempotency key. Permanent deletion tools also preflight the current record and require its exact name, topic, or keyword. If on-demand usage is temporarily limited, the tool returns 429 usage_limit_reached with retry_at; scheduled tracking remains protected.

Missing Tracker data is not zero

Tracker responses label unavailable measurements explicitly. not_tracked means the platform was not selected, no_scan means no completed measurement or failed attempt exists, failed means the latest attempt ended before producing results and needs a rerun, not_ranked means a completed traditional scan did not find the target, and no_history means a current measurement exists without an earlier comparable measurement. SPI and change fields are null when their measurement or comparison does not exist.

Interpret Copywriter scores

Completed content scores include overall_max: 100. Each entry in category_details includes its raw score, max_score, and normalized percentage. The category maxima are not all 100: Copywriting and Uniqueness are each 20; SEO and Coverage are each 15; Readability, Structure, and Credibility are each 10.

The score also returns calculated_at, scored_revision, draft_revision, freshness_state, score_source, category_total, overall_category_delta, category_model, and calculation_state. Request draft and quality_score together and require freshness_state: "current" when an automation needs proof that the score belongs to that saved body. stale belongs to an earlier draft; unverified is normally a historical row without enough provenance. Current seven-category scores are consistent when their categories sum to the stored overall. Preserve legacy_mismatch, legacy_categories, or partial_categories; use the stored overall and do not invent weighting or add mismatched categories together.

Read editor targets and close keyword gaps

get_content_project returns target_word_count_min/max as soon as the brief is ready. get_content_artifacts can request include: ["word_count_target"] before drafting. This is the editor’s actual range, not the brief’s separate single-number drafting hint; fallback ranges are labeled.

After saving a draft, request include: ["keywords", "quality_score"]. keywords reports coverage, usage, ignored state, score eligibility and required verification. Page with keyword_limit (default 50, maximum 100) and keyword_offset until keyword_checklist.has_more is false. Before drafting, coverage is null. These reads use saved content and recommendations; unsaved browser-local custom keywords and edits are not included. Research-only guidance must not be treated as permission to invent a client service or fact.

Use score.editor_breakdown for coverage and placement components, keyword counts, and placement checks. Its calculation_state: "available" is separate from the legacy seven-category categories_unavailable state. Reads neither regenerate research nor start paid scoring. If Claude has cached older tool definitions after a release, refresh/reconnect the integration to discover the new include choices and pagination inputs.

Interpret client configuration and integrations

get_client returns a structured business_scope. primary_location identifies its source, while service_areas are populated only from the latest completed GBP audit. service_areas_state: "unavailable" means Rankability has no structured service-area evidence; do not derive a definitive list from audience prose.

Integration objects separate connection state from operational freshness. health can be healthy, connected, syncing, no_sync, error, auth_error, or not_connected. Scheduled GSC and GA4 connections expose data_through_date, last_successful_sync_at, and last_full_backfill_at as distinct concepts. last_sync_date and last_sync_at remain compatibility aliases for data_through_date and last_successful_sync_at. On-demand GBP, YouTube, WordPress, and Webflow connections return the same telemetry shape with null sync timestamps rather than inventing a refresh time. WordPress can additionally expose publish_health (healthy, warning, failing, or no_activity) from recent delivery attempts.

Manage or revoke access

• Manage OAuth clients under Settings → Connected apps. Revoking an app invalidates its access and refresh tokens.
• Manage API-key connections under Settings → API keys. Delete or rotate the key to revoke that connection.

Security

• Use least-privilege scopes.
• Confirm the active organization during OAuth consent.
• Review consequential or high-impact actions before approval.
• Revoke connections that are no longer used.

Troubleshooting

• No tools appear: Restart the MCP client, then confirm the endpoint and authentication.
• Endpoint check fails in Rankability: Wait and retry before changing assistant configuration. A ready discovery response returns an authentication challenge with Rankability resource metadata.
• An expected published tool is missing: Reconnect the assistant so it reloads the server registry. If it remains absent, record the visible tool list and Rankability build ID; changing scopes cannot add a tool definition the server did not register.
• A tool call is forbidden: Reauthorize with the corresponding read, run, or write scope.
• Unauthorized: Reauthorize the OAuth client or replace an expired, revoked, or malformed API key.
• Wrong organization: Revoke the OAuth connection, switch to the intended Rankability organization, and authorize again.
• The verification result shows the wrong organization or metering mode: Do not start work. Reconnect under the intended organization and run the verification prompt again.
• Rate limited: Back off after 429 and use returned rate or quota headers.

Related articles

• Getting started with the API
• Authentication and API scopes
• API usage, rate limits, and errors