Early Access

API & MCP documentation

What the Pushrank MCP server exposes and how to call it manually via the API.

Exposed tools

The Pushrank MCP server exposes 49 tools. All responses are limited to your organisation's projects; the 26 write actions are flagged below. Only the listed parameters are accepted: an undeclared parameter is rejected with an error naming the key, never silently ignored.

whoami

Show the authenticated user, accessible organisations, granted scopes, credit balances, and useful Pushrank links.

Parameters: None. Read-only, with no additional scope.

list_projects

List the Pushrank projects accessible to the authenticated user.

Parameters: limit (1–50, default 25).

get_project_overview

Compact overview of one project: traffic, digest summary, and status counts.

Parameters: projectId.

get_seo_forecast

Read-only SEO forecast of one project: the Pushrank estimate (slider at its default position) with its curve, M6, M12, cumulative total, cost, threshold, coverage, consultant benchmark, assumptions and provenance, or why it is unavailable. Same level of detail as the app for the account. An assumption, not a guarantee.

Parameters: projectId.

list_seo_opportunities

Automatically retrieve the complete list of SEO actions matching your request, active by default, and guide the assistant to present them as a table. Scope and lifecycle states match the Actions screen; the response also explains actions hidden from that screen.

Parameters: projectId; optional: status (active by default | todo | in_progress | done | verified | still_present | ignored | all), type, severity, priority, source, query, pageUrl, priorityMin. pagination=all by default; pagination=page enables technical page-by-page access with page (default 1) and pageSize (default 10, maximum 25).

update_seo_opportunity_statusWrite · mcp:actions:write

Update the workflow status of one or several SEO opportunities (up to 50 per call) and return one result per opportunity: applied, already in that status, or refused with its reason. Requires the mcp:actions:write scope.

Parameters: projectId, status; opportunityId for one opportunity, or opportunityIds (1 to 50) for a batch.

get_gsc_digest

Return the latest completed GSC digest and the status of the latest attempt; does not generate a new digest.

Parameters: projectId; kind (dashboard_digest | weekly_gsc | monthly_gsc, default dashboard_digest).

get_gsc_snapshot

Read retained Google Search Console snapshots only; never calls GSC live.

Parameters: projectId, dimension (date | page | query | query_page | page_date); optional: period, compareTo (same duration), pageUrl, offset, limit (max 50).

list_articles

List articles with scores, quality state, and publication metadata, without the full content.

Parameters: projectId; optional: status, search, limit (max 25).

get_article

Return one full article: content, meta, quality reports, publication logs, linked keywords, opportunities, and agent runs.

Parameters: projectId, articleId.

get_article_generation_readiness

Check quota, brief completeness, cannibalization, and SERP warnings before generation without creating anything.

Parameters: projectId, keyword, intent, articleType; optional: niche, languageCode.

generate_articleWrite · mcp:articles:generate

Start the normal article-generation workflow with quotas and safety checks. Requires mcp:articles:generate.

Parameters: projectId, keyword, intent, idempotencyKey (UUID); optional: articleType, niche, languageCode, brief, opportunityId, acknowledgeWarnings.

get_workflow_status

Read the progress of an article generation or CMS publication.

Parameters: projectId and exactly one of requestId or articleId; optional: publicationJobId.

get_article_publication_readiness

Check article content, quality, CMS connection, capabilities, and provenance before publication.

Parameters: projectId, articleId.

publish_article_to_cmsWrite · mcp:articles:publish

Actually publish or update the article in the connected CMS. Requires mcp:articles:publish.

Parameters: projectId, articleId, idempotencyKey (UUID), confirmed=true; optional: acknowledgeQualityOverride.

list_content_plan

Return the current editorial plan and the state of every planned topic.

Parameters: projectId.

generate_article_from_plan_itemWrite · mcp:articles:generate

Start the normal generation workflow from a plan item after confirmation. Requires mcp:articles:generate.

Parameters: projectId, itemId, confirmed=true; optional: acknowledgeWarnings.

edit_articleWrite · mcp:articles:write

Preview and then apply article edits with optimistic version checks. Apply requires mcp:articles:write.

