Early Access

API- & MCP-Dokumentation

Was der Pushrank-MCP-Server bereitstellt und wie Sie ihn manuell über die API aufrufen.

Bereitgestellte Tools

Der Pushrank-MCP-Server stellt 49 Tools bereit. Alle Antworten sind auf die Projekte Ihrer Organisation beschränkt; die 26 Schreibaktionen sind unten gekennzeichnet. Nur die aufgeführten Parameter werden akzeptiert: Ein nicht deklarierter Parameter wird mit einer Fehlermeldung abgelehnt, die den Schlüssel nennt, und nie stillschweigend ignoriert.

whoami

Zeigt den authentifizierten Nutzer, zugängliche Organisationen, gewährte Scopes, Credit-Guthaben und nützliche Pushrank-Links.

Parameter: Keine. Nur Lesezugriff, ohne zusätzlichen Scope.

list_projects

Listet die Pushrank-Projekte auf, auf die der authentifizierte Nutzer Zugriff hat.

Parameter: limit (1–50, Standard 25).

get_project_overview

Kompakte Übersicht eines Projekts: Traffic, Digest-Zusammenfassung und Statuszahlen.

Parameter: projectId.

get_seo_forecast

SEO-Prognose eines Projekts, schreibgeschützt: die Schätzung von Pushrank (Schieberegler in Standardposition) mit Kurve, M6, M12, kumuliertem Gesamtwert, Kosten, Schwelle, Deckung, Berater-Vergleich, Annahmen und Herkunft, oder der Grund, warum sie nicht verfügbar ist. Gleicher Detaillierungsgrad wie in der App für das Konto. Eine Annahme, keine Garantie.

Parameter: projectId.

list_seo_opportunities

Ruft automatisch die vollständige Liste der SEO-Aktionen ab, die Ihrer Anfrage entsprechen (standardmäßig aktive), und leitet den Assistenten an, sie als Tabelle darzustellen. Umfang und Lebenszyklus-Status entsprechen der Ansicht „Aktionen“; die Antwort erläutert zudem, welche Aktionen dort ausgeblendet sind.

Parameter: projectId; optional: status (standardmäßig active | todo | in_progress | done | verified | still_present | ignored | all), type, severity, priority, source, query, pageUrl, priorityMin. Standardmäßig pagination=all; pagination=page aktiviert den technischen seitenweisen Zugriff mit page (Standard 1) und pageSize (Standard 10, maximal 25).

update_seo_opportunity_statusSchreiben · mcp:actions:write

Aktualisiert den Workflow-Status einer oder mehrerer SEO-Chancen (bis zu 50 pro Aufruf) und liefert ein Ergebnis pro Chance: angewendet, bereits in diesem Status oder abgelehnt mit Grund. Erfordert den Scope mcp:actions:write.

Parameter: projectId, status; opportunityId für eine Chance oder opportunityIds (1 bis 50) für einen Stapel.

get_gsc_digest

Gibt den letzten abgeschlossenen GSC-Digest und den Status des letzten Versuchs zurück; erstellt keinen neuen Digest.

Parameter: projectId; kind (dashboard_digest | weekly_gsc | monthly_gsc, Standard dashboard_digest).

get_gsc_snapshot

Liest nur gespeicherte Google-Search-Console-Snapshots; ruft GSC nie live ab.

Parameter: projectId, dimension (date | page | query | query_page | page_date); optional: period, compareTo (gleiche Dauer), pageUrl, offset, limit (max. 50).

list_articles

Listet Artikel mit Scores, Qualitätsstatus und Veröffentlichungsmetadaten auf, ohne den vollständigen Inhalt.

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

get_article

Gibt einen vollständigen Artikel zurück: Inhalt, Meta, Qualitätsberichte, Veröffentlichungsprotokolle, verknüpfte Keywords, Chancen und Agent-Läufe.

Parameter: projectId, articleId.

get_article_generation_readiness

Prüft vor der Generierung Kontingent, Vollständigkeit des Briefings, Kannibalisierung und SERP-Warnungen, ohne etwas zu erstellen.

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

generate_articleSchreiben · mcp:articles:generate

Startet den regulären Workflow zur Artikelgenerierung mit Kontingenten und Sicherheitsprüfungen. Erfordert mcp:articles:generate.

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

get_workflow_status

Liest den Fortschritt einer Artikelgenerierung oder CMS-Veröffentlichung.

