Strumenti MCP — Panoramica

Diritti di accesso

Gli strumenti MCP sono assegnati a tre livelli di ambito:

Ambito	Significato
`read`	Solo accesso in lettura; nessuna possibilità di creare, modificare o eliminare
`write`	Lettura e scrittura di sorgenti, canali, Inbox; nessun accesso alle impostazioni del team
`admin`	Accesso completo a MCP, comprese le impostazioni del team

Nelle connessioni OAuth, l’ambito selezionato durante l’autorizzazione limita gli strumenti accessibili. Nei token API, il ruolo del token determina il livello massimo di accesso.

Selezione del Workspace

Il server MCP si trova all’indirizzo https://picasi.app/mcp, senza Workspace nell’indirizzo.

Autenticazione	Workspace
Token API	fisso, il Workspace del token; nessun parametro necessario
OAuth	tutti i Workspaces dell’account; ogni chiamata richiede `workspace_id`

Con OAuth, list_workspaces restituisce i valori possibili. Senza workspace_id la chiamata viene rifiutata.

Strumenti di lettura

Tutti gli strumenti di lettura richiedono almeno l’ambito read.

`search_updates`

Cerca negli Updates in base a parole chiave, fonti, tag e periodo di tempo.

Ambito richiesto: read

Parametro	Tipo	Descrizione
`query`	Stringa	Termine di ricerca full-text (facoltativo)
`source_id`	Stringa	Updates di una determinata fonte (facoltativo)
`tags`	Array	Tag dei temi in base ai quali filtrare (facoltativo)
`folder`	Stringa	`inbox`, `saved` o `dropped` (facoltativo)
`source_ownership`	Stringa	`all` (impostazione predefinita), `own` (solo fonti proprie) o `competitor` (solo fonti esterne)
`limit`	Intero	Numero di risultati (predefinito: 20, max: 100)

Il filtro source_ownership utilizza il campo is_own presente nella fonte. È l’equivalente del filtro di proprietà nell’interfaccia utente dell’Inbox e consente all’assistente IA di considerare in modo mirato solo la propria presenza o solo quella dei concorrenti.

`get_update_details`

Restituisce il contenuto completo di un singolo Update.

Ambito richiesto: read

Parametro	Tipo	Descrizione
`update_id`	Stringa	ID dell’Update

`list_sources`

Elenca tutte le fonti del Workspace.

Ambito richiesto: read

Parametro	Tipo	Descrizione
`is_own`	Booleano	`true` = solo fonti proprie, `false` = solo concorrenti, omesso = tutte

Ogni fonte restituita contiene il campo is_own, in modo che gli assistenti IA possano distinguere la propria presenza da quella dei concorrenti senza dover effettuare una seconda richiesta.

A ogni canale si aggiungono tre campi da tenere distinti:

Campo	Significato
`monitoring_active`	L’interruttore del canale: acceso o spento. Non è uno stato di salute.
`state`	Lo stato del recupero: `healthy`, `degraded`, `broken`, `quarantined` o `paused`. I canali e-mail non vengono recuperati ma ricevono; segnalano `receiving`, `stale` o `waiting`. `null` significa che non c’è ancora un recupero collegato.
`last_checked`	L’ultimo tentativo di recupero, per i canali e-mail l’ultimo messaggio ricevuto.

Per la diagnosi completa di un singolo canale è competente get_channel_status.

`list_reports`

Elenca i report disponibili.

Ambito richiesto: read

Parametro	Tipo	Descrizione
`type`	Stringa	`summary`, `feedback`, `list`, `linkedin_post`, `conversation_starters` (opzionale)
`limit`	Intero	Numero (predefinito: 10)

`get_report`

Restituisce il contenuto completo di un report.

Ambito richiesto: read

Parametro	Tipo	Descrizione
`report_id`	Stringa	ID del report

`get_team_context`

Restituisce il contesto IA del Workspace: metadati del team (nome, lingua, fuso orario), URL del sito web, documenti di contesto e configurazione della proprietà.

Ambito richiesto: read

Nessun parametro obbligatorio.

La risposta contiene nel blocco context:

website_url – URL dell’organizzazione memorizzato
is_own_sources_configured – true, non appena almeno una fonte è contrassegnata come propria
own_sources_count – numero di fonti proprie

Gli assistenti IA devono proporre confronti Voice Share o Momentum solo se is_own_sources_configured è uguale a true — altrimenti manca la base di confronto.

