> 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 over the hosted endpoint, then grant only the scopes its tools need.

## Hosted MCP endpoint

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

## Claude Desktop

1. Open **Settings → Connectors → Add custom connector**.
2. Enter the hosted endpoint and leave the token field blank.
3. Complete Rankability sign-in and consent in the browser.
4. Confirm the active organization before allowing access.

Claude uses OAuth and refreshes access automatically until you revoke it.

## Cursor and Windsurf

Add the hosted endpoint to the client’s MCP configuration and send a Rankability API key as a Bearer token. Store the key as a secret; never commit it.

## Capabilities

Available tools depend on the server version and granted scopes. Current API families include clients, Copywriter and Autopilot, Reporter tracking, Researcher, Optimize, Page Auditor, Search Intelligence, and crawler actions. Read, run, and write capabilities require their matching scopes.

## Credits and limits

MCP uses the same plan-specific API limits and operation credit rules as the Agent API. Read-only chat in Rankability is free, but an assistant-started tool action can be metered.

## Security

* Use least-privilege scopes.
* Confirm the active organization during OAuth consent.
* Revoke a key or connector when it is no longer needed.
* Review consequential actions before approval.

## Troubleshooting

Restart the MCP client after changing configuration. If tools are missing, check server connection, organization, key expiration, and scopes.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.rankability.com/api/mcp-getting-started.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.