Parameter: projectId und genau eines von requestId oder articleId; optional: publicationJobId.

get_article_publication_readiness

Prüft vor der Veröffentlichung Artikelinhalt, Qualität, CMS-Verbindung, Funktionen und Herkunft.

Parameter: projectId, articleId.

publish_article_to_cmsSchreiben · mcp:articles:publish

Veröffentlicht oder aktualisiert den Artikel tatsächlich im verbundenen CMS. Erfordert mcp:articles:publish.

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

list_content_plan

Gibt den aktuellen Redaktionsplan und den Status jedes geplanten Themas zurück.

Parameter: projectId.

generate_article_from_plan_itemSchreiben · mcp:articles:generate

Startet nach Bestätigung den regulären Generierungs-Workflow aus einem Planeintrag. Erfordert mcp:articles:generate.

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

edit_articleSchreiben · mcp:articles:write

Zeigt Artikeländerungen in der Vorschau an und wendet sie mit optimistischer Versionsprüfung an. Das Anwenden erfordert mcp:articles:write.

Parameter: projectId, articleId, mode, expectedUpdatedAt, changes (title, slug, content, metaDescription, faqData, ctaData, robotsConfig{index, follow, noSnippet, noArchive}, featuredImageAlt); confirmed=true zum Anwenden. Ein ctaData mit html "" oder blocks [] bleibt ohne CTA, auch mit URL; ein CTA ohne gültige URL wird nicht dargestellt.

get_article_performance

Liest die gespeicherte GSC-Performance der veröffentlichten Seite, ohne Google live abzufragen.

Parameter: projectId, articleId.

add_keywordsSchreiben · mcp:keywords:write

Zeigt bis zu 100 Keywords in der Vorschau an und fügt sie dann der Strategie hinzu. Neue Keywords werden wie beim Hinzufügen im Dashboard angereichert (Volumen, Schwierigkeit, SERP, Intent), ohne Credit-Kosten, bei aktivem Abo. Ein zuvor entferntes Keyword wird wiederhergestellt. Das Anwenden erfordert mcp:keywords:write.

Parameter: projectId, mode, terms[], locale, intent; confirmed=true und idempotencyKey zum Anwenden.

update_keywordSchreiben · mcp:keywords:write

Zeigt in der Vorschau an und überschreibt dann Intent, Status oder Prioritäts-Score eines Keywords. Das Anwenden erfordert mcp:keywords:write.

Parameter: projectId, mode, keywordId, changes (intent, status, priorityScore); confirmed=true und idempotencyKey zum Anwenden.

set_keyword_statusesSchreiben · mcp:keywords:write

Zeigt in der Vorschau an und setzt dann einen Status für bis zu 100 Keywords. Das Anwenden erfordert mcp:keywords:write.

Parameter: projectId, mode, keywordIds[], status; confirmed=true und idempotencyKey zum Anwenden.

get_page_reanalysis_readiness

Prüft URL, bekannte Seite, doppelte Arbeit und Credits, bevor die Analyse erneut ausgeführt wird.

Parameter: projectId, pageUrl.

reanalyze_pageSchreiben · mcp:analysis:run

Führt die reguläre, Credit-basierte SEO-Analyse einer Seite erneut aus. Erfordert mcp:analysis:run.

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

get_editorial_context

Liest den strukturierten redaktionellen Kontext, ohne interne RAG-Dokumente offenzulegen.

Parameter: projectId.

edit_editorial_contextSchreiben · mcp:editorial:write

Zeigt den strukturierten redaktionellen Kontext in der Vorschau an und wendet ihn mit Versionsprüfung an. Das Anwenden erfordert mcp:editorial:write.

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

get_business_profile

Liest das vollständige Unternehmensprofil: jeden Fakt mit Status, Herkunft und Entscheidung, Bereitschaft, fehlende Kernfelder und Legacy-Modus.

Parameter: projectId.

declare_business_factSchreiben · mcp:editorial:write

Zeigt in der Vorschau an und erfasst dann einen Fakt im Unternehmensprofil (Angebot, Zielgruppe, Markt, Ziel, Regel, Einschränkung, Saisonalität oder Begriff). Bei einer bereits belegten Adresse wird der Wert ersetzt. Das Anwenden erfordert mcp:editorial:write.

Parameter: projectId, mode, expectedRevision, idempotencyKey, address, value; confirmed=true zum Anwenden.

