Vai al contenuto

Riferimento degli strumenti

Ogni strumento offerto dal server MCP di PostNext, con input, forma della risposta e un esempio da copiare e incollare.

URL del server MCPhttps://mcp.postnext.io/api
POST https://mcp.postnext.io/api

Autenticazione

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.

POST https://mcp.postnext.io/api

Strumenti

list_scheduled_posts

Elenca i tuoi post programmati (in coda per la pubblicazione ma non ancora inviati).

Argomenti

limitnumber ·facoltativo · default 20
Numero massimo di risultati (1-100, predefinito 20).
fromstring (ISO 8601) ·facoltativo
Timestamp ISO; restituisce solo i post programmati da questo momento in poi.

Risposta

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

limitnumber ·facoltativo · default 20
Numero massimo di risultati (1-100, predefinito 20).

Risposta

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

platformenum ·facoltativo
Piattaforma social: twitter, instagram, linkedin, threads o tiktok.
windowDays7 | 30 | 90 ·facoltativo · default 30
Periodo da considerare in giorni: 7, 30 o 90 (predefinito 30).

Risposta

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

platformenum ·obbligatorio
Piattaforma social: twitter, instagram, linkedin, threads o tiktok.
contentstring ·obbligatorio
Testo del post (1-2200 caratteri).
channelNamestring ·facoltativo
Quale account collegato, quando la piattaforma ne ha più di uno.
providerIdstring ·facoltativo
Il providerId dell'account da list_connected_accounts. Resta uguale quando l'handle cambia, quindi passalo insieme a channelName o al suo posto.
mediaUrlsarray<string> ·facoltativo
Fino a 10 URL di immagini o video.
clientRequestIdstring ·facoltativo
Chiave di idempotenza facoltativa. La stessa chiave entro 5 minuti restituisce il risultato già salvato.

Risposta

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

postIdstring ·obbligatorio
Id del post PostNext da una chiamata di elenco.
contentstring ·facoltativo
Testo del post (1-2200 caratteri).
mediaUrlsarray<string> ·facoltativo
Fino a 10 URL di immagini o video.
clientRequestIdstring ·facoltativo
Chiave di idempotenza facoltativa. La stessa chiave entro 5 minuti restituisce il risultato già salvato.

Risposta

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

platformenum ·obbligatorio
Piattaforma social: twitter, instagram, linkedin, threads o tiktok.

Risposta

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

postIdstring ·obbligatorio
Id del post PostNext da una chiamata di elenco.
scheduledAtstring (ISO 8601) ·obbligatorio
Timestamp ISO 8601; non può essere più di 5 minuti nel passato.

Risposta

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

postIdstring ·obbligatorio
Id del post PostNext da una chiamata di elenco.

Risposta

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

postIdstring ·obbligatorio
Id del post PostNext da una chiamata di elenco.

Risposta

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

postIdstring ·obbligatorio
Id del post PostNext da una chiamata di elenco.

Risposta

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

querystring ·obbligatorio
Sottostringa da cercare (3-200 caratteri; i metacaratteri delle regex vengono neutralizzati).
statusenum ·facoltativo
Facoltativo: DRAFT | SCHEDULED | PUBLISHED | FAILED | CANCELLED.
platformenum ·facoltativo
Piattaforma social: twitter, instagram, linkedin, threads o tiktok.
limitnumber ·facoltativo · default 20
Numero massimo di risultati (1-100, predefinito 20).

Risposta

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

teamIdstring ·obbligatorio
teamId di destinazione da list_teams. L'appartenenza viene verificata di nuovo sul server.

Risposta

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 9728
  • GET /.well-known/oauth-authorization-server — RFC 8414
  • GET /oauth/.well-known/openid-configuration — OIDC
  • POST /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.