Parameters: projectId, articleId, mode, expectedUpdatedAt, changes (title, slug, content, metaDescription, faqData, ctaData, robotsConfig{index, follow, noSnippet, noArchive}, featuredImageAlt); confirmed=true to apply. A ctaData with html "" or blocks [] stays without a CTA, even with a URL; a CTA without a valid URL is not rendered.

get_article_performance

Read retained GSC performance for the published page without calling Google live.

Parameters: projectId, articleId.

add_keywordsWrite · mcp:keywords:write

Preview and then add up to 100 keywords to the strategy. New keywords are enriched (volume, difficulty, SERP, intent) like a dashboard addition, at no credit cost, with an active plan. A keyword removed earlier is put back. Apply requires mcp:keywords:write.

Parameters: projectId, mode, terms[], locale, intent; confirmed=true and idempotencyKey to apply.

update_keywordWrite · mcp:keywords:write

Preview and then overwrite the intent, status or priority score of one keyword. Apply requires mcp:keywords:write.

Parameters: projectId, mode, keywordId, changes (intent, status, priorityScore); confirmed=true and idempotencyKey to apply.

set_keyword_statusesWrite · mcp:keywords:write

Preview and then set one status on up to 100 keywords. Apply requires mcp:keywords:write.

Parameters: projectId, mode, keywordIds[], status; confirmed=true and idempotencyKey to apply.

get_page_reanalysis_readiness

Check the URL, known page, duplicate work, and credits before rerunning analysis.

Parameters: projectId, pageUrl.

reanalyze_pageWrite · mcp:analysis:run

Rerun the normal credit-metered SEO analysis of one page. Requires mcp:analysis:run.

Parameters: projectId, pageUrl, idempotencyKey, confirmed=true.

get_editorial_context

Read structured editorial context without exposing internal RAG documents.

Parameters: projectId.

edit_editorial_contextWrite · mcp:editorial:write

Preview and then apply structured editorial context with version checks. Apply requires mcp:editorial:write.

Parameters: projectId, mode, expectedUpdatedAt, changes (brandName, primaryOffer, audience, benefits, positioning, tone, proofs[]{claim, sourceUrl, excerpt}); confirmed=true to apply.

get_business_profile

Read the full business profile: every fact with its status, provenance and decision, readiness, missing core fields and legacy mode.

Parameters: projectId.

declare_business_factWrite · mcp:editorial:write

Preview and then declare one fact in the business profile (offer, audience, market, objective, rule, constraint, seasonality or term). A filled address has its value replaced. Apply requires mcp:editorial:write.

Parameters: projectId, mode, expectedRevision, idempotencyKey, address, value; confirmed=true to apply.

replace_business_factWrite · mcp:editorial:write

Preview and then overwrite the value of one business fact. Apply requires mcp:editorial:write.

Parameters: projectId, mode, expectedRevision, idempotencyKey, factId, value; confirmed=true to apply.

confirm_business_factWrite · mcp:editorial:write

Preview and then confirm one proposed business fact. Apply requires mcp:editorial:write.

Parameters: projectId, mode, expectedRevision, idempotencyKey, factId; confirmed=true to apply.

reject_business_factWrite · mcp:editorial:write

Preview and then reject one proposed or confirmed business fact; it can be restored later. Apply requires mcp:editorial:write.

Parameters: projectId, mode, expectedRevision, idempotencyKey, factId, reason; confirmed=true to apply.

withdraw_business_factWrite · mcp:editorial:write

Preview and then remove one business fact for good; it cannot be restored. Apply requires mcp:editorial:write.

Parameters: projectId, mode, expectedRevision, idempotencyKey, factId, reason; confirmed=true to apply.

restore_business_factWrite · mcp:editorial:write

Preview and then return one rejected business fact to proposed. Apply requires mcp:editorial:write.

Parameters: projectId, mode, expectedRevision, idempotencyKey, factId; confirmed=true to apply.

reorder_business_offersWrite · mcp:editorial:write

Preview and then replace the order of the offers. Apply requires mcp:editorial:write.

Parameters: projectId, mode, expectedRevision, idempotencyKey, offerIds[]; confirmed=true to apply.

adopt_business_profileWrite · mcp:editorial:write

