Getting started

Add Autoranko to your AI assistant

One MCP server, every SEO tool. Connect Claude Code, Claude Desktop, Cursor or any MCP client, then ask in plain words: your assistant audits pages, researches keywords, writes and publishes articles and generates every on-page element, for any website.

1. Create a tokenIn Dashboard → API: the same ar_live_ token as the REST API.
2. Add the serverOne command in Claude Code, a few lines of JSON in other clients.
3. Ask for SEO work“Audit example.com and fix the top 3 issues.” Your assistant picks the tools.

Claude Code: the whole setup

export AUTORANKO_TOKEN=ar_live_…
claude mcp add --transport http autoranko https://autoranko.com/api/mcp \
  --header "Authorization: Bearer $AUTORANKO_TOKEN"

26 tools, 15 of them for any website. Using another client? Pick the remote or local setup below.

Create a token

The MCP server takes the same bearer tokens as the REST API.

Open Dashboard → API. Under API keys, name the token after the client that will use it, such as Claude Code or Cursor, and click Create token.
Copy it right away: it's shown once. It starts with ar_live_.
Keep it in an environment variable: the commands on this page read it from there.
Shell
```
export AUTORANKO_TOKEN=ar_live_…
```

A tool call acts as your account, exactly like an API request with the same token: it sees your sites, jobs and SEO Lab history, and uses your plan's allowances. Rotation, revocation and safe storage are covered in Authentication.

Admin-only endpoints have no tool

PUT /ai/models (set a task's AI model) needs an admin token and changes platform-wide settings, so it's left out of MCP on purpose, whatever token the assistant uses. Every tool on this page works with a regular token.

Your assistant acts as you

With your token, an assistant can create article jobs and publish posts to your WordPress sites. Most clients ask before running a tool: keep that confirmation on for create_article_job and publish_job. Give each client its own token, so you can revoke one without breaking the others.

Remote or local

Both serve the same 26 tools and call the same API with your token. Use the remote server unless your client can only start local commands.

Remote server

Recommended

Autoranko hosts it. Point your client at one URL: nothing to install, nothing to update.

Address: https://autoranko.com/api/mcp
Transport: Streamable HTTP
Token: In the Authorization header
Best for: Claude Code, Cursor, VS Code and any client that can send a header

Remote setup

Local server

The autoranko-mcp npm package runs on your machine and forwards each call to the API.

Command: npx -y autoranko-mcp
Transport: stdio
Token: In the AUTORANKO_TOKEN environment variable
Needs: Node.js 18 or later

Local setup

Remote server

Point the client at the endpoint and send your token in a header.

URL	`https://autoranko.com/api/mcp`
Transport	Streamable HTTP, stateless
Header	`Authorization: Bearer ar_live_…`

Terminal

claude mcp add --transport http autoranko https://autoranko.com/api/mcp \
  --header "Authorization: Bearer $AUTORANKO_TOKEN"

Run it where AUTORANKO_TOKEN is set: your shell fills in the token, and Claude Code stores it with the server. Add --scope user to use Autoranko in every project, not only the current one.

claude mcp list, or /mcp inside a session, shows whether it's connected.

claude_desktop_config.json

{
  "mcpServers": {
    "autoranko": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://autoranko.com/api/mcp",
        "--header",
        "Authorization:${AUTORANKO_AUTH}"
      ],
      "env": {
        "AUTORANKO_AUTH": "Bearer ar_live_…"
      }
    }
  }
}

Claude Desktop starts its MCP servers as local commands, so it reaches the remote server through the mcp-remote bridge, which needs Node.js. In Settings → Developer, click Edit Config, add this, then quit and reopen Claude Desktop.

Paste your token after Bearer in AUTORANKO_AUTH. The header has no space after the colon on purpose: on Windows, spaces would split the argument.

~/.cursor/mcp.json

