Drive it from an AI agent

AltoRank ships an MCP server with 26 tools, a REST API underneath it, and a CLI over the same routes. “Point Claude at a client roster, audit every site, plan the keywords and start the drafts” is a thing you can run. The readiness tooling makes client sites readable by agents; this makes AltoRank itself drivable by one.

Self-hosted, in Claude Code

claude mcp add altorank -- npx tsx apps/web/scripts/mcp.ts

Hosted endpoint, in Claude Code

claude mcp add --transport http altorank https://app.altorank.co/api/mcp

Readiness tools, no key needed

These run against any public domain and read only what a crawler can read. An agent can audit a prospect’s site before anyone has an account.

altorank_check_readiness

Run the nine agent-readiness checks against a domain: AI-crawler rules in robots.txt, sitemap, structured data, Organization schema, machine-readable content, title and meta, single h1, content signals. Returns a 0-100 score and a finding per check. Reads public site configuration only. Start here.

altorank_propose_schema

Draft Organization, FAQPage and Product JSON-LD for a page from evidence found on the page itself. Every field carries its source; anything unsourceable is listed as missing for a human rather than guessed. Skips types the page already has.

altorank_generate_machine_readable

Convert a page to Markdown and build a starter llms.txt from pages actually found on the site. The result says which extraction strategy was used so you can judge how much to trust it.

altorank_readiness_report

The whole loop in one call: run the checks, generate every artifact the failures need, attach a placement instruction to each. The same report the dashboard renders.

Account tools, behind an API key

22 tools over the REST API. Each carries the scope the route checks: read is the default, generate costs drafting quota, write is for the mutations, which propose before they write. Every result is the same envelope, ok, data or error, plus agent_guidance telling the model what to do next.

altorank_whoami read

Which account this key opens, its workspaces and this month’s drafting quota. Run first.

altorank_list_workspaces read

Every workspace in the account, with ids for the other tools.

altorank_get_workspace read

One workspace with integration status and a plain-language block for describing its setup to a person.

altorank_list_keywords read

Tracked keywords for a workspace, each with the mutations allowed on it. Difficulty null means unmeasured.

altorank_suggest_keywords read

Keyword candidates from seed phrases or from the site itself. Spends research credits, so the agent is told to ask first. Nothing is saved.

altorank_list_articles read

Articles for a workspace with status, editor URL and allowed mutations.

altorank_get_article read

One article and its latest generation job. This is how an agent polls a draft it started.

altorank_get_article_content read

The article body as Markdown, HTML or editor JSON. Read-only.

altorank_generate_draft generate

Write a draft into the human’s review queue and return the article id. Costs quota. Cannot publish. Takes an idempotency key so a retried call returns the draft already started instead of a second one.

altorank_usage read

This month’s drafting quota and per-workspace article counts.

altorank_gsc_performance read

Clicks and impressions against the previous window, daily series, top pages, and queries in positions 4-15. From the stored nightly Search Console sync; not connected is reported as no data, not zero.

altorank_gsc_cannibalization read

Queries where two or more of the site’s pages compete, with the page Google prefers and a merge-or-differentiate suggestion per loser.

altorank_gsc_coverage read

Every known page bucketed indexed, not indexed or unknown from stored URL Inspection verdicts. Unknown is a real bucket, not a polite not-indexed.

altorank_gsc_url_inspection read

Google’s last stored verdict for one URL. Does not call Google; a fresh inspection is the human’s click in the editor.

altorank_export_keywords read

Every tracked keyword with volume, difficulty, cpc, status and planned date as rows.

altorank_reschedule_keywords write

Move planned, unwritten keywords to other days. The same write as dragging on the planner; skips keywords already written, with the reason.

altorank_remove_keywords_from_plan write

Take planned keywords off the calendar. They stay tracked; nothing is deleted.

altorank_replace_in_article write

Find-and-replace in one draft’s title and body. Preview by default; refused on approved, scheduled or live articles.

altorank_bulk_replace_in_articles write

The same find-and-replace across up to ten editable drafts. Preview by default; approved, scheduled and live articles are skipped with the reason.

altorank_retry_publish write

Re-run the last failed publish of an article a human already approved, through the same connection. Refused unless the last attempt failed and the article is still approved. Not a publish call; cannot publish a draft.

altorank_pause_workspace write

Stop drafting and publishing for one workspace until resumed. Drafts, plan and pace are untouched.

altorank_resume_workspace write

Put a hand-paused workspace back and re-plan its calendar from today. Cannot lift an account-wide billing pause.

There is no publish tool, on purpose

An agent can research, audit, propose schema, plan keywords, start drafts and tidy them. It cannot publish, approve or delete, because an agent-triggered publish that bypasses a human approving the draft is exactly what the approval gate exists to prevent. That holds across the MCP server, the REST API and the CLI: there is no such call to grant a scope for. This is the difference between a gate you can switch off and one that is not implemented in the first place.

Hosted endpoint

