Early Access

Documentazione API e MCP

Cosa espone il server MCP di Pushrank e come chiamarlo manualmente tramite l'API.

Strumenti esposti

Il server MCP di Pushrank espone 49 strumenti. Tutte le risposte sono limitate ai progetti della Sua organizzazione; le 26 azioni di scrittura sono indicate qui sotto. Sono accettati solo i parametri elencati: un parametro non dichiarato viene rifiutato con un errore che ne indica la chiave, mai ignorato in silenzio.

whoami

Mostra l'utente autenticato, le organizzazioni accessibili, gli scope concessi, i saldi dei crediti e i link utili di Pushrank.

Parametri: Nessuno. Sola lettura, senza scope aggiuntivi.

list_projects

Elenca i progetti Pushrank accessibili all'utente autenticato.

Parametri: limit (1–50, predefinito 25).

get_project_overview

Panoramica sintetica di un progetto: traffico, riepilogo del digest e conteggi per stato.

Parametri: projectId.

get_seo_forecast

Previsione SEO di un progetto, in sola lettura: la stima di Pushrank (cursore nella posizione predefinita) con curva, M6, M12, totale cumulato, costo, soglia, copertura, riferimento del consulente, ipotesi e provenienza, oppure il motivo per cui non è disponibile. Stesso livello di dettaglio dell'app per l'account. Un'ipotesi, non una garanzia.

Parametri: projectId.

list_seo_opportunities

Recupera automaticamente l'elenco completo delle azioni SEO corrispondenti alla Sua richiesta, attive per impostazione predefinita, e guida l'assistente a presentarle in una tabella. Ambito e stati del ciclo di vita corrispondono alla schermata Azioni; la risposta spiega anche le azioni nascoste in quella schermata.

Parametri: projectId; facoltativi: status (active predefinito | todo | in_progress | done | verified | still_present | ignored | all), type, severity, priority, source, query, pageUrl, priorityMin. pagination=all per impostazione predefinita; pagination=page abilita l'accesso tecnico pagina per pagina con page (predefinito 1) e pageSize (predefinito 10, massimo 25).

update_seo_opportunity_statusScrittura · mcp:actions:write

Aggiorna lo stato di una o più opportunità SEO (fino a 50 per chiamata) e restituisce un risultato per opportunità: applicato, già in quello stato o rifiutato con il motivo. Richiede lo scope mcp:actions:write.

Parametri: projectId, status; opportunityId per un'opportunità, oppure opportunityIds (da 1 a 50) per un lotto.

get_gsc_digest

Restituisce l'ultimo digest GSC completato e lo stato dell'ultimo tentativo; non genera un nuovo digest.

Parametri: projectId; kind (dashboard_digest | weekly_gsc | monthly_gsc, predefinito dashboard_digest).

get_gsc_snapshot

Legge solo gli snapshot conservati di Google Search Console; non chiama mai GSC in tempo reale.

Parametri: projectId, dimension (date | page | query | query_page | page_date); facoltativi: period, compareTo (stessa durata), pageUrl, offset, limit (max 50).

list_articles

Elenca gli articoli con punteggi, stato di qualità e metadati di pubblicazione, senza il contenuto completo.

Parametri: projectId; facoltativi: status, search, limit (max 25).

get_article

Restituisce un articolo completo: contenuto, meta, report di qualità, log di pubblicazione, keyword collegate, opportunità ed esecuzioni dell'agente.

Parametri: projectId, articleId.

get_article_generation_readiness

Verifica quota, completezza del brief, cannibalizzazione e avvisi SERP prima della generazione, senza creare nulla.

Parametri: projectId, keyword, intent, articleType; facoltativi: niche, languageCode.

generate_articleScrittura · mcp:articles:generate

Avvia il normale workflow di generazione dell'articolo con quote e controlli di sicurezza. Richiede mcp:articles:generate.

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

get_workflow_status

Legge l'avanzamento di una generazione di articolo o di una pubblicazione sul CMS.

