MCP

The AutoRanq MCP (Model Context Protocol) server lets your AI assistant drive the platform directly — list articles, fire generations, tweak prompts, check costs. No REST plumbing, no SDK install, no auth boilerplate. Your AI client and AutoRanq talk to each other.

What you can do

“Hey Claude, generate an article for the keyword ‘best CRM for startups’ in my Marketing project.” → done.

What's underneath

Standard Model Context Protocol over stdio. Same API as the REST API but exposed as tool calls.

Prerequisites

• An AutoRanq API key (create one in app.autoranq.ai → Settings → API). See Authentication for the full key flow.
• Node.js 20+ on your machine (the MCP server runs locally as a child process of your AI client)
• An MCP-compatible client: Claude Code, Cursor, Claude Desktop, or VS Code with the MCP extension

Install

Pick your AI client below. Each tab has copy-paste install steps.

Claude Code

The fastest way:

claude mcp add autoranq -- npx -y @autorank/mcp-server \
  -e AUTORANK_API_KEY=ar_live_your_key \
  -e AUTORANK_API_URL=https://api.autoranq.ai

That writes the config to ~/.claude.json. Restart Claude Code and you’re done.

To verify:

claude mcp list
# Expect: autoranq (running)

Cursor

1. Open Settings → MCP (or press Cmd+Shift+P → “Open MCP Settings”).

2. Click Add New MCP Server and paste:

   {
     "mcpServers": {
       "autoranq": {
         "command": "npx",
         "args": ["-y", "@autorank/mcp-server"],
         "env": {
           "AUTORANK_API_KEY": "ar_live_your_key",
           "AUTORANK_API_URL": "https://api.autoranq.ai"
         }
       }
     }
   }

3. Save and restart Cursor. The AutoRanq tools appear in the MCP panel.

Tip

Cursor supports MCP deep-link installs. We’re working on a one-click install button — until then, the JSON paste above is the supported flow.

Claude Desktop

1. Open the config file:

   OS	Path
   macOS	~/Library/Application Support/Claude/claude_desktop_config.json
   Windows	%APPDATA%\Claude\claude_desktop_config.json
   Linux	~/.config/Claude/claude_desktop_config.json

2. Add (or merge into) mcpServers:

   {
     "mcpServers": {
       "autoranq": {
         "command": "npx",
         "args": ["-y", "@autorank/mcp-server"],
         "env": {
           "AUTORANK_API_KEY": "ar_live_your_key",
           "AUTORANK_API_URL": "https://api.autoranq.ai"
         }
       }
     }
   }

3. Quit and restart Claude Desktop (just closing the window isn’t enough — use Claude → Quit from the menu bar).

4. In a new chat, look for the 🔌 icon in the bottom-right — clicking it shows the AutoRanq tools.

VS Code

VS Code needs the MCP extension first.

1. Install the extension.

2. Open .vscode/settings.json in your workspace (or User Settings) and add:

   {
     "mcp.servers": {
       "autoranq": {
         "command": "npx",
         "args": ["-y", "@autorank/mcp-server"],
         "env": {
           "AUTORANK_API_KEY": "ar_live_your_key",
           "AUTORANK_API_URL": "https://api.autoranq.ai"
         }
       }
     }
   }

3. Open the Command Palette (Cmd+Shift+P) → MCP: Restart Servers.

Generic JSON

Any MCP-compatible client accepts the same config shape:

{
  "mcpServers": {
    "autoranq": {
      "command": "npx",
      "args": ["-y", "@autorank/mcp-server"],
      "env": {
        "AUTORANK_API_KEY": "ar_live_your_key",
        "AUTORANK_API_URL": "https://api.autoranq.ai"
      }
    }
  }
}

Consult your client’s docs for where to place this. The server itself is identical regardless of host.

Don't forget AUTORANK_API_URL

If you omit AUTORANK_API_URL, the server defaults to http://localhost:3001 — every tool call will silently fail with a connection error. Always set the production URL.

