---
title: "Riferimento degli strumenti | PostNext"
description: "Ogni strumento offerto dal server MCP di PostNext, con input, forma della risposta e un esempio da copiare e incollare."
url: "https://postnext.io/it-it/mcp/docs"
language: "it-IT"
---

# Riferimento degli strumenti

Human version: [https://postnext.io/it-it/mcp/docs](https://postnext.io/it-it/mcp/docs)

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

[Collega PostNext](https://postnext.io/it-it/mcp/connect)

URL del server MCP `https://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

`limit` number ·facoltativo · default 20

Numero massimo di risultati (1-100, predefinito 20).

`from` string (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

`limit` number ·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_health` Piano a pagamento

Ottieni un riepilogo dello stato di tutte le piattaforme collegate.

#### Argomenti

`platform` enum ·facoltativo

Piattaforma social: twitter, instagram, linkedin, threads o tiktok.

`windowDays`7 | 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

`platform` enum ·obbligatorio

Piattaforma social: twitter, instagram, linkedin, threads o tiktok.

`content` string ·obbligatorio

Testo del post (1-2200 caratteri).

`channelName` string ·facoltativo

Quale account collegato, quando la piattaforma ne ha più di uno.

`providerId` string ·facoltativo

Il providerId dell'account da list\_connected\_accounts. Resta uguale quando l'handle cambia, quindi passalo insieme a channelName o al suo posto.

`mediaUrls` array<string> ·facoltativo

Fino a 10 URL di immagini o video.

`clientRequestId` string ·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

`postId` string ·obbligatorio

Id del post PostNext da una chiamata di elenco.

`content` string ·facoltativo

Testo del post (1-2200 caratteri).

`mediaUrls` array<string> ·facoltativo

Fino a 10 URL di immagini o video.

`clientRequestId` string ·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

`platform` enum ·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

`postId` string ·obbligatorio

Id del post PostNext da una chiamata di elenco.

`scheduledAt` string (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

`postId` string ·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

`postId` string ·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

`postId` string ·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

`query` string ·obbligatorio

Sottostringa da cercare (3-200 caratteri; i metacaratteri delle regex vengono neutralizzati).

`status` enum ·facoltativo

Facoltativo: DRAFT | SCHEDULED | PUBLISHED | FAILED | CANCELLED.

`platform` enum ·facoltativo

Piattaforma social: twitter, instagram, linkedin, threads o tiktok.

`limit` number ·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

`teamId` string ·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](https://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.

[Apri in Claude Desktop](https://postnext.io/it-it/mcp/connect)