replace_business_factSchreiben · mcp:editorial:write

Zeigt in der Vorschau an und überschreibt dann den Wert eines Unternehmensfakts. Das Anwenden erfordert mcp:editorial:write.

Parameter: projectId, mode, expectedRevision, idempotencyKey, factId, value; confirmed=true zum Anwenden.

confirm_business_factSchreiben · mcp:editorial:write

Zeigt in der Vorschau an und bestätigt dann einen vorgeschlagenen Unternehmensfakt. Das Anwenden erfordert mcp:editorial:write.

Parameter: projectId, mode, expectedRevision, idempotencyKey, factId; confirmed=true zum Anwenden.

reject_business_factSchreiben · mcp:editorial:write

Einen vorgeschlagenen oder bestätigten Unternehmensfakt in der Vorschau prüfen und dann ablehnen; er kann später wiederhergestellt werden. Das Anwenden erfordert mcp:editorial:write.

Parameter: projectId, mode, expectedRevision, idempotencyKey, factId, reason; confirmed=true zum Anwenden.

withdraw_business_factSchreiben · mcp:editorial:write

Einen Unternehmensfakt in der Vorschau prüfen und dann endgültig entfernen; er kann nicht wiederhergestellt werden. Das Anwenden erfordert mcp:editorial:write.

Parameter: projectId, mode, expectedRevision, idempotencyKey, factId, reason; confirmed=true zum Anwenden.

restore_business_factSchreiben · mcp:editorial:write

Einen abgelehnten Unternehmensfakt in der Vorschau prüfen und dann wieder auf „vorgeschlagen“ setzen. Das Anwenden erfordert mcp:editorial:write.

Parameter: projectId, mode, expectedRevision, idempotencyKey, factId; confirmed=true zum Anwenden.

reorder_business_offersSchreiben · mcp:editorial:write

Die Reihenfolge der Angebote in der Vorschau prüfen und dann ersetzen. Das Anwenden erfordert mcp:editorial:write.

Parameter: projectId, mode, expectedRevision, idempotencyKey, offerIds[]; confirmed=true zum Anwenden.

adopt_business_profileSchreiben · mcp:editorial:write

Nur im Legacy-Modus: Das aus vorhandenen Daten wiederhergestellte Profil in der Vorschau prüfen und dann bestätigen, dabei falsche Fakten ablehnen und fehlende Kernfelder in derselben Änderung angeben. Kann nicht rückgängig gemacht werden. Das Anwenden erfordert mcp:editorial:write.

Parameter: projectId, mode, expectedRevision, idempotencyKey, rejectFactIds[], missingFacts[]{address, value}; confirmed=true zum Anwenden.

retry_project_contextSchreiben · mcp:editorial:write

Den Neuaufbau des Projektkontexts nach einem Fehlschlag neu starten (projectContext.retry = available in get_article_generation_readiness), wie über die Schaltfläche in den Einstellungen. Den Status in der Vorschau prüfen und dann erneut einreihen; ein wiederholter Aufruf gibt den bereits eingereihten Neuaufbau zurück; nach einem erneuten Fehlschlag ist jedes Anwenden ein neuer Versuch. Das Anwenden erfordert mcp:editorial:write.

Parameter: projectId, mode; confirmed=true zum Anwenden.

get_cms_config

CMS-Typ, Verbindungsstatus, Datum des letzten Tests und nicht geheime Einstellungen lesen. Geheimnisse werden nie zurückgegeben, nur ob sie jeweils gespeichert sind.

Parameter: projectId.

configure_cmsSchreiben · mcp:integrations:write

Die nicht geheimen Einstellungen einer bestehenden WordPress-, Webflow-, Wix-, Framer- (sofern aktiviert) oder benutzerdefinierten Webhook-Verbindung in der Vorschau prüfen, dann speichern und testen. Zugangsdaten werden nur im PushRank-Dashboard eingegeben und bleiben unverändert. Shopify bleibt im Dashboard. Das Anwenden erfordert mcp:integrations:write und die Rolle Inhaber.

Parameter: projectId, mode, cmsType; je nach Typ: wpUrl, wpUsername | webflowCollectionId | wixSiteId, wixMemberId | framerProjectId, framerCollectionId, framerFieldMapping (Framer, sofern aktiviert) | webhookUrl; confirmed=true und idempotencyKey zum Anwenden.

get_publishing_schedule