Parametri: projectId ed esattamente uno tra requestId e articleId; facoltativo: publicationJobId.

get_article_publication_readiness

Verifica contenuto, qualità, connessione al CMS, funzionalità e provenienza dell'articolo prima della pubblicazione.

Parametri: projectId, articleId.

publish_article_to_cmsScrittura · mcp:articles:publish

Pubblica o aggiorna effettivamente l'articolo nel CMS connesso. Richiede mcp:articles:publish.

Parametri: projectId, articleId, idempotencyKey (UUID), confirmed=true; facoltativo: acknowledgeQualityOverride.

list_content_plan

Restituisce il piano editoriale corrente e lo stato di ogni argomento pianificato.

Parametri: projectId.

generate_article_from_plan_itemScrittura · mcp:articles:generate

Avvia il normale workflow di generazione da un elemento del piano dopo conferma. Richiede mcp:articles:generate.

Parametri: projectId, itemId, confirmed=true; facoltativo: acknowledgeWarnings.

edit_articleScrittura · mcp:articles:write

Visualizza in anteprima e poi applica le modifiche all'articolo con controlli di versione ottimistici. L'applicazione richiede mcp:articles:write.

Parametri: projectId, articleId, mode, expectedUpdatedAt, changes (title, slug, content, metaDescription, faqData, ctaData, robotsConfig{index, follow, noSnippet, noArchive}, featuredImageAlt); confirmed=true per applicare. Un ctaData con html "" o blocks [] resta senza CTA, anche con un URL; una CTA senza URL valido non viene visualizzata.

get_article_performance

Legge le prestazioni GSC conservate della pagina pubblicata senza chiamare Google in tempo reale.

Parametri: projectId, articleId.

add_keywordsScrittura · mcp:keywords:write

Visualizza in anteprima e poi aggiunge fino a 100 keyword alla strategia. Le nuove keyword vengono arricchite (volume, difficoltà, SERP, intento) come un'aggiunta dalla dashboard, senza costo in crediti, con un piano attivo. Una keyword rimossa in precedenza viene ripristinata. L'applicazione richiede mcp:keywords:write.

Parametri: projectId, mode, terms[], locale, intent; confirmed=true e idempotencyKey per applicare.

update_keywordScrittura · mcp:keywords:write

Visualizza in anteprima e poi sovrascrive l'intento, lo stato o il punteggio di priorità di una keyword. L'applicazione richiede mcp:keywords:write.

Parametri: projectId, mode, keywordId, changes (intent, status, priorityScore); confirmed=true e idempotencyKey per applicare.

set_keyword_statusesScrittura · mcp:keywords:write

Visualizza in anteprima e poi imposta uno stato su un massimo di 100 keyword. L'applicazione richiede mcp:keywords:write.

Parametri: projectId, mode, keywordIds[], status; confirmed=true e idempotencyKey per applicare.

get_page_reanalysis_readiness

Verifica l'URL, la pagina nota, i lavori duplicati e i crediti prima di rieseguire l'analisi.

Parametri: projectId, pageUrl.

reanalyze_pageScrittura · mcp:analysis:run

Riesegue la normale analisi SEO di una pagina, a consumo di crediti. Richiede mcp:analysis:run.

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

get_editorial_context

Legge il contesto editoriale strutturato senza esporre i documenti RAG interni.

Parametri: projectId.

edit_editorial_contextScrittura · mcp:editorial:write

Visualizza in anteprima e poi applica il contesto editoriale strutturato con controlli di versione. L'applicazione richiede mcp:editorial:write.

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

get_business_profile

Legge il profilo aziendale completo: ogni dato con stato, provenienza e decisione, livello di completezza, campi principali mancanti e modalità legacy.

Parametri: projectId.

declare_business_factScrittura · mcp:editorial:write

Visualizza in anteprima e poi dichiara un dato nel profilo aziendale (offerta, pubblico, mercato, obiettivo, regola, vincolo, stagionalità o termine). Se l'indirizzo è già compilato, il suo valore viene sostituito. L'applicazione richiede mcp:editorial:write.