{
  "mcpServers": {
    "autoranko": {
      "url": "https://autoranko.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ar_live_…"
      }
    }
  }
}

Add this to ~/.cursor/mcp.json to use it in every project, or to .cursor/mcp.json in one project. The file holds your token: keep it out of version control.

.vscode/mcp.json

{
  "servers": {
    "autoranko": {
      "type": "http",
      "url": "https://autoranko.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:autoranko-token}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "autoranko-token",
      "description": "Autoranko API token",
      "password": true
    }
  ]
}

Save it as .vscode/mcp.json in your workspace. VS Code asks for the token the first time the server starts and keeps it in its secret storage, so the file is safe to commit.

Any client that supports Streamable HTTP and custom headers connects with these settings:

URL	`https://autoranko.com/api/mcp`
Transport	Streamable HTTP (`http` in most configs)
Header	`Authorization: Bearer ar_live_…`

Connectors that can only sign in with OAuth, such as custom connectors on claude.ai, can't send a token yet. Use one of the clients above, the mcp-remote bridge shown for Claude Desktop, or the local server.

Local server (npx)

The autoranko-mcp package runs the server on your machine and talks to the client over stdio. It reads your token from AUTORANKO_TOKEN and needs Node.js 18 or later: npx -y downloads it on first run.

Command	`npx -y autoranko-mcp`
Environment	`AUTORANKO_TOKEN=ar_live_…`
Transport	stdio

Terminal

claude mcp add autoranko -e AUTORANKO_TOKEN=$AUTORANKO_TOKEN -- npx -y autoranko-mcp

Claude Code saves the token with the server and passes it as AUTORANKO_TOKEN each time it starts the package. Add --scope user to use it in every project.

claude_desktop_config.json

{
  "mcpServers": {
    "autoranko": {
      "command": "npx",
      "args": ["-y", "autoranko-mcp"],
      "env": {
        "AUTORANKO_TOKEN": "ar_live_…"
      }
    }
  }
}

In Settings → Developer, click Edit Config, add this with your token, then quit and reopen Claude Desktop.

~/.cursor/mcp.json

{
  "mcpServers": {
    "autoranko": {
      "command": "npx",
      "args": ["-y", "autoranko-mcp"],
      "env": {
        "AUTORANKO_TOKEN": "ar_live_…"
      }
    }
  }
}

Add this to ~/.cursor/mcp.json for every project, or to .cursor/mcp.json in one project, and keep the file out of version control.

.vscode/mcp.json

{
  "servers": {
    "autoranko": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "autoranko-mcp"],
      "env": {
        "AUTORANKO_TOKEN": "${input:autoranko-token}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "autoranko-token",
      "description": "Autoranko API token",
      "password": true
    }
  ]
}

VS Code asks for the token on first start, keeps it in its secret storage and passes it to the package as AUTORANKO_TOKEN.

Any client that can start a local command runs it with:

Command	`npx`
Arguments	`-y autoranko-mcp`
Environment	`AUTORANKO_TOKEN=ar_live_…`

At startup, the package loads the current tool list from /api/mcp/tools, with the copy bundled in the package as a fallback.

Tools

26 tools, generated from the same API reference as these docs and the OpenAPI spec, so they can't drift from the API. Each one calls the endpoint shown under its name, with the same arguments, limits and errors: follow the link for every detail.

This is the list tools/list returns. Every tool's full description and JSON Schema are public, no token needed, at /api/mcp/tools. In the lists, * marks a required argument.

SEO toolkit 15 tools

Any website or topic. No connected site needed.