Die in der Themen-Karte festgelegte Artikelplanung lesen: an/aus, Tage, Uhrzeit, Zeitzone und „Ohne Prüfung veröffentlichen“, den nächsten geplanten Artikel und was das Artikelkontingent bis zur Erneuerung erlaubt.

Parameter: projectId.

update_publishing_scheduleSchreiben · mcp:articles:generate, mcp:articles:publish

Eine Änderung der Artikelplanung in der Vorschau prüfen und dann anwenden, nach denselben Regeln wie in der Themen-Karte. Das Anwenden erfordert mcp:articles:generate, um an/aus, Tage, Uhrzeit oder Zeitzone zu ändern, und mcp:articles:publish, um „Ohne Prüfung veröffentlichen“ zu ändern.

Parameter: projectId, mode; optional enabled, publishDays (0 bis 7 Tage aus mon…sun), publishHour (0–23), timezone (Europe/Paris, Europe/London, America/New_York, America/Los_Angeles, Asia/Tokyo), autoPublish; confirmed=true und idempotencyKey zum Anwenden.

update_article_statusSchreiben · mcp:actions:write

Den gespeicherten Veröffentlichungsstatus eines Artikels zurückschreiben und die MCP-Herkunft erfassen. Erfordert den Scope mcp:actions:write.

Parameter: projectId, articleId, status (draft | published); optional: cmsUrl (nur HTTPS), publishedAt (ISO 8601, nur bei published; Standard ist jetzt). Planung wird nicht unterstützt, da dieses Tool keinen Planungszeitstempel hat.

schedule_article_publicationSchreiben · mcp:actions:write

Eine künftige Artikelveröffentlichung mit der bestehenden Qualitätsprüfung und dem Schutz vor gleichzeitigen Zugriffen planen. Erfordert den Scope mcp:actions:write.

Parameter: projectId, articleId, scheduledAt (künftiger ISO-8601-Zeitstempel mit explizitem Offset).

cancel_article_publication_scheduleSchreiben · mcp:actions:write

Eine ausstehende geplante Artikelveröffentlichung abbrechen. Wird abgelehnt, sobald der Veröffentlichungs-Worker sie übernommen hat. Erfordert den Scope mcp:actions:write.

Parameter: projectId, articleId.

list_keywords

Angereicherte Keywords mit Metriken, Status, Priorität, Artikelabdeckung und kanonischer Suchintention auflisten.

Parameter: projectId; optional: intent, source, status, search, limit (max. 25), offset (Paginierung über pagination.nextOffset).

get_keyword_metrics

Bereits gespeicherte Metriken für bis zu 20 Begriffe zurückgeben; ruft nie einen Anbieter auf und löst keine Aktualisierung aus.

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

get_onboarding_checklist

Die fünf Einstiegsschritte eines Projekts anzeigen, was noch zu tun ist, den Dashboard-Link für jeden Schritt und den Status des Willkommens-Backlinks. Clients mit Unterstützung für MCP Apps zeigen dies als interaktive Checkliste an.

Parameter: projectId.

claim_welcome_giftSchreiben · mcp:backlinks:write

Den nach Abschluss der fünf Schritte angebotenen Backlink in der Vorschau prüfen und dann anfordern: eine Seite der Website des Projekts und ihr Ankertext. Nur für Inhaber, mit Testphase oder aktivem Tarif; einer pro Organisation. Während der Testphase wird der Backlink nur reserviert: Er wird am Ende der Testphase mit dem ersten bezahlten Monat bestellt. Das Anwenden erfordert mcp:backlinks:write.

Parameter: projectId, mode, targetUrl, anchorText; confirmed=true zum Anwenden.

get_ai_visibility

Liest die KI-Sichtbarkeit eines Projekts: verfolgte Prompts, Score, Ergebnisse je Prompt und je KI-Engine (zitiert, erwähnt, Rang, Auszug), Messzeiträume und optional der Wettbewerbervergleich. Gibt nie den vollständigen Antworttext zurück und löst keine Messung aus.

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

manage_ai_visibility_promptsSchreiben · mcp:ai-visibility:write

Zeigt das Hinzufügen, Entfernen oder Umformulieren verfolgter Prompts in der Vorschau und wendet es dann an. Ein umformulierter Prompt beginnt ohne Verlauf. Löst keine Messung aus: neue Prompts werden bei der nächsten Messung erfasst. Anwenden erfordert mcp:ai-visibility:write.

