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.
whoamiMostra 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_projectsElenca i progetti Pushrank accessibili all'utente autenticato.
Parametri: limit (1–50, predefinito 25).
get_project_overviewPanoramica sintetica di un progetto: traffico, riepilogo del digest e conteggi per stato.
Parametri: projectId.
get_seo_forecastPrevisione 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_opportunitiesRecupera 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:writeAggiorna 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_digestRestituisce 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_snapshotLegge 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_articlesElenca gli articoli con punteggi, stato di qualità e metadati di pubblicazione, senza il contenuto completo.
Parametri: projectId; facoltativi: status, search, limit (max 25).
get_articleRestituisce un articolo completo: contenuto, meta, report di qualità, log di pubblicazione, keyword collegate, opportunità ed esecuzioni dell'agente.
Parametri: projectId, articleId.
get_article_generation_readinessVerifica 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:generateAvvia 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_statusLegge 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_readinessVerifica contenuto, qualità, connessione al CMS, funzionalità e provenienza dell'articolo prima della pubblicazione.
Parametri: projectId, articleId.
publish_article_to_cmsScrittura · mcp:articles:publishPubblica o aggiorna effettivamente l'articolo nel CMS connesso. Richiede mcp:articles:publish.
Parametri: projectId, articleId, idempotencyKey (UUID), confirmed=true; facoltativo: acknowledgeQualityOverride.
list_content_planRestituisce il piano editoriale corrente e lo stato di ogni argomento pianificato.
Parametri: projectId.
generate_article_from_plan_itemScrittura · mcp:articles:generateAvvia 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:writeVisualizza 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_performanceLegge le prestazioni GSC conservate della pagina pubblicata senza chiamare Google in tempo reale.
Parametri: projectId, articleId.
add_keywordsScrittura · mcp:keywords:writeVisualizza 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:writeVisualizza 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:writeVisualizza 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_readinessVerifica l'URL, la pagina nota, i lavori duplicati e i crediti prima di rieseguire l'analisi.
Parametri: projectId, pageUrl.
reanalyze_pageScrittura · mcp:analysis:runRiesegue la normale analisi SEO di una pagina, a consumo di crediti. Richiede mcp:analysis:run.
Parametri: projectId, pageUrl, idempotencyKey, confirmed=true.
get_editorial_contextLegge il contesto editoriale strutturato senza esporre i documenti RAG interni.
Parametri: projectId.
edit_editorial_contextScrittura · mcp:editorial:writeVisualizza 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_profileLegge 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:writeVisualizza 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:writeVisualizza 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:writeVisualizza 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:writeVisualizzi 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:writeVisualizzi 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:writeVisualizzi 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:writeVisualizzi 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:writeSolo 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:writeRilanci 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_configLegga 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:writeVisualizzi 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_scheduleLegga 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:publishVisualizzi 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:writeAggiorni 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:writeProgrammi 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:writeAnnulli 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_keywordsElenchi 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_metricsRestituisce 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_checklistMostra 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:writeVisualizzi 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_visibilityLegge 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:writeMostra 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.
https://ai.pushrank.io/.well-known/oauth-protected-resource/mcphttps://app.pushrank.io/.well-known/oauth-authorization-server- 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.
- Registrazione — il client si registra tramite registrazione dinamica (registration_endpoint) come client pubblico, senza segreto.
- 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.
- 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".
https://ai.pushrank.io/mcpHeader 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).
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.
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.
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}}}'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.