`list_tags`

Elenca tutti i tag del Workspace.

Ambito richiesto: read

Parametro	Tipo	Descrizione
`type`	Stringa	`sources`, `channels`, `updates` (opzionale)

`get_update_statistics`

Conta gli Updates invece di elencarli. Accetta gli stessi filtri di search_updates e non ha il limite di 100 risultati.

Ambito richiesto: read

Parametro	Tipo	Descrizione
`group_by`	Stringa	`source` (predefinito), `source_tag`, `update_tag`, `day`, `week`, `month`, `quarter`
`compare_previous_period`	Booleano	Conta anche il periodo precedente di pari durata e indica la differenza
`query`	Stringa	Termine di ricerca full text (facoltativo)
`source_id`	Stringa	Limitare a una fonte (facoltativo)
`source_tags`	Array	Tag delle fonti (facoltativo)
`update_tags`	Array	Tag tematici (facoltativo)
`source_ownership`	Stringa	`all` (predefinito), `own` o `competitor`
`platform`	Stringa	Limitare a una piattaforma, ad es. `linkedin` (facoltativo)
`folder`	Array	`inbox`, `saved`; per impostazione predefinita entrambi
`days`	Intero	Periodo in giorni, da 1 a 365 (predefinito: 30)
`date_from`, `date_to`	Stringa	Periodo come data, al posto di `days`

Non è possibile raggruppare per piattaforma. Gli Updates scartati e quelli in Overflow non vengono contati.

`get_channel_status`

Restituisce lo stato di un canale: ultimo recupero, ultimo esito positivo, ultimo errore, numero di errori consecutivi, prossimo tentativo previsto e numero di Updates provenienti da quel canale.

Ambito richiesto: read

Parametro	Tipo	Descrizione
`channel_id`	Stringa	ID del canale, da `list_sources` con `include_channels=true`

`discover_channels`

Esamina un sito web e segnala i canali che si potrebbero osservare. Non crea nulla.

Ambito richiesto: read

Parametro	Tipo	Descrizione
`url`	Stringa	Sito web da esaminare (facoltativo se `source_id` è impostato)
`source_id`	Stringa	Usa il sito web di questa fonte e segna i canali che ha già

`list_workspaces`

Elenca i Workspaces dell’account autenticato con workspace_id, nome e ruolo.

Ambito richiesto: nessuno; lo strumento è aperto a ogni connessione

Senza parametri.

Strumenti per i report

`create_report`

Crea un report dagli Updates che corrispondono a un filtro. I filtri sono gli stessi di search_updates.

La generazione avviene in background: la chiamata restituisce subito un request_id. get_report_status indica a che punto è, get_report legge il report finito.

Ambito richiesto: read

Parametro	Tipo	Descrizione
`type`	Stringa	Obbligatorio. `summary`, `feedback`, `list` o `conversation_starters`
`title`	Stringa	Nome del report (facoltativo)
`instructions`	Stringa	Focus per l’IA (facoltativo)
`language`	Stringa	Codice lingua, ad es. `de`; per impostazione predefinita la lingua del Workspace
`query`	Stringa	Termine di ricerca full text (facoltativo)
`source_ids`	Array	Limitare a queste fonti (facoltativo)
`source_tags`	Array	Tag delle fonti (facoltativo)
`source_tags_mode`	Stringa	`AND` o `OR`
`update_tags`	Array	Tag tematici (facoltativo)
`update_tags_mode`	Stringa	`AND` o `OR`
`source_ownership`	Stringa	`all`, `own` o `competitor`
`platform`	Stringa	Limitare a una piattaforma (facoltativo)
`folder`	Array	Cartelle della base dati; per impostazione predefinita `inbox` e `saved`
`days`	Intero	Periodo in giorni, da 1 a 365 (predefinito: 30)
`date_from`, `date_to`	Stringa	Periodo come data, al posto di `days`

`get_report_status`

Restituisce lo stato di un report commissionato con create_report.

Ambito richiesto: read

Parametro	Tipo	Descrizione
`request_id`	Stringa	Il `request_id` restituito da `create_report`

Stato	Significato
`queued`	in attesa nella coda
`running`	in fase di generazione
`ready`	pronto; leggilo con `get_report` e il `report_id`
`empty`	concluso, ma nessun Update corrispondeva ai filtri
`failed`	interrotto; il motivo è nella risposta

Strumenti di scrittura

