> 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 the current client, 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, shared-credit state, and available tools without starting paid 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 exposes the following tools. Availability depends on the account plan and the scopes granted to the connection. The MCP surface currently covers clients, usage, Copywriter, Optimize, Tracker, Page Auditor, and Site Auditor. Other Agent API scopes do not imply that a same-named MCP tool is registered.

### Clients and account

* `list_clients`, `resolve_client`, `get_client`, `get_client_overview`, `create_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`; editing brand voice or sources remains web-app only.
* `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 active shared-credit balance and limits
* `estimate_cost` for a read-only, operation-specific pre-spend estimate
* Use `get_usage_and_limits` for credit availability; do not substitute an older balance endpoint

### Copywriter and Autopilot

* `list_content_projects`, `get_content_project`, and `get_content_artifacts`
* `create_content_auto`, `create_content_stepped`, and `approve_brief`
* `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_stepped` creates the brief without charge. `create_content_auto`, `create_content_autopilot`, and `approve_brief` require an approved estimate and `confirm_cost: true`. For retryable automations, provide a stable `idempotency_key` so a reconnect does not start duplicate paid 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.

### Tracker and optimization

* `list_tracker_projects`, `get_tracker_project`, `get_tracker_summary`, and `get_notifications`
* 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_cost: true`, and provide a stable `idempotency_key` for retries

### Page and site auditing

* `page_audit_run`, `page_audit_get`, `page_audit_list`, and `page_audit_delete`; estimate and confirm before a run, provide a stable `idempotency_key`, use the status view for polling, and keep list discovery compact
* `site_audit_estimate`, `site_audit_run`, `site_audit_get`, `site_audit_list`, `site_audit_cancel`, and `site_audit_delete`; a run requires `confirm_cost: true` plus a stable `idempotency_key`, while reads default to bounded status/summary views and paginate full inventories

## Built-in workflows and references

MCP clients that expose server prompts can discover sixteen free-first workflows, including `client_baseline`, `ai_visibility_gap`, `keyword_diagnosis`, `stale_data_sweep`, `brief_first`, `monthly_client_report`, `portfolio_leaderboard`, and `tracking_setup_plan`. Paid workflows stop after the live estimate; they do not spend 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 shared credit balance as the Rankability application. Call `get_usage_and_limits` to resolve spendable credits, then call `estimate_cost` before consequential work. For a Tracker scan, pass `operation: "trigger_scan"` plus the Tracker `project_id`; the estimate uses the project's current platforms, Local Pack grid, and tracked keyword count, because a scan runs every keyword on every selected platform. Both reads are free and create no reservation. Paid tools require `confirm_cost: true` after the estimate is shown and approved. Run and write tools can reserve credits, which are consumed only at the operation's documented completion point.

## 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 credit-consuming 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.
* **A tool is missing:** Confirm the connection has 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 credits, rate limits, and errors](/api/api-credits-rate-limits-and-errors.md)