API & automation

MCP server

Ranksify speaks the Model Context Protocol, so an AI assistant can read your AEO metrics mid-conversation instead of you exporting a CSV and pasting it in. Read tools ship with the mcp scope; write tools need a separate mcp:write key. Every tool is scoped to one workspace.

Quickstart

In Settings → API keys, create a key and tick the mcp scope (also tick mcp:write if the assistant must create prompts or drafts — write is additive, not a substitute). Copy it — it is shown once.

Paste this into your client’s MCP config, swapping in the key you just copied:

{
  "mcpServers": {
    "ranksify": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.ranksify.ai/api/mcp",
        "--header",
        "Authorization: Bearer rk_your_mcp_key"
      ]
    }
  }
}

Restart the client and ask it something only your data can answer — “what is my visibility on ChatGPT this month, and how many samples is that?”

That is the whole setup. The rest of this page is the detail: the transport, the tools and how errors come back.

Endpoint and transport

POST https://app.ranksify.ai/api/mcp
Authorization: Bearer rk_your_mcp_key
Content-Type: application/json

JSON-RPC 2.0 over Streamable HTTP, request/response only — there is no server-initiated stream, so a GET is answered with a 405 explaining as much. JSON-RPC batch arrays are not supported; send one request per call.

Auth is an mcp-scoped key. Mint one under API keys — a read key will be refused here.

Connecting a client

Any MCP client that can talk to a remote HTTP server with a bearer token works. For clients that only speak stdio, bridge with mcp-remote:

{
  "mcpServers": {
    "ranksify": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.ranksify.ai/api/mcp",
        "--header",
        "Authorization: Bearer rk_your_mcp_key"
      ]
    }
  }
}

The tools

Tool	Returns
`list_projects`	Id, name and domain for every brand the key can read. Call this first — the others need a `project_id`.
`get_visibility_ranking`	The brand against its tracked competitors across engines: visibility, share of voice, average position, mentions, citations, sample size and 95% confidence interval.
`get_mentions`	Recent mentions inside AI answers with engine, prompt, position and funnel stage. Accepts a `limit` from 1 to 200, defaulting to 50 — out-of-range values are clamped rather than refused, and the response echoes the `limit` that was actually applied. Each item carries a `citationCount` and a `responseId`; the citations themselves are listed once per response under `citationsByResponse`, not repeated on every mention of the same answer.
`get_traffic`	Search and analytics performance from a connected provider — `gsc` (default), `bing` or `ga4` — by `query` (default), `page`, `country`, `device` or `totals`.
`list_prompts`	Tracked prompts — id, text, state, intent and topic names — optionally filtered to one state. Paged: `limit` is 1 to 200 and defaults to 50 (clamped, not refused), and a page that is not the last carries a `nextCursor` to pass back as `cursor`. The cursor is a keyset, so rows added or removed before it do not shift the next page.

The metric tools accept an optional from/to pair of YYYY-MM-DD dates; omitting them uses a recent window.

Write tools (`mcp:write`)

An mcp-only key never sees these. mcp:write is additive: the key must carry both mcp and mcp:write. Calling a write tool without mcp:write returns an error naming the missing scope.

Tool	Does
`create_prompt`	Adds a tracked prompt. Defaults to `proposed` so a human still approves sampling; pass `state:'active'` only when the user asked to start tracking now.
`update_prompt`	Edits text, branded flag, sampling policy or topics on an existing prompt.
`create_content_draft`	Creates a Content Studio draft. Never publishes — use `publish_content_draft` for that.
`publish_content_draft`	Pushes an existing draft to a connected CMS (WordPress or Webflow). Defaults to `mode:'draft'` in the CMS; pass `mode:'live'` only when the user explicitly asked to publish live. The piece should already be in a ready state in Content Studio. `mode:'live'` is accepted only for a piece already in In Review (or already published); a first draft is refused live and must be moved to In Review in the app first.
`run_site_audit`	Runs a site audit now (costs one monthly audits quota unit, same as the app button).

How it behaves

Errors

A failing tool comes back as tool content flagged as an error, not a transport failure, so the assistant can read the reason and adjust instead of losing the connection. Transport problems — a bad key, a missing scope, an exhausted rate limit — are returned as JSON-RPC errors with the matching HTTP status, and a rate-limited response carries Retry-After.

Statistics come with the numbers that have them

Visibility metrics are returned with their sample size and 95% confidence interval, and the server instructs connected assistants to cite both. If an assistant reports a visibility figure without saying how many samples it rests on, ask it — the number was there. A subject with too few completed runs has no visibility percentage at all: the field is null and rateWithheld says why, and an assistant should report the sample size rather than estimate a rate.

Traffic figures and mention counts carry no interval, because they are not estimates. They are raw counts of what a connected provider recorded and of what we found in the answers we sampled — a census of that data, not a sample of a larger population. An assistant that attaches a confidence interval to a click count is inventing one.

The MCP server is a paid-plan feature, and the entitlement is checked on every request rather than only when the key is minted.