Parametri: projectId, mode, expectedRevision, idempotencyKey, address, value; confirmed=true per applicare.

replace_business_factScrittura · mcp:editorial:write

Visualizza in anteprima e poi sovrascrive il valore di un dato aziendale. L'applicazione richiede mcp:editorial:write.

Parametri: projectId, mode, expectedRevision, idempotencyKey, factId, value; confirmed=true per applicare.

confirm_business_factScrittura · mcp:editorial:write

Visualizza in anteprima e poi conferma un dato aziendale proposto. L'applicazione richiede mcp:editorial:write.

Parametri: projectId, mode, expectedRevision, idempotencyKey, factId; confirmed=true per applicare.

reject_business_factScrittura · mcp:editorial:write

Visualizzi l'anteprima, poi rifiuti un fatto aziendale proposto o confermato; potrà essere ripristinato in seguito. L'applicazione richiede mcp:editorial:write.

Parametri: projectId, mode, expectedRevision, idempotencyKey, factId, reason; confirmed=true per applicare.

withdraw_business_factScrittura · mcp:editorial:write

Visualizzi l'anteprima, poi elimini definitivamente un fatto aziendale; non potrà essere ripristinato. L'applicazione richiede mcp:editorial:write.

Parametri: projectId, mode, expectedRevision, idempotencyKey, factId, reason; confirmed=true per applicare.

restore_business_factScrittura · mcp:editorial:write

Visualizzi l'anteprima, poi riporti un fatto aziendale rifiutato allo stato proposto. L'applicazione richiede mcp:editorial:write.

Parametri: projectId, mode, expectedRevision, idempotencyKey, factId; confirmed=true per applicare.

reorder_business_offersScrittura · mcp:editorial:write

Visualizzi l'anteprima, poi sostituisca l'ordine delle offerte. L'applicazione richiede mcp:editorial:write.

Parametri: projectId, mode, expectedRevision, idempotencyKey, offerIds[]; confirmed=true per applicare.

adopt_business_profileScrittura · mcp:editorial:write

Solo in modalità legacy: visualizzi l'anteprima, poi confermi il profilo recuperato dai dati esistenti, rifiutando i fatti errati e dichiarando i campi principali mancanti nella stessa modifica. Non è reversibile. L'applicazione richiede mcp:editorial:write.

Parametri: projectId, mode, expectedRevision, idempotencyKey, rejectFactIds[], missingFacts[]{address, value}; confirmed=true per applicare.

retry_project_contextScrittura · mcp:editorial:write

Rilanci la ricostruzione del contesto del progetto dopo un errore (projectContext.retry = available in get_article_generation_readiness), come il pulsante nelle impostazioni. Visualizzi l'anteprima dello stato, poi rimetta in coda; una chiamata ripetuta restituisce la ricostruzione già in coda; dopo un nuovo errore, ogni applicazione è un nuovo tentativo. L'applicazione richiede mcp:editorial:write.

Parametri: projectId, mode; confirmed=true per applicare.

get_cms_config

Legga il tipo di CMS, lo stato della connessione, la data dell'ultimo test e le impostazioni non segrete. I segreti non vengono mai restituiti, solo se ciascuno è memorizzato.

Parametri: projectId.

configure_cmsScrittura · mcp:integrations:write

Visualizzi l'anteprima, poi salvi e testi le impostazioni non segrete di una connessione WordPress, Webflow, Wix, Framer (se attivo) o webhook personalizzato esistente. Le credenziali si inseriscono solo nella dashboard PushRank e restano invariate. Shopify resta nella dashboard. L'applicazione richiede mcp:integrations:write e il ruolo di proprietario.

Parametri: projectId, mode, cmsType; per tipo: wpUrl, wpUsername | webflowCollectionId | wixSiteId, wixMemberId | framerProjectId, framerCollectionId, framerFieldMapping (Framer, se attivo) | webhookUrl; confirmed=true e idempotencyKey per applicare.

get_publishing_schedule

