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.
whoamiShow the authenticated user, accessible organisations, granted scopes, credit balances, and useful Pushrank links.
Parameters: None. Read-only, with no additional scope.
list_projectsList the Pushrank projects accessible to the authenticated user.
Parameters: limit (1–50, default 25).
get_project_overviewCompact overview of one project: traffic, digest summary, and status counts.
Parameters: projectId.
get_seo_forecastRead-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_opportunitiesAutomatically 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:writeUpdate 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_digestReturn 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_snapshotRead 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_articlesList articles with scores, quality state, and publication metadata, without the full content.
Parameters: projectId; optional: status, search, limit (max 25).
get_articleReturn one full article: content, meta, quality reports, publication logs, linked keywords, opportunities, and agent runs.
Parameters: projectId, articleId.
get_article_generation_readinessCheck quota, brief completeness, cannibalization, and SERP warnings before generation without creating anything.
Parameters: projectId, keyword, intent, articleType; optional: niche, languageCode.
generate_articleWrite · mcp:articles:generateStart 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_statusRead the progress of an article generation or CMS publication.
Parameters: projectId and exactly one of requestId or articleId; optional: publicationJobId.
get_article_publication_readinessCheck article content, quality, CMS connection, capabilities, and provenance before publication.
Parameters: projectId, articleId.
publish_article_to_cmsWrite · mcp:articles:publishActually publish or update the article in the connected CMS. Requires mcp:articles:publish.
Parameters: projectId, articleId, idempotencyKey (UUID), confirmed=true; optional: acknowledgeQualityOverride.
list_content_planReturn the current editorial plan and the state of every planned topic.
Parameters: projectId.
generate_article_from_plan_itemWrite · mcp:articles:generateStart 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:writePreview 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_performanceRead retained GSC performance for the published page without calling Google live.
Parameters: projectId, articleId.
add_keywordsWrite · mcp:keywords:writePreview 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:writePreview 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:writePreview 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_readinessCheck the URL, known page, duplicate work, and credits before rerunning analysis.
Parameters: projectId, pageUrl.
reanalyze_pageWrite · mcp:analysis:runRerun the normal credit-metered SEO analysis of one page. Requires mcp:analysis:run.
Parameters: projectId, pageUrl, idempotencyKey, confirmed=true.
get_editorial_contextRead structured editorial context without exposing internal RAG documents.
Parameters: projectId.
edit_editorial_contextWrite · mcp:editorial:writePreview 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_profileRead 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:writePreview 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:writePreview 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:writePreview 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:writePreview 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:writePreview 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:writePreview 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:writePreview 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:writeIn 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:writeRelaunch 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_configRead 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:writePreview 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_scheduleRead 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:publishPreview 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:writeWrite 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:writeSchedule 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:writeCancel a pending article publication schedule. Refuses once the publication worker has claimed it. Requires the mcp:actions:write scope.
Parameters: projectId, articleId.
list_keywordsList 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_metricsReturn 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_checklistShow 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:writePreview 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_visibilityRead 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:writePreview 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.
https://ai.pushrank.io/.well-known/oauth-protected-resource/mcphttps://app.pushrank.io/.well-known/oauth-authorization-server- 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.
- Registration — the client registers itself through dynamic client registration (registration_endpoint) as a public client, without a secret.
- 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.
- 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.
https://ai.pushrank.io/mcpRequired 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).
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.
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.
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}}}'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.