The same server, hosted, so nothing needs cloning. It speaks Streamable HTTP at https://app.altorank.co/api/mcp and any MCP client can add it as a connector. Auth is OAuth 2.0 with PKCE and dynamic client registration, discovered at /.well-known/oauth-authorization-server, so there is no key to paste: the client sends you to sign in, and an owner or admin picks the scopes to grant on a consent screen. Write is opt-in. A raw Authorization: Bearer altorank_live_… header works too.

  • ChatGPT: Settings → Connectors, with Developer mode on a paid plan, and add the URL above.
  • Claude.ai: Settings → Connectors → Add custom connector, with the URL above.
  • Claude Code: claude mcp add --transport http altorank https://app.altorank.co/api/mcp
  • Cursor, Codex: add a custom MCP connector with the URL above.

Tokens granted this way show up as API keys at /settings/api-keys and are revoked there, the same as a key you created by hand.

The REST API underneath

The MCP server and the CLI are thin clients over https://app.altorank.co/api/agent/v1, 23 routes. Keys are created at /settings/api-keys, start with altorank_live_, are stored hashed, carry scopes (read, generate, write) and an expiry, and can be revoked at any time. Send one as Authorization: Bearer.

Account

  • GET auth/whoami
  • GET workspaces
  • GET workspaces/:id
  • GET usage
  • GET readiness

Keywords

  • GET keywords
  • POST keywords/suggest
  • GET keywords/export
  • POST keywords/bulk-reschedule
  • POST keywords/bulk-remove

Articles

  • GET articles
  • GET articles/:id
  • GET articles/:id/content
  • POST articles/generate
  • POST articles/:id/replace
  • POST articles/bulk-replace
  • POST articles/:id/retry-publish

Search Console

  • GET gsc/performance
  • GET gsc/cannibalization
  • GET gsc/coverage
  • GET gsc/url-inspection

Workspaces

  • POST workspaces/:id/pause
  • POST workspaces/:id/resume

CLI and skill

The same routes are available as a command-line tool, npm run cli from apps/web in the repository, packaged for npm but not yet published. A skill file, skills/altorank/SKILL.md, states the rules above in the form a coding agent reads before it acts: preflight with whoami, ask before spending credits, never try to publish. Install it into Claude Code, Cursor, Codex, Copilot, Windsurf, Gemini CLI or Cline with npx skills add AltoRank/altorank.

Setup, self-hosted

  1. 1 Install it

    Clone https://github.com/AltoRank/altorank and install dependencies. The server is a stdio MCP server at apps/web/scripts/mcp.ts and runs with npm run mcp from apps/web. The four readiness tools work with no account at all.

  2. 2 Register it with your agent

    In Claude Code: claude mcp add altorank -- npx tsx apps/web/scripts/mcp.ts. Any MCP-compatible client works the same way; the transport is stdio.

  3. 3 Add a key for the account tools

    Create an API key at /settings/api-keys in the app, choose its scopes (read, generate, write) and an expiry, and set it as ALTORANK_API_KEY in the environment the server runs in. Without it the 22 account tools answer with an error that says so.

  4. 4 Point it at a roster

    Ask your agent to run altorank_whoami, pick a workspace, check readiness, suggest keywords and start a draft. The tools are namespaced altorank_* so they compose alongside other MCP servers in the same session.

Common questions

Can an AI agent publish articles through AltoRank?

No, and that is deliberate rather than unfinished. There is no publish, approve or delete call in the MCP server, the REST API or the CLI. Publishing needs per-workspace CMS credentials and a human approval, and an agent-triggered publish that bypasses the approval is precisely what the approval gate exists to prevent. The one tool with publish in its name, altorank_retry_publish, only re-runs a publish a human already approved and that failed; it is refused on anything else.

Which tools does the server expose?

26 today, in two groups. Four public readiness tools that need no key: altorank_check_readiness, altorank_propose_schema, altorank_generate_machine_readable, altorank_readiness_report. And 22 account tools behind an API key, covering workspaces, keywords, drafts, Search Console reads and quota, plus a handful of write-scope mutations that mirror the planner and editor.

Is there a REST API?

Yes. https://app.altorank.co/api/agent/v1 has 23 routes and the MCP server and CLI are thin clients over it. Every response is the same envelope, ok, data or error, and agent_guidance, so a model gets told what to do next rather than left with a bare JSON blob. Keys are created at /settings/api-keys, start with altorank_live_, are stored hashed, carry scopes and an expiry, and can be revoked at any time.

Do I need a paid plan to use the MCP server?

No. It is in the open-source build, so cloning the repo and bringing your own model key is enough. The managed plans exist for people who would rather not run infrastructure, and the hosted endpoint is part of that.

Does it work with anything other than Claude Code?

Yes. The self-hosted server is standard MCP over stdio, so any MCP-compatible client can register it. The hosted endpoint at https://app.altorank.co/api/mcp speaks Streamable HTTP with OAuth, which is what ChatGPT, Claude.ai, Cursor and Codex expect from a custom connector.

What does the hosted endpoint change?

Nothing about what an agent may do; the same 26 tools and the same gate. It removes the install: add https://app.altorank.co/api/mcp as a connector, sign in, and an owner or admin approves the scopes on a consent screen. Write is opt-in there. The resulting token shows up as an API key at /settings/api-keys and is revoked in the same place.

View the source Add your domain

Be the site the assistant names.

Add a domain and the first draft is written while you watch. Every publish is your decision, a click on the draft or a rule you set and can hold, and you can read the source or self-host it free.

Add your domain Self-host it free

Add a domain, it sets up your workspace