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

Use the guided connection in Rankability

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

The verification prompt calls get_usage_and_limits and asks the assistant to report the product mode, metering model, and available deliverables without starting paid work. Confirm that result before approving a run or write tool.

You can also reach the same guided setup from a client's Integrations tab, where Claude and Codex appear under AI assistants. Selecting one opens the connection dialog for that assistant. The connection is still made once for the organization; opening it from a client only sets which brand you go on to work with.

Connect Claude with OAuth

On Claude Pro or Max, open Customize → Connectors → + → Add custom connector. On Team or Enterprise, an owner first adds it under Organization settings → Connectors.
Add Rankability with the hosted endpoint shown above.
Complete Rankability sign-in and approve only the required scopes.
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

In the Codex desktop app or IDE extension, open Settings → MCP servers → Add server.
Choose Streamable HTTP, enter https://app.rankability.com/mcp, save, restart, and select Authenticate.
Use /mcp to confirm Rankability is active.
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"

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 both the account's product mode 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 current-plan allowance or existing full-platform credit contract
estimate_cost for a read-only, operation-specific pre-spend estimate
The legacy Full-only credit-balance endpoint is not exposed as an MCP tool; use get_usage_and_limits

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.

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 product entitlement as the Rankability application. Current Rankability plans consume completed-deliverable allowances; existing full-platform accounts retain the shared credit balance. Call get_usage_and_limits to resolve the active contract, 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 and Local Pack grid. 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 an allowance or 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.

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 contract: 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.

PreviousKnowledge Base API endpoint NextOptimize API endpoint

Last updated 11 hours ago

Was this helpful?