In legacy mode only: preview and then confirm the profile recovered from existing data, rejecting wrong facts and declaring the missing core fields in the same change. Cannot be undone. Apply requires mcp:editorial:write.

Parameters: projectId, mode, expectedRevision, idempotencyKey, rejectFactIds[], missingFacts[]{address, value}; confirmed=true to apply.

retry_project_contextWrite · mcp:editorial:write

Relaunch the project context rebuild after it failed (projectContext.retry = available in get_article_generation_readiness), like the settings button. Preview the state, then requeue; a replayed call returns the rebuild already queued; after a new failure, each apply is a new retry. Apply requires mcp:editorial:write.

Parameters: projectId, mode; confirmed=true to apply.

get_cms_config

Read the CMS type, connection state, last test date and non-secret settings. Secrets are never returned, only whether each one is stored.

Parameters: projectId.

configure_cmsWrite · mcp:integrations:write

Preview and then save and test the non-secret settings of an existing WordPress, Webflow, Wix, Framer (when enabled) or custom webhook connection. Credentials are entered only in the PushRank dashboard and stay unchanged. Shopify stays in the dashboard. Apply requires mcp:integrations:write and the owner role.

Parameters: projectId, mode, cmsType; per type: wpUrl, wpUsername | webflowCollectionId | wixSiteId, wixMemberId | framerProjectId, framerCollectionId, framerFieldMapping (Framer, when enabled) | webhookUrl; confirmed=true and idempotencyKey to apply.

get_publishing_schedule

Read the article planning set on the Topics card: on/off, days, hour, time zone and Publish without review, the next planned article and what the article quota allows until it renews.

Parameters: projectId.

update_publishing_scheduleWrite · mcp:articles:generate, mcp:articles:publish

Preview and then apply a change to the article planning, with the same rules as the Topics card. Apply requires mcp:articles:generate to change on/off, days, hour or time zone, and mcp:articles:publish to change Publish without review.

Parameters: projectId, mode; optional enabled, publishDays (0 to 7 days among mon…sun), publishHour (0–23), timezone (Europe/Paris, Europe/London, America/New_York, America/Los_Angeles, Asia/Tokyo), autoPublish; confirmed=true and idempotencyKey to apply.

update_article_statusWrite · mcp:actions:write

Write back an article's persisted publication status and record MCP provenance. Requires the mcp:actions:write scope.

Parameters: projectId, articleId, status (draft | published); optional: cmsUrl (HTTPS only), publishedAt (ISO 8601, published only; defaults to now). Scheduling is not supported because this tool has no scheduling timestamp.

schedule_article_publicationWrite · mcp:actions:write

Schedule a future article publication with the existing quality gate and concurrency protection. Requires the mcp:actions:write scope.

Parameters: projectId, articleId, scheduledAt (future ISO 8601 timestamp with an explicit offset).

cancel_article_publication_scheduleWrite · mcp:actions:write

Cancel a pending article publication schedule. Refuses once the publication worker has claimed it. Requires the mcp:actions:write scope.

Parameters: projectId, articleId.

list_keywords

List enriched keywords with metrics, status, priority, article coverage, and canonical intent.

Parameters: projectId; optional: intent, source, status, search, limit (max 25), offset (paginate with pagination.nextOffset).

get_keyword_metrics

Return already-stored metrics for up to 20 terms; never calls a provider or triggers a refresh.

Parameters: projectId, terms (1–20); optional: locale (default fr), locationCode (default 2250).

get_onboarding_checklist

Show the five getting-started steps of a project, what remains to do, the dashboard link for each step and the state of the welcome backlink. Clients that support MCP Apps display it as an interactive checklist.

Parameters: projectId.

claim_welcome_giftWrite · mcp:backlinks:write

Preview and then claim the backlink offered once the five steps are done: a page of the project's site and its anchor text. Owner only, with a trial or an active plan; one per organisation. During the trial the backlink is only reserved: it is ordered when the trial ends, with the first paid month. Apply requires mcp:backlinks:write.

Parameters: projectId, mode, targetUrl, anchorText; confirmed=true to apply.

get_ai_visibility

