API- en MCP-documentatie
Wat de Pushrank MCP-server beschikbaar stelt en hoe u die handmatig via de API aanroept.
Beschikbare tools
De Pushrank MCP-server stelt 49 tools beschikbaar. Alle antwoorden zijn beperkt tot de projecten van uw organisatie; de 26 schrijfacties zijn hieronder gemarkeerd. Alleen de vermelde parameters worden geaccepteerd: een niet-gedeclareerde parameter wordt geweigerd met een foutmelding die de sleutel noemt, en nooit stilzwijgend genegeerd.
whoamiToon de geverifieerde gebruiker, toegankelijke organisaties, toegekende scopes, tegoedsaldi en handige Pushrank-links.
Parameters: Geen. Alleen-lezen, zonder extra scope.
list_projectsToon de Pushrank-projecten waartoe de geverifieerde gebruiker toegang heeft.
Parameters: limit (1–50, standaard 25).
get_project_overviewCompact overzicht van één project: verkeer, samenvatting van de digest en aantallen per status.
Parameters: projectId.
get_seo_forecastSEO-prognose van één project, alleen-lezen: de schatting van Pushrank (schuifregelaar in de standaardpositie) met de curve, M6, M12, cumulatief totaal, kosten, drempel, dekking, consultantbenchmark, aannames en herkomst, of de reden waarom ze niet beschikbaar is. Hetzelfde detailniveau als de app voor het account. Een aanname, geen garantie.
Parameters: projectId.
list_seo_opportunitiesHaal automatisch de volledige lijst SEO-acties op die bij uw verzoek passen, standaard de actieve, en laat de assistent ze als tabel weergeven. Bereik en levenscyclusstatussen komen overeen met het scherm Acties; het antwoord legt ook uit welke acties op dat scherm verborgen zijn.
Parameters: projectId; optioneel: status (standaard active | todo | in_progress | done | verified | still_present | ignored | all), type, severity, priority, source, query, pageUrl, priorityMin. Standaard pagination=all; pagination=page geeft technische toegang per pagina met page (standaard 1) en pageSize (standaard 10, maximaal 25).
update_seo_opportunity_statusSchrijven · mcp:actions:writeWerkt de status van een of meer SEO-kansen bij (tot 50 per aanroep) en geeft per kans een resultaat: toegepast, al in die status of geweigerd met de reden. Vereist de scope mcp:actions:write.
Parameters: projectId, status; opportunityId voor één kans, of opportunityIds (1 tot 50) voor een batch.
get_gsc_digestGeef de laatste voltooide GSC-digest en de status van de laatste poging terug; genereert geen nieuwe digest.
Parameters: projectId; kind (dashboard_digest | weekly_gsc | monthly_gsc, standaard dashboard_digest).
get_gsc_snapshotLeest alleen bewaarde Google Search Console-snapshots; roept GSC nooit live aan.
Parameters: projectId, dimension (date | page | query | query_page | page_date); optioneel: period, compareTo (zelfde duur), pageUrl, offset, limit (max. 50).
list_articlesToon artikelen met scores, kwaliteitsstatus en publicatiemetadata, zonder de volledige inhoud.
Parameters: projectId; optioneel: status, search, limit (max. 25).
get_articleGeef één volledig artikel terug: inhoud, meta, kwaliteitsrapporten, publicatielogs, gekoppelde zoekwoorden, kansen en agent-runs.
Parameters: projectId, articleId.
get_article_generation_readinessControleer quota, volledigheid van de briefing, kannibalisatie en SERP-waarschuwingen vóór het genereren, zonder iets aan te maken.
Parameters: projectId, keyword, intent, articleType; optioneel: niche, languageCode.
generate_articleSchrijven · mcp:articles:generateStart de normale workflow voor artikelgeneratie met quota en veiligheidscontroles. Vereist mcp:articles:generate.
Parameters: projectId, keyword, intent, idempotencyKey (UUID); optioneel: articleType, niche, languageCode, brief, opportunityId, acknowledgeWarnings.
get_workflow_statusLees de voortgang van een artikelgeneratie of CMS-publicatie.
Parameters: projectId en precies één van requestId of articleId; optioneel: publicationJobId.
get_article_publication_readinessControleer inhoud, kwaliteit, CMS-koppeling, mogelijkheden en herkomst van het artikel vóór publicatie.
Parameters: projectId, articleId.
publish_article_to_cmsSchrijven · mcp:articles:publishPubliceer of werk het artikel daadwerkelijk bij in het gekoppelde CMS. Vereist mcp:articles:publish.
Parameters: projectId, articleId, idempotencyKey (UUID), confirmed=true; optioneel: acknowledgeQualityOverride.
list_content_planGeef het huidige redactieplan en de status van elk gepland onderwerp terug.
Parameters: projectId.
generate_article_from_plan_itemSchrijven · mcp:articles:generateStart na bevestiging de normale generatieworkflow vanuit een planitem. Vereist mcp:articles:generate.
Parameters: projectId, itemId, confirmed=true; optioneel: acknowledgeWarnings.
edit_articleSchrijven · mcp:articles:writeBekijk en pas daarna artikelwijzigingen toe met optimistische versiecontroles. Toepassen vereist mcp:articles:write.
Parameters: projectId, articleId, mode, expectedUpdatedAt, changes (title, slug, content, metaDescription, faqData, ctaData, robotsConfig{index, follow, noSnippet, noArchive}, featuredImageAlt); confirmed=true om toe te passen. Een ctaData met html "" of blocks [] blijft zonder CTA, ook met een URL; een CTA zonder geldige URL wordt niet weergegeven.
get_article_performanceLees de bewaarde GSC-prestaties van de gepubliceerde pagina zonder Google live aan te roepen.
Parameters: projectId, articleId.
add_keywordsSchrijven · mcp:keywords:writeBekijk en voeg daarna tot 100 zoekwoorden toe aan de strategie. Nieuwe zoekwoorden worden verrijkt (volume, moeilijkheid, SERP, intentie) zoals bij toevoegen via het dashboard, zonder tegoedkosten, met een actief abonnement. Een eerder verwijderd zoekwoord wordt teruggezet. Toepassen vereist mcp:keywords:write.
Parameters: projectId, mode, terms[], locale, intent; confirmed=true en idempotencyKey om toe te passen.
update_keywordSchrijven · mcp:keywords:writeBekijk en overschrijf daarna de intentie, status of prioriteitsscore van één zoekwoord. Toepassen vereist mcp:keywords:write.
Parameters: projectId, mode, keywordId, changes (intent, status, priorityScore); confirmed=true en idempotencyKey om toe te passen.
set_keyword_statusesSchrijven · mcp:keywords:writeBekijk en stel daarna één status in voor tot 100 zoekwoorden. Toepassen vereist mcp:keywords:write.
Parameters: projectId, mode, keywordIds[], status; confirmed=true en idempotencyKey om toe te passen.
get_page_reanalysis_readinessControleer de URL, bekende pagina, dubbel werk en tegoed voordat de analyse opnieuw wordt uitgevoerd.
Parameters: projectId, pageUrl.
reanalyze_pageSchrijven · mcp:analysis:runVoer de normale SEO-analyse van één pagina opnieuw uit, met tegoedverbruik. Vereist mcp:analysis:run.
Parameters: projectId, pageUrl, idempotencyKey, confirmed=true.
get_editorial_contextLees gestructureerde redactionele context zonder interne RAG-documenten vrij te geven.
Parameters: projectId.
edit_editorial_contextSchrijven · mcp:editorial:writeBekijk en pas daarna gestructureerde redactionele context toe met versiecontroles. Toepassen vereist mcp:editorial:write.
Parameters: projectId, mode, expectedUpdatedAt, changes (brandName, primaryOffer, audience, benefits, positioning, tone, proofs[]{claim, sourceUrl, excerpt}); confirmed=true om toe te passen.
get_business_profileLees het volledige bedrijfsprofiel: elk feit met status, herkomst en beslissing, gereedheid, ontbrekende kernvelden en legacymodus.
Parameters: projectId.
declare_business_factSchrijven · mcp:editorial:writeBekijk en declareer daarna één feit in het bedrijfsprofiel (aanbod, doelgroep, markt, doelstelling, regel, beperking, seizoensgebondenheid of term). Bij een ingevuld adres wordt de waarde vervangen. Toepassen vereist mcp:editorial:write.
Parameters: projectId, mode, expectedRevision, idempotencyKey, address, value; confirmed=true om toe te passen.
replace_business_factSchrijven · mcp:editorial:writeBekijk en overschrijf daarna de waarde van één bedrijfsfeit. Toepassen vereist mcp:editorial:write.
Parameters: projectId, mode, expectedRevision, idempotencyKey, factId, value; confirmed=true om toe te passen.
confirm_business_factSchrijven · mcp:editorial:writeBekijk en bevestig daarna één voorgesteld bedrijfsfeit. Toepassen vereist mcp:editorial:write.
Parameters: projectId, mode, expectedRevision, idempotencyKey, factId; confirmed=true om toe te passen.
reject_business_factSchrijven · mcp:editorial:writeBekijk een voorstel of bevestigd bedrijfsfeit en wijs het daarna af; u kunt het later herstellen. Toepassen vereist mcp:editorial:write.
Parameters: projectId, mode, expectedRevision, idempotencyKey, factId, reason; confirmed=true om toe te passen.
withdraw_business_factSchrijven · mcp:editorial:writeBekijk een bedrijfsfeit en verwijder het daarna definitief; het kan niet worden hersteld. Toepassen vereist mcp:editorial:write.
Parameters: projectId, mode, expectedRevision, idempotencyKey, factId, reason; confirmed=true om toe te passen.
restore_business_factSchrijven · mcp:editorial:writeBekijk een afgewezen bedrijfsfeit en zet het daarna terug naar voorgesteld. Toepassen vereist mcp:editorial:write.
Parameters: projectId, mode, expectedRevision, idempotencyKey, factId; confirmed=true om toe te passen.
reorder_business_offersSchrijven · mcp:editorial:writeBekijk en vervang daarna de volgorde van de aanbiedingen. Toepassen vereist mcp:editorial:write.
Parameters: projectId, mode, expectedRevision, idempotencyKey, offerIds[]; confirmed=true om toe te passen.
adopt_business_profileSchrijven · mcp:editorial:writeAlleen in legacymodus: bekijk en bevestig daarna het profiel dat uit bestaande gegevens is hersteld, waarbij u in dezelfde wijziging onjuiste feiten afwijst en ontbrekende kernvelden opgeeft. Kan niet ongedaan worden gemaakt. Toepassen vereist mcp:editorial:write.
Parameters: projectId, mode, expectedRevision, idempotencyKey, rejectFactIds[], missingFacts[]{address, value}; confirmed=true om toe te passen.
retry_project_contextSchrijven · mcp:editorial:writeStart de herbouw van de projectcontext opnieuw na een mislukking (projectContext.retry = available in get_article_generation_readiness), net als de knop in de instellingen. Bekijk de status en zet de herbouw daarna opnieuw in de wachtrij; een herhaalde aanroep geeft de al geplande herbouw terug; na een nieuwe mislukking is elke toepassing een nieuwe poging. Toepassen vereist mcp:editorial:write.
Parameters: projectId, mode; confirmed=true om toe te passen.
get_cms_configLees het CMS-type, de verbindingsstatus, de datum van de laatste test en de niet-geheime instellingen. Geheimen worden nooit teruggegeven, alleen of ze zijn opgeslagen.
Parameters: projectId.
configure_cmsSchrijven · mcp:integrations:writeBekijk en sla daarna de niet-geheime instellingen van een bestaande WordPress-, Webflow-, Wix-, Framer- (indien ingeschakeld) of aangepaste webhookverbinding op en test ze. Inloggegevens voert u alleen in het PushRank-dashboard in en blijven ongewijzigd. Shopify blijft in het dashboard. Toepassen vereist mcp:integrations:write en de rol eigenaar.
Parameters: projectId, mode, cmsType; per type: wpUrl, wpUsername | webflowCollectionId | wixSiteId, wixMemberId | framerProjectId, framerCollectionId, framerFieldMapping (Framer, indien ingeschakeld) | webhookUrl; confirmed=true en idempotencyKey om toe te passen.
get_publishing_scheduleLees de artikelplanning van de kaart Onderwerpen: aan/uit, dagen, uur, tijdzone en Publiceren zonder controle, het volgende geplande artikel en wat het artikelquotum toestaat tot het wordt vernieuwd.
Parameters: projectId.
update_publishing_scheduleSchrijven · mcp:articles:generate, mcp:articles:publishBekijk en pas daarna een wijziging in de artikelplanning toe, met dezelfde regels als de kaart Onderwerpen. Toepassen vereist mcp:articles:generate om aan/uit, dagen, uur of tijdzone te wijzigen, en mcp:articles:publish om Publiceren zonder controle te wijzigen.
Parameters: projectId, mode; optioneel enabled, publishDays (0 tot 7 dagen uit mon…sun), publishHour (0–23), timezone (Europe/Paris, Europe/London, America/New_York, America/Los_Angeles, Asia/Tokyo), autoPublish; confirmed=true en idempotencyKey om toe te passen.
update_article_statusSchrijven · mcp:actions:writeSchrijf de opgeslagen publicatiestatus van een artikel terug en leg de MCP-herkomst vast. Vereist de scope mcp:actions:write.
Parameters: projectId, articleId, status (draft | published); optioneel: cmsUrl (alleen HTTPS), publishedAt (ISO 8601, alleen bij published; standaard nu). Inplannen wordt niet ondersteund, omdat deze tool geen planningstijdstempel heeft.
schedule_article_publicationSchrijven · mcp:actions:writePlan een toekomstige artikelpublicatie in met de bestaande kwaliteitscontrole en bescherming tegen gelijktijdigheid. Vereist de scope mcp:actions:write.
Parameters: projectId, articleId, scheduledAt (toekomstige ISO 8601-tijdstempel met expliciete offset).
cancel_article_publication_scheduleSchrijven · mcp:actions:writeAnnuleer een openstaande publicatieplanning van een artikel. Wordt geweigerd zodra de publicatieworker deze heeft opgepakt. Vereist de scope mcp:actions:write.
Parameters: projectId, articleId.
list_keywordsToon verrijkte zoekwoorden met statistieken, status, prioriteit, artikeldekking en canonieke intentie.
Parameters: projectId; optioneel: intent, source, status, search, limit (max. 25), offset (pagineren met pagination.nextOffset).
get_keyword_metricsGeef al opgeslagen statistieken terug voor maximaal 20 termen; roept nooit een provider aan en start geen vernieuwing.
Parameters: projectId, terms (1–20); optioneel: locale (standaard fr), locationCode (standaard 2250).
get_onboarding_checklistToon de vijf startstappen van een project, wat er nog te doen is, de dashboardlink voor elke stap en de status van de welkomstbacklink. Clients die MCP Apps ondersteunen, tonen dit als interactieve checklist.
Parameters: projectId.
claim_welcome_giftSchrijven · mcp:backlinks:writeBekijk en claim daarna de backlink die u krijgt zodra de vijf stappen zijn voltooid: een pagina van de projectsite en de ankertekst. Alleen voor de eigenaar, met een proefperiode of actief abonnement; één per organisatie. Tijdens de proefperiode wordt de backlink alleen gereserveerd: hij wordt besteld wanneer de proefperiode eindigt, met de eerste betaalde maand. Toepassen vereist mcp:backlinks:write.
Parameters: projectId, mode, targetUrl, anchorText; confirmed=true om toe te passen.
get_ai_visibilityLeest de AI-zichtbaarheid van een project: gevolgde prompts, score, resultaten per prompt en per AI-engine (geciteerd, genoemd, positie, fragment), meetperiodes en optioneel de vergelijking met concurrenten. Geeft nooit de volledige antwoordtekst terug en start geen meting.
Parameters: projectId; optioneel: collectionId, prompt, provider, offset, limit (1–25, standaard 15), includeCompetitors.
manage_ai_visibility_promptsSchrijven · mcp:ai-visibility:writeToont eerst een voorbeeld en past daarna het toevoegen, verwijderen of herformuleren van gevolgde prompts toe. Een geherformuleerde prompt begint zonder historie. Start geen meting: nieuwe prompts worden bij de volgende meting gemeten. Toepassen vereist mcp:ai-visibility:write.
Parameters: projectId, mode, operation (add met prompts, remove met prompts, of rename met from en to); confirmed=true om toe te passen.
OAuth-verbinding
MCP-clients zoals Claude of ChatGPT verbinden via OAuth: geef ze het endpoint en ze vinden de rest in de metadata hieronder.
https://ai.pushrank.io/.well-known/oauth-protected-resource/mcphttps://app.pushrank.io/.well-known/oauth-authorization-server- Detectie — een niet-geauthenticeerde aanroep van het endpoint geeft 401 met een WWW-Authenticate-header die naar de resource-metadata verwijst; die noemen de autorisatieserver en de ondersteunde scopes.
- Registratie — de client registreert zich via dynamische clientregistratie (registration_endpoint) als publieke client, zonder secret.
- Autorisatie — authorization-code-flow met PKCE (S256) en de parameter resource gelijk aan het MCP-endpoint; de gebruiker logt in bij Pushrank en keurt de gevraagde scopes goed.
- Tokens — het token_endpoint geeft een toegangstoken van 1 uur en, als offline_access wordt gevraagd, een vernieuwingstoken van 30 dagen. Stuur het toegangstoken mee als Authorization: Bearer.
Handmatig API-gebruik
Voor een script of een client zonder OAuth roept u het JSON-RPC 2.0-endpoint aan met een bearer-token dat u aanmaakt via het tabblad "API / handmatig".
https://ai.pushrank.io/mcpVereiste headers
- Authorization: Bearer <token> — verplicht bij elk verzoek.
- Content-Type: application/json.
- Accept: application/json, text/event-stream.
- mcp-session-id — teruggegeven in de responseheaders van initialize; herhaal deze bij elke volgende aanroep.
- mcp-protocol-version: 2025-06-18 bij de aanroepen na initialize.
Volgorde van aanroepen
1. initialize — opent een sessie. Lees de responseheader mcp-session-id (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 — toont de beschikbare tools en hun invoerschema's.
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 — voert een tool uit met de bijbehorende argumenten.
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, limieten en intrekking
MCP-tokens zijn speciaal bedoeld hiervoor en staan los van uw sessie.
Handmatig token
Een handmatig token heeft standaard de scopes mcp:projects:read en mcp:actions:read. Het verloopt nooit en kan op elk moment worden ingetrokken.
Schrijfacties
Status- en planningsupdates vereisen mcp:actions:write. Genereren gebruikt mcp:articles:generate, publiceren mcp:articles:publish, artikelen bewerken mcp:articles:write, zoekwoordwijzigingen mcp:keywords:write, heranalyse mcp:analysis:run, redactionele context mcp:editorial:write, wijzigingen in de CMS-verbinding mcp:integrations:write, het claimen van de welkomstbacklink mcp:backlinks:write en de gevolgde prompts van AI-zichtbaarheid mcp:ai-visibility:write. Wijzigingen in de artikelplanning gebruiken mcp:articles:generate, en Publiceren zonder controle mcp:articles:publish. Deze specifieke scopes worden via OAuth toegekend of aangevinkt bij een handmatige sleutel, bij het aanmaken of later. Een token zonder de vereiste scope krijgt insufficientScope.
OAuth-geldigheidsduur
Voor OAuth-clients (Claude, ChatGPT…) is het toegangstoken 1 u geldig en het vernieuwingstoken 30 dagen.
Intrekking
Trek een handmatig token in via het tabblad "API / handmatig". Intrekking gaat direct in en heeft geen invloed op uw sessie; OAuth-toegang trekt u in vanuit de verbonden client.
Organisatiebereik
De server beperkt elk antwoord tot de projecten van de organisaties waarvan u lid bent.