Verify it works

Open your AI client and ask:

“List my AutoRanq projects.”

If everything’s wired up, the assistant calls the list_projects tool and shows your projects. If you see an error like “tool not found” or “MCP server not connected”, check the Troubleshooting section.

Tool reference

22 tools across 6 categories — a one-to-one mapping of the public REST API into MCP tool calls. Your AI client decides when to call each.

Projects (2 tools)

Tool	What it does
list_projects	List all projects in your organization
get_project	Get a single project by ID

Articles (6 tools)

Tool	What it does
list_articles	List articles with optional filters (project, status, format)
get_article	Get a single article with full content + metadata
create_article	Create a draft article manually (title + content)
update_article	Update title, content, status, or metadata of an existing article
publish_article	Transition a DRAFT/APPROVED article to PUBLISHED
delete_article	Delete an article

Generations (3 tools)

Tool	What it does
list_generations	List recent AI generation jobs with optional filters
get_generation	Get detailed status, phase, and result of a generation
generate_article	Trigger a new AI article generation for a keyword

Keywords (3 tools)

Tool	What it does
list_keywords	List keywords for a project with optional filters
get_keyword	Get a single keyword with SERP data
research_keywords	Trigger a keyword research job (seed keywords + location)

Webhooks (6 tools)

Tool	What it does
list_webhooks	List webhook subscriptions for your organization
get_webhook	Get a single webhook subscription
create_webhook	Create a new webhook subscription (URL + event types)
delete_webhook	Revoke an existing webhook
test_webhook	Fire a test delivery to verify your endpoint
list_webhook_events	List all available event types you can subscribe to

System (2 tools)

Tool	What it does
get_system_health	Public API health status
get_rate_limit	Current rate-limit usage for your API key

Example prompts

Things your AI client can now do:

• “List my last 10 published articles for the webgroeiers.nl project.”
• “Trigger a generation for the keyword ‘best CRM for B2B startups’ in my Marketing project.”
• “My last generation is FAILED — fetch it and tell me why.”
• “Create a webhook on https://my-app.com/hooks/autoranq that listens to article.published and generation.completed.”
• “How many requests do I have left on my rate limit this hour?”

The MCP server gives you the entire public API surface as tools — your AI client combines them into multi-step workflows automatically.

Troubleshooting

”MCP server not connected” or tools don’t appear

1. Check the API key prefix. Must start with ar_live_ or ar_test_. See Authentication.
2. Check AUTORANK_API_URL. Without it, the server hits http://localhost:3001 — production calls fail silently.
3. Try the npm package manually:

   AUTORANK_API_KEY=ar_live_your_key \
   AUTORANK_API_URL=https://api.autoranq.ai \
   npx -y @autorank/mcp-server

   You should see a startup log line on stderr (the server uses stdio so it waits for MCP protocol input — that’s normal, just Ctrl+C to exit).

”Unauthorized” on every tool call

The key was rejected. Common causes:

• The key was revoked or rotated in the dashboard
• You’re using a test-mode key (ar_test_) but pointing at the live API URL — they work together, so this is fine; just double-check
• The key lacks the required scope. MCP tools that write (e.g. update_recipe_step, create_prompt) need write scope; read-only keys get 403. See Authentication → Scopes.

Timeouts on long-running operations

Default tool-call timeout is 30 seconds. Heavy operations like test_recipe (which fires a real generation) can take longer. If you hit timeouts:

• Use test_single_step instead for faster iteration
• Or fire POST /generate via the REST API and use list_generations to poll status separately

Server crashes on startup with “AUTORANK_API_KEY environment variable is required”

You forgot the env block in your client config. Re-check the install steps above — the API key MUST be passed via env, not as a tool argument.

Next steps

• Authentication — manage API keys, rotate compromised ones, understand scopes
• Webhooks — get notified when long-running tools complete (no polling needed)
• Quickstart — same workflow via REST if you prefer code over chat
• CLI — terminal-native version of the same surface (coming in Phase 3)