Riferimento degli strumenti
Ogni strumento offerto dal server MCP di PostNext, con input, forma della risposta e un esempio da copiare e incollare.
https://mcp.postnext.io/apiPOST https://mcp.postnext.io/apiAutenticazione
Ogni richiesta a https://mcp.postnext.io/api richiede un header Authorization con un token Bearer. Puoi ottenerlo in due modi.
OAuth (consigliato per i client AI)
Al primo collegamento i client AI eseguono la Dynamic Client Registration, poi guidano l'utente in una schermata di consenso OAuth. La pagina /mcp/connect lo fa in automatico. Il tuo client riceve un token di accesso valido 30 giorni.
Chiave API
Per script e CI, genera una chiave API personale nell'app PostNext in Account → API Keys. La chiave inizia con apikey_ e si presenta come token Bearer, come gli altri.
Endpoint
Tutte le chiamate agli strumenti vanno a un unico endpoint JSON-RPC 2.0 via HTTPS POST.
Strumenti
list_scheduled_posts
Elenca i tuoi post programmati (in coda per la pubblicazione ma non ancora inviati).
Argomenti
limitfromRisposta
Un oggetto con posts: [{id, platform, content, scheduledAt, status}]. Fino a limit risultati.
Esempio
curl -X POST https://mcp.postnext.io/api \
-H "Authorization: Bearer apikey_xxx" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/call","id":1,
"params":{"name":"list_scheduled_posts",
"arguments":{"limit":5}}}'
list_drafts
Elenca le tue bozze (non ancora programmate).
Argomenti
limitRisposta
Un oggetto con drafts: [{id, platform, content, updatedAt}]. Fino a limit risultati.
Esempio
{"jsonrpc":"2.0","method":"tools/call","id":2,
"params":{"name":"list_drafts","arguments":{"limit":10}}}
list_connected_accounts
Elenca gli account social collegati al tuo team.
Argomenti
Nessun argomento.
Risposta
Un oggetto con accounts: [{platform, handle, providerId, connected, lastSyncAt}].
Esempio
{"jsonrpc":"2.0","method":"tools/call","id":3,
"params":{"name":"list_connected_accounts","arguments":{}}}
get_account_healthPiano a pagamento
Ottieni un riepilogo dello stato di tutte le piattaforme collegate.
Argomenti
platformwindowDaysRisposta
Un oggetto con windowDays, postsScheduled, postsPublished, postsFailed, il dettaglio byPlatform e topErrors[].
Esempio
{"jsonrpc":"2.0","method":"tools/call","id":4,
"params":{"name":"get_account_health",
"arguments":{"windowDays":30}}}
create_post_draft
Crea una nuova bozza. Le bozze non vengono pubblicate in automatico.
Argomenti
platformcontentchannelNameproviderIdmediaUrlsclientRequestIdRisposta
Un oggetto con la nuova bozza: {id, platform, content, status: "DRAFT", createdAt}.
Esempio
{"jsonrpc":"2.0","method":"tools/call","id":5,
"params":{"name":"create_post_draft",
"arguments":{"platform":"twitter",
"content":"Hello from MCP"}}}
update_post_draft Piano a pagamento
Aggiorna una bozza esistente. Devi fornire almeno content o mediaUrls.
Argomenti
postIdcontentmediaUrlsclientRequestIdRisposta
Un oggetto con la bozza aggiornata: {id, platform, content, mediaUrls, status, updatedAt}.
Esempio
{"jsonrpc":"2.0","method":"tools/call","id":6,
"params":{"name":"update_post_draft",
"arguments":{"postId":"",
"content":"Updated copy"}}}
connect_channel
Genera un URL valido una volta che l'utente può aprire per autorizzare il collegamento di una nuova piattaforma.
Argomenti
platformRisposta
Un oggetto con authUrl (link valido una volta che l'utente apre per autorizzare), expiresAt e platform.
Esempio
{"jsonrpc":"2.0","method":"tools/call","id":7,
"params":{"name":"connect_channel",
"arguments":{"platform":"linkedin"}}}
schedule_post
Sposta una bozza (status DRAFT) nella coda di pubblicazione a un timestamp futuro. Idempotente con uno scarto di ±60 s; rifiuta di riprogrammare a un orario diverso senza prima annullare. Conta nei post mensili del piano (Free: 10, condivisi con l'app); un post conta una volta sola, quindi riprogrammarlo dopo un annullamento o una pubblicazione non riuscita non viene contato di nuovo.
Argomenti
postIdscheduledAtRisposta
Un oggetto con postId, scheduledAt (ISO), status: SCHEDULED.
Esempio
{"jsonrpc":"2.0","method":"tools/call","id":8,
"params":{"name":"schedule_post",
"arguments":{"postId":"",
"scheduledAt":"2026-05-10T09:00:00Z"}}}
cancel_scheduled_post
Annulla un post programmato e lo toglie dalla coda di pubblicazione. La bozza resta.
Argomenti
postIdRisposta
Un oggetto con postId e status: CANCELLED.
Esempio
{"jsonrpc":"2.0","method":"tools/call","id":9,
"params":{"name":"cancel_scheduled_post",
"arguments":{"postId":""}}}
delete_draft
Elimina definitivamente una bozza. Rifiuta i post che non sono DRAFT (per i SCHEDULED usa cancel_scheduled_post).
Argomenti
postIdRisposta
Un oggetto con postId e deleted: true.
Esempio
{"jsonrpc":"2.0","method":"tools/call","id":10,
"params":{"name":"delete_draft",
"arguments":{"postId":""}}}
get_post
Restituisce il PostGroup completo per un postId, con contenuto per piattaforma, stato e timestamp.
Argomenti
postIdRisposta
Un oggetto con postId, status, scheduledAt, createdAt, updatedAt e providers (record piattaforma → contenuto).
Esempio
{"jsonrpc":"2.0","method":"tools/call","id":11,
"params":{"name":"get_post",
"arguments":{"postId":""}}}
search_posts
Ricerca di una sottostringa (senza distinzione tra maiuscole e minuscole) nel testo dei post del team attivo. Filtri: status, platform, limit (1-100, predefinito 20).
Argomenti
querystatusplatformlimitRisposta
Un oggetto con posts: [{postId, status, platforms, snippet, scheduledAt, updatedAt}]. Snippet contiene il contesto trovato, con puntini di sospensione ai lati.
Esempio
{"jsonrpc":"2.0","method":"tools/call","id":12,
"params":{"name":"search_posts",
"arguments":{"query":"launch","limit":10}}}
list_teams
Restituisce i team di cui l'utente autenticato è proprietario o amministratore, con il team attivo segnalato.
Argomenti
Nessun argomento.
Risposta
Un oggetto con currentTeamId e teams: [{teamId, teamName, isCurrent}].
Esempio
{"jsonrpc":"2.0","method":"tools/call","id":13,
"params":{"name":"list_teams","arguments":{}}}
set_current_team
Cambia il team attivo per questo token Bearer. L'utente deve essere membro. Salvato nel documento del token OAuth; la modifica nella sessione lo rende subito effettivo per gli strumenti successivi nella stessa conversazione.
Argomenti
teamIdRisposta
Un oggetto con teamId, teamName, persisted (true con OAuth, false con chiave API) e una nota facoltativa.
Esempio
{"jsonrpc":"2.0","method":"tools/call","id":14,
"params":{"name":"set_current_team",
"arguments":{"teamId":"team_xxxxx"}}}
get_plan_limits
Legge il livello di abbonamento attuale dell'utente e le quote per livello (canali, spazio, crediti AI, pubblicazione). Disponibile con ogni piano. Utile prima degli strumenti che modificano dati, per prevedere se la chiamata verrà bloccata.
Argomenti
Nessun argomento.
Risposta
Un oggetto con tier, tierDisplayName, isPaid, isTrial, limits (channels/storage/aiCalls ognuno come {limit, current, exceeded}; posts come {limit, allowed, current}, dove current è il conteggio di questo mese, o null se non è stato possibile leggerlo) e creditsAvailable ({total, subscriptionRemaining, purchasedBalance} o null).
Esempio
{"jsonrpc":"2.0","method":"tools/call","id":15,
"params":{"name":"get_plan_limits","arguments":{}}}
get_post_metrics
Recupera le metriche di engagement di un post pubblicato su ogni piattaforma a cui è stato inviato. Twitter restituisce mi piace, retweet, risposte e impression; Instagram restituisce mi piace e commenti. LinkedIn, Threads e TikTok restituiscono solo stato di pubblicazione e URL (la raccolta dell'engagement arriverà in una versione successiva). Un totale normalizzato somma le metriche delle piattaforme che le hanno fornite.
Argomenti
postId Id del post PostNext da una chiamata di elenco.
Risposta
Un oggetto con postId, status, providers: [{platform, publishedPostId, publishedUrl, publishedAt, status, metrics}] e totals: {likes, comments, shares, impressions}. metrics è un oggetto di conteggi numerici per piattaforma, o null quando la piattaforma non raccoglie ancora l'engagement.
Esempio
{"jsonrpc":"2.0","method":"tools/call","id":16,
"params":{"name":"get_post_metrics",
"arguments":{"postId":""}}}
get_publish_status
Scopri cosa è successo a un post programmato: stato della coda, riuscita o errore per piattaforma, tempo di elaborazione e id del job del worker. Restituisce isScheduled=false per i post che esistono come bozze ma non sono mai stati messi nella coda di pubblicazione, con un suggerimento che rimanda a schedule_post.
Argomenti
postId Id del post PostNext da una chiamata di elenco.
Risposta
Un oggetto con postId, isScheduled, status, scheduledAt, publishedAt, platforms, processingTimeMs, jobId, topLevelError e results: [{platform, success, publishedPostId, publishedAt, error}]. Include hint quando isScheduled è false.
Esempio
{"jsonrpc":"2.0","method":"tools/call","id":17,
"params":{"name":"get_publish_status",
"arguments":{"postId":""}}}
update_brand_profile Piano a pagamento
Aggiorna il profilo del brand attivo dell'utente. Campi ammessi: bio, brandVoice, personalityTraits, mainThemes, expertiseAreas, preferredHashtags, audienceSize. Tutto il resto viene ignorato senza avviso. Per "attivo" usa prima il profilo predefinito del team, poi il primo profilo attivo dell'utente.
Argomenti
brandVoice Array di descrittori del tono del brand (per esempio ["professionale", "sintetico"]).
Other patchable fields: bio, personalityTraits, mainThemes, expertiseAreas, preferredHashtags, audienceSize.
Risposta
Un oggetto con profileId, name, updated: [nomi dei campi aggiornati] e i valori attuali di bio, brandVoice, personalityTraits, mainThemes, expertiseAreas, preferredHashtags, audienceSize dopo l'aggiornamento.
Esempio
{"jsonrpc":"2.0","method":"tools/call","id":18,
"params":{"name":"update_brand_profile",
"arguments":{"brandVoice":["professional","concise"]}}}
get_best_time_to_post Piano a pagamento
Consiglia le N fasce migliori (dayOfWeek, hour) per il prossimo post su una piattaforma, in base agli ultimi 90 giorni. Twitter e Instagram ordinano per engagement per post; LinkedIn, Threads e TikTok solo per frequenza di pubblicazione. Gli orari sono nel fuso IANA indicato (predefinito UTC). Richiede un piano a pagamento.
Argomenti
platform Piattaforma social: twitter, instagram, linkedin, threads o tiktok.
timezone Nome del fuso orario IANA (per esempio Europe/Rome, America/New_York). Predefinito UTC.
topN Numero di fasce consigliate da restituire (1-24, predefinito 5).
Risposta
Un oggetto con platform, timezone, sampleWindowDays, sampleSize, metricsAvailable e recommendations: [{dayOfWeek (1-7, lun=1), dayLabel, hour (0-23), score, basedOn: {posts, avgEngagement}}]. Include hint quando mancano dati o metriche.
Esempio
{"jsonrpc":"2.0","method":"tools/call","id":19,
"params":{"name":"get_best_time_to_post",
"arguments":{"platform":"twitter","timezone":"Europe/Berlin","topN":5}}}
get_channel_analytics
Risultati complessivi di un canale collegato, o di tutti i canali insieme. Restituisce impression, copertura, mi piace, commenti ed engagement rate del periodo, la variazione rispetto al periodo precedente della stessa durata e la serie dei follower. Ometti platform per il totale del team. Usa get_post_metrics per un singolo post e get_best_time_to_post per la programmazione.
Argomenti
platform Piattaforma social: twitter, instagram, linkedin, threads o tiktok.
channelName Quale account collegato, quando la piattaforma ne ha più di uno.
providerId Il providerId dell'account da list_connected_accounts. Resta uguale quando l'handle cambia, quindi passalo insieme a channelName o al suo posto.
period Periodo del report: 7d, 30d, 90d o all (predefinito 30d).
Risposta
Un oggetto con scope, period, totals, vsPrevious, coverage, dataThrough e followers, che contiene trackingSince, current, change e la serie.
Esempio
{"jsonrpc":"2.0","method":"tools/call","id":34,
"params":{"name":"get_channel_analytics",
"arguments":{"platform":"linkedin","period":"30d"}}}search_tools
Cerca nel catalogo degli strumenti MCP con testo libero, categoria o intento. Restituisce categorie, requiresScope, descrizioni di una riga e i tag di utilizzo trovati. Gratis con tutti i piani (strumento di scoperta).
Argomenti
Tutti facoltativi. Chiamalo senza argomenti per elencare tutti gli strumenti disponibili.
query Ricerca a testo libero in nomi, descrizioni e tag di utilizzo degli strumenti.
category Filtra su una categoria: posts, accounts, analytics, brand, teams, discovery, other.
Risposta
Un oggetto con totalTools, matchCount, categories: [string[]] e tools: [{name, category, requiresScope, description, useCases, matchedOn: [name|category|description|use_case]}]. Include hint quando non ci sono risultati o filtri.
Esempio
{"jsonrpc":"2.0","method":"tools/call","id":20,
"params":{"name":"search_tools",
"arguments":{"query":"why did my post fail"}}}
get_plan
Piano e date di fatturazione: livello, data di rinnovo, fine della prova e se l'abbonamento è impostato per essere disdetto a fine periodo. Per quote e utilizzo, chiama get_plan_limits.
Argomenti
Nessun argomento.
Risposta
Un oggetto con tier, tierDisplayName, isPaid, isTrial, gated, subscriptionStatus, renewsAt, trialEndsAt, cancelAtPeriodEnd e currency.
Esempio
{"jsonrpc":"2.0","method":"tools/call","id":21,
"params":{"name":"get_plan",
"arguments":{}}}
upload_asset
Caricamento in base64 di un'immagine o un video nella libreria media. Affidabile solo per file molto piccoli, circa 8 KB o meno: un payload più grande viene troncato senza avviso negli argomenti dello strumento e salva un file danneggiato. Per file più grandi usa request_asset_upload.
Argomenti
filename Nome del file con l'estensione, fino a 255 caratteri.
contentType Tipo MIME del file, dalla lista di immagini e video ammessi.
base64 I byte del file, codificati in base64. Tienilo minuscolo e leggi prima l'avviso qui sopra.
Risposta
Un oggetto con assetId, url, sizeBytes e mimeType. Passa l'url a create_post_draft come mediaUrls.
Esempio
{"jsonrpc":"2.0","method":"tools/call","id":22,
"params":{"name":"upload_asset",
"arguments":{"filename":"logo.png","contentType":"image/png","base64":"iVBORw0KGgo..."}}}
request_asset_upload
Il metodo di caricamento consigliato, per immagini e video di qualsiasi dimensione. Due passaggi: chiama questo strumento per ottenere un URL prefirmato e un comando curl pronto, poi invia con PUT i byte del file a quell'URL. La risposta al PUT contiene l'URL finale del file.
Argomenti
filename Nome del file con l'estensione, fino a 255 caratteri.
contentType Tipo MIME del file, dalla lista di immagini e video ammessi.
sizeBytes Dimensione esatta del file in byte, usata per firmare il caricamento.
Risposta
Un oggetto con uploadId, uploadUrl, uploadToken, expiresInSeconds e instructions con il comando PUT esatto.
Esempio
{"jsonrpc":"2.0","method":"tools/call","id":23,
"params":{"name":"request_asset_upload",
"arguments":{"filename":"clip.mp4","contentType":"video/mp4","sizeBytes":4194304}}}
import_chat_file
Solo ChatGPT. Salva nella libreria media le immagini e i video allegati nella chat, pronti per create_post_draft. ChatGPT passa ogni file come link temporaneo; PostNext lo scarica una volta via HTTPS e controlla dal file stesso che sia un'immagine o un video. Fino a 10 file per chiamata, 50 MB ciascuno, conteggiati nello spazio del tuo piano (10 MB in totale con Free).
Argomenti
files Compilato da ChatGPT con i file allegati nella chat: download_url e file_id, e se vuoi mime_type e file_name. Fino a 10. Gli altri client caricano con request_asset_upload.
Risposta
Un oggetto con files (assetId, url, sizeBytes, mimeType e fileName per ogni file salvato) e failed (fileName e reason per ogni file che non è stato possibile salvare). Se nessun file viene salvato, la chiamata restituisce invece l'errore del primo file.
Esempio
{"jsonrpc":"2.0","method":"tools/call","id":35,
"params":{"name":"import_chat_file",
"arguments":{"files":[{"download_url":"https://files.oaiusercontent.com/...","file_id":"file_abc123"}]}}}
Risorse MCP
Le risorse sono contesto in sola lettura che il client può recuperare con il metodo MCP resources/read. Claude le carica all'inizio della conversazione, così ha il contesto di account, team e brand senza che tu lo ripeta a ogni sessione.
postnext://account/summary
Email e handle dell'account (così Claude può confermare su quale account sta lavorando), piano, crediti AI usati / limite, numero di bozze, numero di post programmati, numero di canali collegati. Conteggi fermati a 100 ciascuno per un caricamento veloce.
postnext://channels/connected
Stessa forma del risultato di list_connected_accounts; offerto come risorsa così Claude lo carica una volta all'inizio della conversazione (senza chiamare uno strumento).
postnext://brand-profiles/active
Il profilo del brand attivo dell'utente (predefinito del team, altrimenti il primo profilo dell'utente). Restituisce solo i campi utili al modello: bio, expertiseAreas, personalityTraits, brandVoice, mainThemes, audienceSize, preferredHashtags.
postnext://teams/current
Metadati del team attuale (teamId, teamName) più il numero totalTeamsAvailable. Usalo con list_teams e set_current_team per cambiare team.
Flussi con nome
Scorciatoie del menu con la barra che coordinano più strumenti. Scegline uno e il tuo assistente AI segue un'attività in più passaggi, chiedendo conferma prima di modificare qualsiasi cosa.
/weekly-plan
Legge profilo del brand, canali collegati e post in coda, poi propone da 5 a 10 bozze distribuite dal lunedì al venerdì.
/draft-thread
Scrive un thread di 5-10 post per Twitter o Threads su un tema o un URL che indichi, con il tono del tuo brand.
/audit-queue
Scorre i post programmati dei prossimi 7 giorni e segnala doppioni, piattaforme sovraccariche e vuoti.
/channel-sweep
Confronta i canali collegati con quelli supportati e suggerisce quali collegare o aggiornare.
Endpoint di discovery e OAuth
Metadati conformi agli standard, così qualsiasi client MCP si configura da solo.
GET /.well-known/oauth-protected-resource/api— RFC 9728GET /.well-known/oauth-authorization-server— RFC 8414GET /oauth/.well-known/openid-configuration— OIDCPOST /oauth/reg— Dynamic Client Registration (RFC 7591)GET /oauth/auth— Authorize (PKCE-S256 required)POST /oauth/token— Token exchange
Open source
Ricette pronte da incollare e un riferimento per sviluppatori sono nel nostro repository pubblico di documentazione. Licenza MIT; le pull request sono benvenute. github.com/postnextio/postnext-mcp
MCP per social media per Claude, ChatGPT e qualsiasi agente AI
Il server MCP per social media di PostNext permette a Claude, ChatGPT e qualsiasi agente AI di pianificare, scrivere e programmare post. Le bozze restano nel tuo calendario finché non le programmi.