seo_analyzePOST/seo/analyze
Audit a page
Fetches any public page, from a CMS page to a hand-written HTML file, and audits it for search in four layers.
Arguments:url* (required)save
seo_keyword_researchPOST/seo/keywords
Research keywords for any site
Keyword research without a connected site.
Arguments:topicurlkeywordsmodelanguagecountrysave
seo_write_articlePOST/seo/article
Write a long-form article
Writes a complete SEO article without a connected site, in two AI steps.
Arguments:topic* (required)target_keywordword_counttonelanguagesave
seo_write_short_articlePOST/seo/article-short
Write a short article
Writes a short, publication-ready piece of 150–800 words (400 by default).
Arguments:topic* (required)target_keywordword_counttonelanguagesave
seo_meta_tagsPOST/seo/meta-tags
Write title and meta description variants
Writes three title tags and three meta descriptions, plus a slug and a focus keyword, for an existing page (url) or a new one (topic).
Arguments:urltopictarget_keywordbrandlanguagesave
seo_open_graphPOST/seo/open-graph
Generate Open Graph and Twitter tags
Generates a page's social-sharing tags.
Arguments:urltopicbrandimage_urllanguagesave
seo_schemaPOST/seo/schema
Generate JSON-LD structured data
Generates valid schema.org JSON-LD for one of eight types.
Arguments:schema_type* (required)detailsurlsave
seo_headingsPOST/seo/headings
Plan the heading structure
Designs the heading structure that best serves a query.
Arguments:topicurltarget_keywordlanguagesave
seo_content_briefPOST/seo/content-brief
Create a content brief
Writes a brief a writer can work from for one keyword, the way the search results see it.
Arguments:keyword* (required)contextlanguagesave
seo_rewritePOST/seo/rewrite
Rewrite copy for SEO
Rewrites any copy, from a paragraph to a full article, to rank for target_keyword and read better.
Arguments:content* (required)target_keywordinstructionslanguagesave
seo_alt_textsPOST/seo/alt-texts
Write image alt text
Writes alt text for each image in images.
Arguments:imagesurltarget_keywordlanguagesave
robots_sitemapPOST/seo/robots-sitemap
Generate robots.txt and a sitemap
Builds a robots.txt and an XML sitemap for a site from the pages you list.
Arguments:site_url* (required)pages* (required)disallow_pathssave
serp_previewPOST/seo/serp-preview
Preview a Google result
Shows how a title, meta description and URL render on Google's results page.
Arguments:title* (required)description* (required)url* (required)keywordsave
list_seo_analysesGET/seo/analyses
List saved analyses
Lists the account's saved toolkit results, its SEO Lab history, newest first.
Arguments:kindlimitoffset
get_seo_analysisGET/seo/analyses/{id}
Get a saved analysis
Returns one saved toolkit result.
Arguments:id* (required)

Sites, articles and publishing 9 tools

The WordPress sites connected to your account.

list_sitesGET/sites
List sites
Returns every site your account owns, newest first.
No arguments.
get_siteGET/sites/{id}
Get a site with usage
Returns one site and its usage against the plan's limits.
Arguments:id* (required)
list_articlesGET/sites/{id}/articles
List synced articles
Lists the posts the Autoranko plugin has synced from this WordPress site: your whole content library, not only the articles Autoranko wrote.
Arguments:id* (required)limitoffsetq
get_articleGET/sites/{id}/articles/{postId}
Get an article
Returns the latest synced version of one WordPress post, including its full HTML content.
Arguments:id* (required)postId* (required)
list_article_jobsGET/sites/{id}/jobs
List jobs
Lists the site's generation jobs, newest first, including jobs created in the dashboard.
Arguments:id* (required)statuslimit
create_article_jobPOST/sites/{id}/jobs
Create a job
Starts writing a new article for the site.
Arguments:id* (required)topic* (required)target_keywordauto_publishscheduled_for
get_article_jobGET/jobs/{id}
Get a job
Returns one job with everything generated so far.
Arguments:id* (required)
publish_jobPOST/jobs/{id}/publish
Publish a job
Approves a job that's waiting in review and publishes it to the site's WordPress as a live post.
Arguments:id* (required)
site_keyword_researchPOST/sites/{id}/keywords
Research keywords
Runs AI keyword research for the site.
Arguments:id* (required)keywords* (required)mode