Read a project's AI visibility: tracked prompts, score, results per prompt and per AI engine (cited, mentioned, rank, excerpt), measurement periods and, optionally, the competitor comparison. Never returns the full answer text and never triggers a measurement.

Parameters: projectId; optional: collectionId, prompt, provider, offset, limit (1–25, default 15), includeCompetitors.

manage_ai_visibility_promptsWrite · mcp:ai-visibility:write

Preview and then apply adding, removing or rewording tracked prompts. A reworded prompt starts with no history. Never triggers a measurement: new prompts are measured at the next run. Apply requires mcp:ai-visibility:write.

Parameters: projectId, mode, operation (add with prompts, remove with prompts, or rename with from and to); confirmed=true to apply.

OAuth connection

MCP clients such as Claude or ChatGPT connect through OAuth: give them the endpoint and they discover everything else from the metadata below.

Resource metadatahttps://ai.pushrank.io/.well-known/oauth-protected-resource/mcp
Authorization serverhttps://app.pushrank.io/.well-known/oauth-authorization-server
  1. Discovery — an unauthenticated call to the endpoint returns 401 with a WWW-Authenticate header pointing at the resource metadata, which names the authorization server and the supported scopes.
  2. Registration — the client registers itself through dynamic client registration (registration_endpoint) as a public client, without a secret.
  3. Authorization — authorization code flow with PKCE (S256) and the resource parameter set to the MCP endpoint; the user signs in to Pushrank and approves the requested scopes.
  4. Tokens — the token_endpoint returns a 1 h access token, plus a 30-day refresh token when offline_access is requested. Send the access token as Authorization: Bearer.

Manual API usage

For a script or a client without OAuth, call the JSON-RPC 2.0 endpoint with a bearer token created from the "API / manual" tab.

Endpointhttps://ai.pushrank.io/mcp

Required headers

  • Authorization: Bearer <token> — required on every request.
  • Content-Type: application/json.
  • Accept: application/json, text/event-stream.
  • mcp-session-id — returned in the initialize response headers; repeat it on every subsequent call.
  • mcp-protocol-version: 2025-06-18 on the calls that follow initialize.

Call sequence

1. initialize — opens a session. Read the mcp-session-id response header (curl -i).

terminal
curl -i -X POST "https://ai.pushrank.io/mcp" \
  -H "Authorization: Bearer pushrank_mcp_xxxxxxxx" \
  -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":"pushrank-manual-client","version":"1.0"}}}'

2. tools/list — lists the available tools and their input schemas.

terminal
curl -X POST "https://ai.pushrank.io/mcp" \
  -H "Authorization: Bearer pushrank_mcp_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id>" \
  -H "mcp-protocol-version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

3. tools/call — runs a tool with its arguments.

terminal
curl -X POST "https://ai.pushrank.io/mcp" \
  -H "Authorization: Bearer pushrank_mcp_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id>" \
  -H "mcp-protocol-version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_projects","arguments":{"limit":10}}}'
The server is stateful: without a valid mcp-session-id header, any call after initialize returns "Session not found" (404).

Scopes, limits, and revocation

MCP tokens are dedicated and independent from your session.

Manual token

A manual token carries the mcp:projects:read and mcp:actions:read scopes by default. It never expires and can be revoked at any time.

Write actions

Status and scheduling updates require mcp:actions:write. Generation uses mcp:articles:generate, publication mcp:articles:publish, article editing mcp:articles:write, keyword changes mcp:keywords:write, reanalysis mcp:analysis:run, editorial context mcp:editorial:write, CMS connection changes mcp:integrations:write, the welcome backlink claim mcp:backlinks:write, and tracked AI visibility prompts mcp:ai-visibility:write. Article planning changes use mcp:articles:generate, and Publish without review mcp:articles:publish. These dedicated scopes are granted through OAuth, or ticked on a manual key, at creation or later. A token without the required scope gets insufficientScope.

OAuth lifetimes

For OAuth clients (Claude, ChatGPT…), the access token lasts 1 h and the refresh token 30 days.

Revocation

Revoke a manual token from the "API / manual" tab. Revocation is immediate and does not affect your session; OAuth access is revoked from the connected client.

Organisation scope

The server limits every response to the projects of the organisations you belong to.