Legga la pianificazione degli articoli impostata nella scheda Argomenti: attiva/disattiva, giorni, ora, fuso orario e Pubblica senza revisione, il prossimo articolo pianificato e ciò che la quota di articoli consente fino al rinnovo.

Parametri: projectId.

update_publishing_scheduleScrittura · mcp:articles:generate, mcp:articles:publish

Visualizzi l'anteprima, poi applichi una modifica alla pianificazione degli articoli, con le stesse regole della scheda Argomenti. L'applicazione richiede mcp:articles:generate per modificare attivazione, giorni, ora o fuso orario, e mcp:articles:publish per modificare Pubblica senza revisione.

Parametri: projectId, mode; facoltativi enabled, publishDays (da 0 a 7 giorni tra mon…sun), publishHour (0–23), timezone (Europe/Paris, Europe/London, America/New_York, America/Los_Angeles, Asia/Tokyo), autoPublish; confirmed=true e idempotencyKey per applicare.

update_article_statusScrittura · mcp:actions:write

Aggiorni lo stato di pubblicazione salvato di un articolo e registri la provenienza MCP. Richiede lo scope mcp:actions:write.

Parametri: projectId, articleId, status (draft | published); facoltativi: cmsUrl (solo HTTPS), publishedAt (ISO 8601, solo published; predefinito: adesso). La programmazione non è supportata perché questo strumento non ha un timestamp di programmazione.

schedule_article_publicationScrittura · mcp:actions:write

Programmi una pubblicazione futura di un articolo con il controllo qualità e la protezione dalla concorrenza esistenti. Richiede lo scope mcp:actions:write.

Parametri: projectId, articleId, scheduledAt (timestamp ISO 8601 futuro con offset esplicito).

cancel_article_publication_scheduleScrittura · mcp:actions:write

Annulli una programmazione di pubblicazione in attesa. Viene rifiutato una volta che il worker di pubblicazione l'ha presa in carico. Richiede lo scope mcp:actions:write.

Parametri: projectId, articleId.

list_keywords

Elenchi le parole chiave arricchite con metriche, stato, priorità, copertura degli articoli e intento canonico.

Parametri: projectId; facoltativi: intent, source, status, search, limit (max 25), offset (paginazione con pagination.nextOffset).

get_keyword_metrics

Restituisce le metriche già memorizzate per un massimo di 20 termini; non chiama mai un provider né avvia un aggiornamento.

Parametri: projectId, terms (1–20); facoltativi: locale (predefinito fr), locationCode (predefinito 2250).

get_onboarding_checklist

Mostra i cinque passaggi iniziali di un progetto, ciò che resta da fare, il link alla dashboard per ogni passaggio e lo stato del backlink di benvenuto. I client che supportano le MCP Apps lo visualizzano come checklist interattiva.

Parametri: projectId.

claim_welcome_giftScrittura · mcp:backlinks:write

Visualizzi l'anteprima, poi richieda il backlink offerto una volta completati i cinque passaggi: una pagina del sito del progetto e il relativo testo di ancoraggio. Solo per il proprietario, con una prova o un piano attivo; uno per organizzazione. Durante la prova il backlink è solo riservato: viene ordinato alla fine della prova, con il primo mese a pagamento. L'applicazione richiede mcp:backlinks:write.

Parametri: projectId, mode, targetUrl, anchorText; confirmed=true per applicare.

get_ai_visibility

Legge la Visibilità IA di un progetto: prompt monitorati, punteggio, risultati per prompt e per motore IA (citato, menzionato, posizione, estratto), periodi di rilevazione e, facoltativamente, il confronto con i concorrenti. Non restituisce mai il testo completo delle risposte e non avvia alcuna misurazione.

Parametri: projectId; facoltativi: collectionId, prompt, provider, offset, limit (1–25, predefinito 15), includeCompetitors.

manage_ai_visibility_promptsScrittura · mcp:ai-visibility:write

