Scripts and CI
Call the RankX AI MCP server from a script or CI job with a personal access token: the JSON-RPC calls in cURL, Node and Python, and the limits to respect.
A script, a cron job or a CI pipeline calls the RankX AI MCP server with a
personal access token in an Authorization header, speaking JSON-RPC to
POST https://app.rankxai.com/api/mcp. A token is the supported path for any
unattended caller, and it is a first-class one.
Why a token rather than OAuth. RankX AI's authorisation server accepts two grants and no others: the authorisation code with PKCE, and a rotating refresh that can only renew what the code flow already issued. There is no client credentials grant, so every OAuth credential starts with a person at a browser.
Refresh tokens also rotate with theft detection: a daemon that fails to save the new value is not slowed down, it is disconnected. A token avoids both problems.
How do I create a token for the job?
In RankX AI's MCP settings (owner-only), open the API tokens tab, select Create token, and give it only the scopes the job needs. A nightly reporting script wants Read-only and nothing more.
A tool outside a token's scopes is not listed and not callable, so a read-only token cannot be made to write, spend or publish, even by a bug in your script. Every token expires after 30 days, 90 days or a year, as you choose, so put the renewal date in your calendar.
Store the token wherever you store secrets, never in the repository.
Which calls does a script make?
Three calls, in order:
initialize, where the connection identifies itself.tools/list, which returns exactly the tools your token's scopes reach, with every tool that spends credits saying so in its description, and the current rate written into the priced ones.tools/call, one per tool.
RANKXAI_TOKEN="rxai_your_token_here"ENDPOINT="https://app.rankxai.com/api/mcp"
# 1. initializecurl -sS "$ENDPOINT" \ -H "Authorization: Bearer $RANKXAI_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": { "name": "reporting-script", "version": "1.0.0" } } }'
# 2. tools/listcurl -sS "$ENDPOINT" \ -H "Authorization: Bearer $RANKXAI_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }'
# 3. tools/callcurl -sS "$ENDPOINT" \ -H "Authorization: Bearer $RANKXAI_TOKEN" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "list_projects", "arguments": {} } }'const ENDPOINT = 'https://app.rankxai.com/api/mcp'const TOKEN = process.env.RANKXAI_TOKEN
let id = 0
async function rpc(method, params) { const response = await fetch(ENDPOINT, { method: 'POST', headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json', Accept: 'application/json, text/event-stream', }, body: JSON.stringify({ jsonrpc: '2.0', id: ++id, method, params }), }) if (!response.ok) throw new Error(`${method}: HTTP ${response.status}`) const body = await response.json() if (body.error) throw new Error(`${method}: ${body.error.message}`) return body.result}
await rpc('initialize', { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'reporting-script', version: '1.0.0' },})
const { tools } = await rpc('tools/list')console.log(`${tools.length} tools reachable with this token`)
const projects = await rpc('tools/call', { name: 'list_projects', arguments: {},})console.log(projects.structuredContent)import osimport httpx
ENDPOINT = "https://app.rankxai.com/api/mcp"TOKEN = os.environ["RANKXAI_TOKEN"]
client = httpx.Client( headers={ "Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json", "Accept": "application/json, text/event-stream", }, timeout=60,)
_id = 0
def rpc(method, params=None): global _id _id += 1 payload = {"jsonrpc": "2.0", "id": _id, "method": method} if params is not None: payload["params"] = params response = client.post(ENDPOINT, json=payload) response.raise_for_status() body = response.json() if "error" in body: raise RuntimeError(f"{method}: {body['error']['message']}") return body["result"]
rpc("initialize", { "protocolVersion": "2025-06-18", "capabilities": {}, "clientInfo": {"name": "reporting-script", "version": "1.0.0"},})
tools = rpc("tools/list")["tools"]print(f"{len(tools)} tools reachable with this token")
projects = rpc("tools/call", {"name": "list_projects", "arguments": {}})print(projects["structuredContent"])What comes back from a tool call?
Every RankX AI tool returns three things, and which one you want depends on the caller:
structuredContent, the machine-readable payload. This is what a script should read.content, a readable rendering for text-only clients._meta, which carries the website acted on, a link into RankX AI, and for a tool that spends, the credits charged and the balance remaining.
Every tool also publishes an output schema in tools/list, so a strict
client can validate what it receives.
Which rules does a script have to respect?
Poll the background jobs. start_site_audit, write_article,
generate_article, get_keyword_trends, publish_content_item,
propose_page_optimisation, run_shopping_check and create_content_brief
return at once and do the work in the background. Poll with the matching status
tool at a sensible interval, and do not start a job again while it is running.
Treat the rate limits as real limits. RankX AI allows 600 requests an
hour per account, counting every request to the endpoint, and 120 an hour
for tool calls whose scope is not read. Both are shared across every
credential on the account, and a write uses one of each.
Both limits fail closed: if the limiter cannot be read, the request is denied. Back off rather than retrying at once.
Never treat null as zero. Any metric field can be null, and null means
unmeasured. A report that shows it as 0% tells its reader they are invisible
when nothing was measured.
Read which refusal you got. There are four, with four different remedies, and only one of them is fixed by adding credits. See credits and metering.
Do not spend on a schedule without a ceiling. The spend tools exist so an
agent can act, not so a cron job runs a full sweep every night by accident.
Check the balance first with get_credit_balance, which is free.
Why set clientInfo?
clientInfo in initialize is worth setting to something meaningful. RankX AI
records it for each credential, so a connection that calls itself
reporting-script is easy to tell apart when you are working out where a spend
came from.
Where to go next
- Authentication and scopes for scopes and rate limits.
- The tool reference for every tool and its inputs.
- Examples for the dispatch-and-poll pairs worked through.
Questions
Can a CI job sign in to RankX AI with OAuth?
No. RankX AI's authorisation server issues OAuth credentials only through a person approving in a browser, and it has no client credentials grant. A personal access token is the supported credential for any caller with nobody at a browser.
Does the RankX AI MCP endpoint keep a session?
No. The endpoint is stateless: each POST carries one JSON-RPC message and gets one JSON response, with no session id to store. Batched requests are refused, and a GET returns 405.
How do I rotate a token without breaking the job?
Create the replacement token, update the secret your job reads, then revoke the old token in RankX AI's MCP settings. Both work in between, so the job never fails.
Last updated