Account 2 tools

The token's account and the AI models behind each step.

whoamiGET/me
Get the current account
Returns the account the API token belongs to: its ID, email and name, its subscription plan and how many sites it owns.
No arguments.
list_ai_modelsGET/ai/models
List AI models
Shows which AI model each step of the content pipeline uses.
No arguments.

What to ask

Talk to your assistant the way you'd brief an SEO consultant. It picks the tools, fills in their arguments and chains them. Some prompts to start with:

“Audit https://example.com and fix the top 3 issues.”
Scores the page and ranks what's wrong, then writes the fixes for you to paste in: a new title and meta description, a cleaner heading outline, structured data.
Typical tools:seo_analyze seo_meta_tags seo_headings seo_schema
“Find 15 low-difficulty keywords about vegan meal prep for the US market.”
Keyword ideas with estimated monthly volume, difficulty and cost per click, ready to compare.
Typical tools:seo_keyword_research
“Write a 1,500-word article on choosing a heat pump, targeting ‘best heat pump for cold climates’.”
An outline, then the full article in HTML with its title, meta description and slug. Takes 1 to 3 minutes.
Typical tools:seo_write_article
“Draft an article about winter roof maintenance for my WordPress site, show me the draft, then publish it.”
Starts a generation job on your connected site, waits for the draft, and publishes it once you say so.
Typical tools:list_sites create_article_job get_article_job publish_job
“Generate schema.org markup for my local business: Rosa's Bakery, 12 Main Street, Austin, open 7am to 3pm.”
LocalBusiness JSON-LD built only from the facts you give: anything Google requires that you left out comes back flagged as a TODO, never invented.
Typical tools:seo_schema
“How will this title and description look on Google? Is anything cut off on mobile?”
Measured in pixels and cut where Google would cut them, on desktop and mobile, with pass-or-fail checks. Instant and free.
Typical tools:serp_preview

Say which page, which market and which keyword you care about: the assistant turns them into arguments. Add “don't save it” to a request and it sends save: false, so nothing goes to Dashboard → SEO Lab.

Protocol notes

Endpoint	`POST https://autoranko.com/api/mcp`
Transport	Streamable HTTP, stateless: no `Mcp-Session-Id` and no server-sent events, so every reply is a single `application/json` body. Notifications get `202 Accepted`, `GET` answers `405` and `DELETE` is accepted and ignored.
Messages	JSON-RPC 2.0, one message or a batch per request. Methods: `initialize`, `ping`, `tools/list` and `tools/call`; `resources/list` and `prompts/list` return empty lists. No call needs a prior `initialize`.
Protocol versions	`2025-06-18`, `2025-03-26` and `2024-11-05`. `initialize` gets back the version the client asks for when it's one of these, and `2025-06-18` otherwise.
Authentication	`Authorization: Bearer ar_live_…` on every request. Without a valid token: HTTP `401`, a `WWW-Authenticate: Bearer` header and JSON-RPC error `-32001`.
Rate limit	240 requests per minute per token on this endpoint. Over it: HTTP `429`, `Retry-After: 30`, JSON-RPC error `-32000`. Each `tools/call` is also an API request, so it counts toward the token's 120 per minute too.
Results	One `text` content item holding the API's JSON response. When the API answers with an error, the result has `isError: true` and the usual `{"error": {"code", "message"}}` envelope, so the assistant can read why and react.
Duration	Computed tools answer at once and most AI-powered ones within a minute. seo_write_article takes 1 to 3 minutes; the server waits up to 5 minutes for any tool. Article jobs return immediately and keep writing in the background, and the assistant checks on them with get_article_job.
Saving	13 tools take a `save` argument, on by default: their results go to Dashboard → SEO Lab, where list_seo_analyses and get_seo_analysis find them again. Send `save: false` to keep nothing.
Allowances	AI-powered toolkit tools use your account's monthly AI calls (seo_write_article uses two). robots_sitemap and serp_preview are computed and free. Article jobs use the site's article allowance.
Tool manifest	GET /api/mcp/tools: server info, instructions and every tool, public and cached for an hour.