Mostra in anteprima e poi applica l'aggiunta, la rimozione o la riformulazione dei prompt monitorati. Un prompt riformulato riparte senza storico. Non avvia alcuna misurazione: i nuovi prompt vengono misurati alla rilevazione successiva. L'applicazione richiede mcp:ai-visibility:write.

Parametri: projectId, mode, operation (add con prompts, remove con prompts o rename con from e to); confirmed=true per applicare.

Connessione OAuth

I client MCP come Claude o ChatGPT si collegano tramite OAuth: fornisci l'endpoint e scopriranno il resto dai metadati qui sotto.

Metadati della risorsahttps://ai.pushrank.io/.well-known/oauth-protected-resource/mcp
Server di autorizzazionehttps://app.pushrank.io/.well-known/oauth-authorization-server
  1. Rilevamento — una chiamata non autenticata all'endpoint restituisce 401 con un'intestazione WWW-Authenticate che punta ai metadati della risorsa, i quali indicano il server di autorizzazione e gli scope supportati.
  2. Registrazione — il client si registra tramite registrazione dinamica (registration_endpoint) come client pubblico, senza segreto.
  3. Autorizzazione — flusso authorization code con PKCE (S256) e il parametro resource uguale all'endpoint MCP; l'utente accede a Pushrank e approva gli scope richiesti.
  4. Token — il token_endpoint restituisce un token di accesso valido 1 h e, se viene richiesto offline_access, un token di aggiornamento di 30 giorni. Invia il token di accesso come Authorization: Bearer.

Uso manuale dell'API

Per uno script o un client senza OAuth, chiami l'endpoint JSON-RPC 2.0 con un token bearer creato dalla scheda "API / manuale".

Endpointhttps://ai.pushrank.io/mcp

Header obbligatori

  • Authorization: Bearer <token> — obbligatorio in ogni richiesta.
  • Content-Type: application/json.
  • Accept: application/json, text/event-stream.
  • mcp-session-id — restituito negli header della risposta di initialize; lo ripeta in ogni chiamata successiva.
  • mcp-protocol-version: 2025-06-18 nelle chiamate successive a initialize.

Sequenza delle chiamate

1. initialize — apre una sessione. Legga l'header di risposta mcp-session-id (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 — elenca gli strumenti disponibili e i relativi schemi di input.

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 — esegue uno strumento con i suoi argomenti.

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}}}'
Il server è stateful: senza un header mcp-session-id valido, qualsiasi chiamata dopo initialize restituisce "Session not found" (404).

Scope, limiti e revoca

I token MCP sono dedicati e indipendenti dalla Sua sessione.

Token manuale

Un token manuale include per impostazione predefinita gli scope mcp:projects:read e mcp:actions:read. Non scade mai e può essere revocato in qualsiasi momento.

Azioni di scrittura

Gli aggiornamenti di stato e di programmazione richiedono mcp:actions:write. La generazione usa mcp:articles:generate, la pubblicazione mcp:articles:publish, la modifica degli articoli mcp:articles:write, le modifiche alle parole chiave mcp:keywords:write, la rianalisi mcp:analysis:run, il contesto editoriale mcp:editorial:write, le modifiche alla connessione CMS mcp:integrations:write, la richiesta del backlink di benvenuto mcp:backlinks:write e i prompt monitorati di Visibilità IA mcp:ai-visibility:write. Le modifiche alla pianificazione degli articoli usano mcp:articles:generate, e Pubblica senza revisione mcp:articles:publish. Questi scope dedicati vengono concessi tramite OAuth, oppure selezionati su una chiave manuale, alla creazione o in seguito. Un token senza lo scope richiesto riceve insufficientScope.

Durata OAuth

Per i client OAuth (Claude, ChatGPT…), l'access token dura 1 h e il refresh token 30 giorni.

Revoca

Revochi un token manuale dalla scheda "API / manuale". La revoca è immediata e non influisce sulla Sua sessione; l'accesso OAuth si revoca dal client connesso.

Ambito dell'organizzazione

Il server limita ogni risposta ai progetti delle organizzazioni di cui fa parte.