Parameter: projectId, mode, operation (add mit prompts, remove mit prompts oder rename mit from und to); confirmed=true zum Anwenden.

OAuth-Verbindung

MCP-Clients wie Claude oder ChatGPT verbinden sich per OAuth: Geben Sie ihnen den Endpunkt, den Rest entdecken sie über die folgenden Metadaten.

Ressourcen-Metadatenhttps://ai.pushrank.io/.well-known/oauth-protected-resource/mcp
Autorisierungsserverhttps://app.pushrank.io/.well-known/oauth-authorization-server
  1. Erkennung — ein nicht authentifizierter Aufruf des Endpunkts liefert 401 mit einem WWW-Authenticate-Header, der auf die Ressourcen-Metadaten verweist; diese nennen den Autorisierungsserver und die unterstützten Scopes.
  2. Registrierung — der Client registriert sich per dynamischer Client-Registrierung (registration_endpoint) als öffentlicher Client, ohne Secret.
  3. Autorisierung — Authorization-Code-Flow mit PKCE (S256) und dem Parameter resource gleich dem MCP-Endpunkt; der Nutzer meldet sich bei Pushrank an und bestätigt die angeforderten Scopes.
  4. Tokens — der token_endpoint liefert ein Zugriffstoken mit 1 h Gültigkeit und, wenn offline_access angefordert wird, ein Refresh-Token mit 30 Tagen. Senden Sie das Zugriffstoken als Authorization: Bearer.

Manuelle API-Nutzung

Rufen Sie für ein Skript oder einen Client ohne OAuth den JSON-RPC-2.0-Endpunkt mit einem Bearer-Token auf, das im Tab „API / manuell“ erstellt wurde.

Endpunkthttps://ai.pushrank.io/mcp

Erforderliche Header

  • Authorization: Bearer <token> — bei jeder Anfrage erforderlich.
  • Content-Type: application/json.
  • Accept: application/json, text/event-stream.
  • mcp-session-id — wird in den Antwort-Headern von initialize zurückgegeben; bei jedem weiteren Aufruf mitsenden.
  • mcp-protocol-version: 2025-06-18 bei den Aufrufen nach initialize.

Aufrufreihenfolge

1. initialize — öffnet eine Sitzung. Lesen Sie den Antwort-Header mcp-session-id aus (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 — listet die verfügbaren Tools und ihre Eingabeschemas auf.

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 — führt ein Tool mit seinen Argumenten aus.

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}}}'
Der Server ist zustandsbehaftet: Ohne gültigen Header mcp-session-id gibt jeder Aufruf nach initialize „Session not found“ (404) zurück.

Scopes, Limits und Widerruf

MCP-Tokens sind eigenständig und unabhängig von Ihrer Sitzung.

Manuelles Token

Ein manuelles Token hat standardmäßig die Scopes mcp:projects:read und mcp:actions:read. Es läuft nie ab und kann jederzeit widerrufen werden.

Schreibaktionen

Status- und Planungsänderungen erfordern mcp:actions:write. Die Generierung nutzt mcp:articles:generate, die Veröffentlichung mcp:articles:publish, die Artikelbearbeitung mcp:articles:write, Keyword-Änderungen mcp:keywords:write, die erneute Analyse mcp:analysis:run, der redaktionelle Kontext mcp:editorial:write, Änderungen der CMS-Verbindung mcp:integrations:write, die Anforderung des Willkommens-Backlinks mcp:backlinks:write und die verfolgten Prompts der KI-Sichtbarkeit mcp:ai-visibility:write. Änderungen der Artikelplanung nutzen mcp:articles:generate, „Ohne Prüfung veröffentlichen“ mcp:articles:publish. Diese eigenen Scopes werden über OAuth gewährt oder bei einem manuellen Schlüssel angehakt, bei der Erstellung oder später. Ein Token ohne den erforderlichen Scope erhält insufficientScope.

OAuth-Gültigkeitsdauer

Für OAuth-Clients (Claude, ChatGPT…) gilt das Access-Token 1 h und das Refresh-Token 30 Tage.

Widerruf

Widerrufen Sie ein manuelles Token im Tab „API / manuell“. Der Widerruf wirkt sofort und betrifft Ihre Sitzung nicht; OAuth-Zugriff wird im verbundenen Client widerrufen.

Organisationsbereich

Der Server beschränkt jede Antwort auf die Projekte der Organisationen, denen Sie angehören.