Try it with cURL

Every client does this under the hood. Two calls show the whole exchange:

Shell

# List the tools. The server is stateless: no initialize call needed first.
curl https://autoranko.com/api/mcp \
  -H "Authorization: Bearer $AUTORANKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Call one. serp_preview is computed and free; save: false stores nothing.
curl https://autoranko.com/api/mcp \
  -H "Authorization: Bearer $AUTORANKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "serp_preview",
      "arguments": {
        "title": "How to Choose a Heat Pump for Cold Climates (2026 Guide)",
        "description": "Compare cold-climate heat pumps on efficiency, noise and price, and find the right size for your home before you buy.",
        "url": "https://example.com/heat-pumps",
        "keyword": "heat pump",
        "save": false
      }
    }
  }'

What the server tells your assistant

The initialize reply carries these instructions. Clients hand them to the model, which is how it knows where to start and which calls take time or cost allowance:

instructions

Autoranko ranks websites: analyze any URL, research keywords, write and publish SEO articles, and generate every on-page element (meta tags, Open Graph, schema.org, headings, briefs, rewrites, alt texts, robots/sitemap). Guidance: - Start with seo_analyze for any "how do I rank / audit this site" question; it returns parsed facts, a scored issue list and expert recommendations. - seo_write_article runs a full outline→draft pipeline (1-3 minutes, counts as 2 AI calls); seo_write_short_article is faster for 150-800 words. - Tools with a "save" argument persist results to the user's Autoranko account (Dashboard → SEO Lab) by default; pass save=false for throwaway calls. - create_article_job / publish_job target a connected WordPress site (see list_sites); the seo_* tools work for ANY website with no connection. - serp_preview and robots_sitemap are computed instantly and never consume AI allowance.

Troubleshooting

Symptom	What to do
HTTP `401`: `Missing bearer token`, `Invalid token format.` or `Invalid or revoked token.`	The header didn't arrive, the token is mistyped (it starts with `ar_live_`) or it was revoked. Fix the config, or create a new token in Dashboard → API, then restart the client.
The server doesn't show up, or lists no tools	Restart the client after editing its config, and quit Claude Desktop completely. In Claude Code, `claude mcp list` shows each server's status, and `/mcp` shows it inside a session.
Local server: `spawn npx ENOENT` or `command not found`	The client can't find Node.js. Install Node.js 18 or later. If you use nvm on macOS, set `command` to the full path `which npx` prints. On Windows, use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "autoranko-mcp"]`.
A long tool call times out in the client	Some clients give up on a tool after about a minute, and seo_write_article can take three. The work still finishes on Autoranko's side and, unless you sent `save: false`, lands in Dashboard → SEO Lab: ask the assistant to fetch it with list_seo_analyses.
A tool result with `isError: true`	The API's own error, passed through: read its `code` and `message`. plan_limit means an allowance is used up, fetch_failed that a page couldn't be fetched, invalid_body that an argument is wrong. Every code is in Errors.
HTTP `429` from the MCP endpoint	Over 240 requests in a minute on one token: wait for `Retry-After` (30 seconds). Past the API's own 120 per minute, the tool result carries rate_limited instead.

Create a token#

Remote or local#

Remote server

Local server

Remote server#

Local server (npx)#

Tools#

SEO toolkit 15 tools

Sites, articles and publishing 9 tools

Account 2 tools

What to ask#

Protocol notes#

Try it with cURL

What the server tells your assistant

Troubleshooting#

Create a token

Remote or local

Remote server

Local server (npx)

Tools

What to ask

Protocol notes

Troubleshooting