Connect Cursor, VS Code and Windsurf
Add the RankX AI MCP server to Cursor, VS Code or Windsurf: create a personal access token, paste your editor's mcp.json block, keep the token out of git.
Cursor, VS Code and Windsurf connect to RankX AI with a personal access token in the editor's own MCP configuration file. Create the token in RankX AI's MCP settings, which is owner-only, then paste the block for your editor below.
The three editors want the same three facts in slightly different shapes: a
name for the connection, the address https://app.rankxai.com/api/mcp and an
Authorization header. The key names differ per editor, and a block copied
from the wrong one usually fails silently rather than showing an error.
How do I create the token?
In RankX AI, open MCP settings and the API tokens tab, then select Create token. MCP settings sit in Settings on a direct account and under Agency Admin on an agency account.
| Field | What to choose |
|---|---|
| Name | Something you will recognise later, for example "Cursor, laptop" |
| Capability | Read-only for reporting; Read + Write or Read + Write + Spend credits for an assistant that acts |
| Connected websites | Publish to WordPress, Edit WooCommerce products or Site administration, only if the editor should change a live site |
| Access | Your whole account, or one client's websites |
| Expires after | 30 days, 90 days (the default) or 1 year |
Copy the token when it is shown. RankX AI stores only a hash, so it is not shown again. A tool outside a token's scopes is not listed and not callable, so a read-only token cannot be talked into writing, spending or publishing.
How do I add the MCP server to Cursor, VS Code or Windsurf?
Paste the block for your editor into its MCP config file, save it, and the editor connects to the RankX AI MCP server with your token.
.cursor/mcp.json in the project root, or ~/.cursor/mcp.json in your home
directory for every project.
{ "mcpServers": { "rankxai": { "url": "https://app.rankxai.com/api/mcp", "headers": { "Authorization": "Bearer ${env:RANKXAI_TOKEN}" } } }}Cursor reads ${env:RANKXAI_TOKEN} from your environment, so the token itself
stays out of the file.
.vscode/mcp.json in the workspace, or the mcp.json in your VS Code user
profile.
{ "inputs": [ { "type": "promptString", "id": "rankxai-token", "description": "RankX AI personal access token", "password": true } ], "servers": { "rankxai": { "type": "http", "url": "https://app.rankxai.com/api/mcp", "headers": { "Authorization": "Bearer ${input:rankxai-token}" } } }}The top-level key is servers, not mcpServers, and the entry declares its
type. VS Code asks for the token the first time the server starts and stores
it for you, so the file holds no secret.
Windsurf is now called Devin Desktop. Put the entry in your user file,
~/.config/devin/mcp_config.json (%APPDATA%\devin\mcp_config.json on
Windows), or in .devin/mcp_config.local.json in a project, which git ignores.
{ "mcpServers": { "rankxai": { "url": "https://app.rankxai.com/api/mcp", "headers": { "Authorization": "Bearer rxai_your_token_here" } } }}Windsurf releases from before the rename read
~/.codeium/windsurf/mcp_config.json and take the address as serverUrl
instead of url.
Editors change these formats between versions. If a block does not attach, check that editor's current MCP documentation for the key names; RankX AI always needs the same three facts.
How do I keep the token out of git?
A project-level MCP config is a file in your repository, and a rxai_ token
pasted into it is a credential in your history. Each editor has a way to keep
it out:
| Editor | Keep the token out of the file with |
|---|---|
| Cursor | ${env:RANKXAI_TOKEN} in the header, with the value in your shell profile or secret manager |
| VS Code | An inputs entry with "password": true, referenced as ${input:rankxai-token} |
| Windsurf (Devin Desktop) | Your user file, or .devin/mcp_config.local.json, which git ignores |
If a token does reach a commit, revoke it in RankX AI's MCP settings and issue a new one. Rotation has no downtime: create the replacement, update the config, then revoke the old one.
How do I check the MCP server works?
Ask the editor's assistant:
Using RankX AI, list my websites, then show me the site audit issues for the first one.
list_projects is the entry point: every other tool takes a website id it
returns.
If no RankX AI tools appear at all, the connection is not attached. If some appear and others do not, the connection is fine and the token does not carry those tools' scopes. See troubleshooting.
Where to go next
- Authentication and scopes for what each scope reaches.
- The tool reference for every tool.
- Examples for prompts that work.
- Connect Claude Code for the command line.
Questions
Which scopes should an editor token have?
Only what the job needs. For reporting and analysis, choose Read-only, so the assistant can see your data but cannot write, spend credits or publish. Add spend or the website capabilities only for an assistant you trust to act.
What happens when the token expires?
The editor's RankX AI tools stop answering. Create a replacement token in RankX AI's MCP settings, paste it into the config, then revoke the old one; there is no downtime.
Why do some RankX AI tools appear and others not?
The connection works and the token does not carry the missing tools' scopes. RankX AI lists only the tools a token's scopes cover. Create a token with the scopes you need, as authentication explains.
Last updated