> For the complete documentation index, see [llms.txt](https://help.rankability.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.rankability.com/api/mcp-getting-started.md).

# Connecting Rankability to AI assistants with MCP

Connect an MCP-compatible assistant to Rankability's hosted endpoint with OAuth or a scoped API key, then use client, research, content, tracking, optimization, and audit tools.

Connect an MCP-compatible assistant to Rankability's hosted endpoint with OAuth or a scoped API key, then use client, research, content, tracking, optimization, and audit tools.

Rankability hosts a remote Model Context Protocol server. Use it to give an MCP-compatible assistant scoped access to your organization’s Rankability data and actions.

## Hosted MCP endpoint

```
https://app.rankability.com/mcp
```

No local installation is required. The hosted endpoint supports OAuth access tokens and Rankability API keys that begin with `rk_live_`.

## Start the connection in Rankability

1. Open **Settings → API keys**.
2. Find **Connect Claude or Codex** and select the assistant.
3. Select **Check endpoint**. **Endpoint ready** confirms that OAuth discovery is available; it does not authenticate the assistant by itself.
4. Follow the assistant-specific steps and complete Rankability sign-in and consent.
5. Run the read-only verification prompt before starting consequential work.

The verification prompt calls `get_usage_and_limits` and asks the assistant to report the active organization, usage contract, and available tools without starting work. Confirm that result before approving a run or write tool.

## Connect Claude with OAuth

1. On Claude Pro or Max, open **Customize → Connectors → + → Add custom connector**. On Team or Enterprise, an owner first adds it under **Organization settings → Connectors**.
2. Add Rankability with the hosted endpoint shown above.
3. Complete Rankability sign-in and approve only the required scopes.
4. Enable Rankability for the conversation and run the read-only verification prompt.

The OAuth token is bound to the organization that was active during consent. Claude refreshes access automatically until you revoke the connected app or authorize a different organization.

## 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:

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

## 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 currently registers 99 general-account tools. Account terms and granted scopes control whether a call is authorized; they do not dynamically hide registered tool definitions. The MCP surface also includes Serena consultation, saved Prospector, backlink-profile, 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 plus `do_not_use`, `blocked_keywords`, and `excluded_topics`. `update_client_profile` patches the client and can merge selected Knowledge fields without clearing omitted nested settings.
* `list_client_sources`, `get_client_source`, `create_client_source`, `update_client_source`, and `delete_client_source` manage pasted Knowledge sources. Lists return compact metadata only; request one source in full when its body is needed. Creating or changing content can schedule the normal indexing and contradiction checks.
* `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 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.

### 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.

### Tracker and optimization

* `list_tracker_projects`, `get_tracker_project`, `get_tracker_results`, `get_tracker_trends`, `get_tracker_matrix`, `get_tracker_summary`, `get_tracker_seo_performance`, `get_tracker_brand_summary`, and `get_notifications`
* `tracker_capabilities` performs the read-only entitlement and client dependency preflight. `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_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.
* `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.

### 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. `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.
* 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 tool never refreshes DataForSEO, loads the usage-billed individual backlink list, or exports rows. Live refresh, individual backlink-list, and export 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 Google/SerpAPI/DataForSEO/GSC/GA4, 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 exists, `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 `category_total`, `overall_category_delta`, `category_model`, and `calculation_state`. Current seven-category scores are `consistent` when their categories sum to the stored overall. Historical rows can return `legacy_mismatch`, `legacy_categories`, or `partial_categories`; preserve that state instead of explaining the difference as undocumented weighting.

## 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:** Start a new MCP session so the client 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.
* **Session needs to restart:** A `session_reinitialize_required` response means the saved MCP session no longer belongs to the current credential. Start a new MCP initialization request; do not repeatedly retry the old session ID.
* **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](/api/api-getting-started.md)
* [Authentication and API scopes](/api/api-authentication.md)
* [API usage, rate limits, and errors](/api/api-credits-rate-limits-and-errors.md)