Tutti gli strumenti di scrittura richiedono almeno l’ambito write.

`create_source`

Crea una nuova fonte.

Scope richiesto: write

Parametro	Tipo	Descrizione
`url`	Stringa	URL del sito web della fonte
`name`	Stringa	Nome interno
`tags`	Array	ID dei tag (opzionale)

`update_source`

Modifica il nome, l’URL o i tag di una fonte esistente.

Ambito richiesto: write

Parametro	Tipo	Descrizione
`source_id`	Stringa	ID della fonte
`name`	Stringa	Nuovo nome (facoltativo)
`url`	Stringa	Nuovo URL (facoltativo)

`delete_source`

Elimina una fonte, inclusi tutti i canali e gli Updates.

Ambito richiesto: write

Parametro	Tipo	Descrizione
`source_id`	Stringa	ID della fonte

`create_channel`

Crea manualmente un canale.

Ambito richiesto: write

Parametro	Tipo	Descrizione
`source_id`	Stringa	ID della fonte di livello superiore
`url`	Stringa	URL del canale
`name`	Stringa	Nome del canale (facoltativo)

`update_channel`

Modifica il nome o la descrizione di un canale.

Ambito richiesto: write

Parametro	Tipo	Descrizione
`channel_id`	Stringa	ID del canale
`name`	Stringa	Nuovo nome (facoltativo)

`delete_channel`

Elimina un canale.

Ambito richiesto: write

Parametro	Tipo	Descrizione
`channel_id`	Stringa	ID del canale

`toggle_channel`

Attiva o disattiva un canale.

Ambito richiesto: write

Parametro	Tipo	Descrizione
`channel_id`	Stringa	ID del canale
`active`	Booleano	`true` = attivo, `false` = inattivo

`create_tag`

Crea un nuovo tag.

Ambito richiesto: write

Parametro	Tipo	Descrizione
`name`	Stringa	Nome del tag
`type`	Stringa	`sources`, `channels` o `updates`
`description`	Stringa	Descrizione del tagging IA (facoltativa)

`update_tag`

Modifica il nome o la descrizione di un tag.

Ambito richiesto: write

Parametro	Tipo	Descrizione
`tag_id`	Stringa	ID del tag
`name`	Stringa	Nuovo nome (facoltativo)
`description`	Stringa	Nuova descrizione AI (facoltativa)

`update_update_state`

Sposta gli Updates tra le cartelle del Workspace.

Ambito richiesto: write

Parametro	Tipo	Descrizione
`update_ids`	Array	ID degli Updates, al massimo 100 per chiamata
`folder`	Stringa	`inbox`, `saved` o `dropped`

Lo stato vale per Workspace e non modifica l’Update stesso. La risposta riferisce ogni ID separatamente.

`tag_update`

Assegna agli Updates tag tematici già esistenti.

Ambito richiesto: write

Parametro	Tipo	Descrizione
`update_ids`	Array	ID degli Updates, al massimo 100 per chiamata
`tags`	Array	Tag come slug, ID o nome
`mode`	Stringa	`add` (predefinito) mantiene i tag esistenti, `replace` imposta esattamente questi

Sono ammessi solo tag con applies_to = updates; un tag di fonte viene rifiutato. Crea prima i tag mancanti con create_tag.

`untag_update`

Rimuove tag tematici dagli Updates.

Ambito richiesto: write

Parametro	Tipo	Descrizione
`update_ids`	Array	ID degli Updates, al massimo 100 per chiamata
`tags`	Array	Tag da rimuovere, come slug, ID o nome

Viene rimossa solo l’assegnazione di questo Workspace. Il tag stesso resta.

`refresh_source_channels`

Esegue di nuovo il riconoscimento dei canali per una fonte esistente.

Ambito richiesto: write

Parametro	Tipo	Descrizione
`source_id`	Stringa	ID della fonte
`create_detected`	Booleano	`false` (predefinito) si limita a segnalare, `true` crea i canali mancanti

I canali esistenti non vengono creati due volte; un canale disattivato conta come esistente. I canali nuovi iniziano il recupero da soli.

Argomenti correlati

MCP — Utilizzo di Picasi nell'assistente AI Contesto: cos’è l’MCP, i livelli di ambito OAuth e il concetto di sicurezza.

Collegare Picasi a Claude Code Creare un token API e configurarlo in Claude Code.

Collegare Picasi a Claude.ai Configurare l'autenticazione OAuth per Claude.ai.