Agenti AI (MCP)

Disponibile con ogni piano

MCP funziona con tutti i piani. Free e Basic hanno accesso in sola lettura a tutti i 10 strumenti di lettura (Free è limitato a 100 richieste al giorno). Pro e Ultra hanno accesso completo in lettura e scrittura (27 strumenti) e, se preferiscono, possono passare alla modalità di sola lettura.

MCP (Model Context Protocol) ti permette di collegare assistenti AI come ChatGPT e Claude, assistenti di programmazione e strumenti di automazione direttamente ai tuoi dati di TellDone. Una volta collegato, il tuo assistente può leggere le tue note, attività, eventi, report, etichette e la cronologia delle modifiche. Da Pro in su può anche creare, aggiornare, eliminare e ripristinare elementi. Gli strumenti sono 27: 10 per leggere (ogni piano) e 17 per scrivere (da Pro in su).

Sull'iPhone, Impostazioni > Integrazioni > Agenti AI (MCP) apre la schermata di configurazione di MCP con il tuo token di accesso nascosto per impostazione predefinita:

E sul web:

Due modi per collegarsi

Ci sono due modi per collegare un client AI:

1. Accedi con TellDone (OAuth) (consigliato) - accedi con il tuo account TellDone e approvi ciò che l'app richiede. ChatGPT e Claude usano questo metodo e non c'è nessun token da copiare.
2. Bearer token - copia il tuo token di accesso dalle Impostazioni e incollalo nella configurazione del tuo client. È la soluzione più semplice per script, strumenti da riga di comando e client senza un flusso OAuth integrato.

Client	Consigliato
ChatGPT (chatgpt.com o l'app desktop di ChatGPT, non l'app per dispositivi mobili)	OAuth - aggiungi un server MCP personalizzato con l'URL MCP, poi accedi
Claude (sito web, Desktop, app per iPhone) / Cowork	OAuth - aggiungi un connettore personalizzato con l'URL MCP, poi accedi
Claude Code (CLI)	Bearer token per ora - aggiungi l'header Authorization con il tuo token
Script o il tuo codice	Bearer token - il più semplice da automatizzare
Un client che permette solo di scegliere da un elenco di connettori pubblicati	Aggiungi TellDone come connettore personalizzato con l'URL MCP, oppure usa un bearer token. TellDone non è ancora in nessun elenco di connettori

Requisiti del piano

Piano	MCP
Free	Sola lettura (10 strumenti di lettura), 100 richieste al giorno
Basic	Sola lettura (10 strumenti di lettura), nessun limite giornaliero
Pro	Lettura e scrittura (27 strumenti) - può passare alla modalità di sola lettura
Ultra	Lettura e scrittura (27 strumenti) - può passare alla modalità di sola lettura

Il limite di 100 richieste al giorno con Free conta solo le chiamate agli strumenti. Collegarsi, accedere ed elencare gli strumenti non conta. Il giorno segue il fuso orario salvato nel tuo account e si azzera a mezzanotte. Quando raggiungi il limite, il tuo assistente riceve un messaggio che lo dice. Con Free e Basic gli strumenti di scrittura vengono rifiutati. Con un token di accesso rispondono che la connessione è in sola lettura e che creare e modificare richiede Pro o superiore. Con l'accesso (OAuth), la maggior parte risponde "Insufficient scope", perché le connessioni Free e Basic non ottengono mai i permessi di scrittura.

La schermata nell'app

Apri Impostazioni > Integrazioni e, nella sezione Agenti AI, tocca Agenti AI (MCP). La schermata dice "Lascia che ChatGPT, Claude e altri assistenti AI lavorino con le tue note, attività ed eventi di TellDone." e mostra il tuo piano:

• Free: "Il tuo piano: accesso in sola lettura, 100 richieste al giorno. La scrittura arriva con Pro."
• Basic: "Il tuo piano: accesso in sola lettura"
• Pro e Ultra: "Il tuo piano: accesso in lettura e scrittura"

Finché MCP è disattivato, tocca Attiva per attivarlo.

Una volta attivato, la schermata mostra:

• Modalità di accesso (Pro e Ultra) - scegli Solo lettura o Lettura e scrittura in qualsiasi momento.
• Connetti un assistente - i passaggi per ChatGPT, Claude e Altro assistente. Accedi a TellDone direttamente nell'assistente, quindi non serve nessun token.
• App connesse - gli assistenti che hai collegato, ognuno con un pulsante Disconnetti. Resta vuoto fino alla prima connessione.
• Per sviluppatori (chiuso per impostazione predefinita) - il campo Token di accesso (nascosto, con Mostra / Nascondi e Copia), Rigenera token e un selettore Claude Code / Cursor / Altro con testo già pronto e un suo pulsante Copia. Claude Code ti dà il comando claude mcp add, Cursor ti dà il JSON per .cursor/mcp.json, e Altro elenca l'indirizzo del server, l'opzione di accesso OAuth e l'header Authorization: Bearer. Finché il token è nascosto, gli snippet mostrano YOUR_TOKEN. Tocca Mostra e contengono il tuo vero token.

Il web ha gli stessi controlli con una disposizione diversa, senza la sezione sviluppatori chiusa: l'indirizzo OAuth con un pulsante Copia, i controlli del token, App connesse con Disconnetti e Manual bearer token setup con sei client tra cui scegliere (Claude Code, Cursor, Windsurf, Codex, OpenClaw e cURL). Sul web gli snippet contengono sempre il tuo vero token, anche quando il campo del token è nascosto, quindi trattali come il token stesso.

• Documentazione - un link a questa pagina.
• Disattiva - disattiva MCP. Confermi con "Verrà revocato l'accesso per tutti gli strumenti AI collegati." Il tuo token viene eliminato e tutte le connessioni si interrompono. Se riattivi MCP, ricevi un nuovo token e le app collegate con l'accesso (OAuth) funzionano di nuovo senza dover accedere. Per rimuovere un'app definitivamente, tocca Disconnetti sotto App connesse.

suggerimento

Tieni privato il tuo token di accesso. Chiunque abbia il token può accedere ai tuoi dati di TellDone. Tocca Rigenera token se sospetti che sia trapelato.

Come attivarlo

Puoi configurare MCP da entrambe le piattaforme:

• iPhone: Impostazioni > Integrazioni > Agenti AI (MCP)
• Web: app.telldone.app > Impostazioni > Integrazioni > Agenti AI (MCP)

Passaggi:

1. Tocca Attiva.
2. Con Pro e Ultra, scegli la tua modalità di accesso (Solo lettura o Lettura e scrittura). Free e Basic sono in sola lettura.
3. Per collegare ChatGPT o Claude, toccalo sotto Connetti un assistente e segui i passaggi (vedi sotto). Non serve nessun token.
4. Per un client di programmazione su iPhone, apri Per sviluppatori, tocca Mostra, scegli Claude Code, Cursor o Altro e tocca Copia sotto lo snippet. Se copi prima di toccare Mostra, lo snippet ha YOUR_TOKEN al posto del tuo token. Sul web, scegli il tuo client sotto Manual bearer token setup e copia lo snippet: contiene già il tuo token.
5. Incolla lo snippet nel tuo client o nel suo file di configurazione.

Collegarsi con OAuth

OAuth è il percorso consigliato per ChatGPT, Claude e Cowork: accedi con il tuo account TellDone invece di copiare un token.

URL MCP per OAuth: https://api.telldone.app/mcp/user

Lo stesso server risponde anche a https://api.telldone.app/mcp/user/mcp, ed entrambi gli indirizzi accettano un bearer token. Per l'accesso OAuth, usa il primo.

ChatGPT

Puoi aggiungere un server MCP personalizzato su chatgpt.com o nell'app desktop di ChatGPT. L'app ChatGPT per dispositivi mobili non può aggiungere connettori personalizzati, e l'app TellDone lo dice così: "L'app ChatGPT aggiunge solo connettori dal suo catalogo." Tocca Invia i passaggi al mio computer in TellDone per ricevere le istruzioni su un computer. Una volta aggiunto lì, TellDone è disponibile anche nell'app ChatGPT per dispositivi mobili.

I passaggi nell'app:

1. Su un computer, apri chatgpt.com/plugins, clicca Add e scegli Add custom MCP server.
2. Chiamalo TellDone, incolla l'indirizzo qui sotto (https://api.telldone.app/mcp/user) e scegli OAuth.
3. Conferma e installalo, poi accedi a TellDone e consenti l'accesso.

Se i nomi dei menu cambiano, vedi la guida di OpenAI sui server MCP personalizzati.

Claude (sito web, Desktop, app per iPhone) / Cowork

I passaggi nell'app:

1. In Claude, apri Customize → Connectors e tocca Add custom connector.
2. Incolla l'indirizzo qui sotto (https://api.telldone.app/mcp/user).
3. Accedi a TellDone e consenti l'accesso.

Quando accedi, la pagina di consenso di TellDone mostra quale app chiede l'accesso e i permessi esatti che vuole. Accedi con l'email e la password di TellDone e clicca Allow access, oppure tocca Sign in with Apple o Sign in with Google, che approva l'accesso nello stesso passaggio. Claude si collega da solo: non c'è nessun token da copiare.

Se i nomi dei menu cambiano, vedi la guida di Anthropic su come aggiungere un connettore personalizzato.

Collegarsi con un bearer token

Per Claude Code, Cursor e altri client senza accesso OAuth integrato, incolla il tuo token di accesso direttamente nella configurazione del client. In tutti gli esempi qui sotto, sostituisci YOUR_TOKEN con il token delle tue impostazioni.

Claude Code (bearer token)

claude mcp add --transport http telldone \
  https://api.telldone.app/mcp/user/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Non devi scriverlo tu: in Impostazioni > Integrazioni > Agenti AI (MCP) > Per sviluppatori, tocca Mostra, scegli Claude Code e tocca Copia. Il comando copiato contiene già il tuo token.

Cursor

Aggiungi a .cursor/mcp.json (oppure copialo da Per sviluppatori > Cursor dopo aver toccato Mostra):

{
  "mcpServers": {
    "telldone": {
      "url": "https://api.telldone.app/mcp/user/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Altri client

Impostazioni per altri client MCP:

Codex

Aggiungi a codex.json:

{
  "mcpServers": {
    "telldone": {
      "type": "http",
      "url": "https://api.telldone.app/mcp/user/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

OpenClaw

Settings > MCP Servers > Add:

• Name: TellDone
• URL: https://api.telldone.app/mcp/user/mcp
• Auth: Bearer YOUR_TOKEN

Altri client MCP

Qualsiasi strumento che supporta MCP su HTTP può collegarsi. Usa l'endpoint https://api.telldone.app/mcp/user/mcp con un header di autorizzazione Bearer YOUR_TOKEN.

Header di autenticazione alternativo

Se il tuo client o proxy riserva l'header Authorization (per esempio, alcuni gateway in stile Smithery), invia invece il token in X-MCP-Token: YOUR_TOKEN. Funzionano entrambi gli header; se sono presenti tutti e due, vince Authorization.

Verificare la connessione

Puoi controllare che il tuo token funzioni con un semplice comando cURL:

curl -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Una risposta positiva elenca tutti gli strumenti disponibili.

Permessi (scope)

Le connessioni OAuth hanno degli scope: durante l'accesso vedi esattamente cosa chiede il client e lo approvi in modo esplicito.

Scope	Permette all'app di...
notes:read	Leggere le tue note e aprire i dettagli completi di una nota (lo strumento di ricerca richiede anche tasks:read e events:read)
notes:write	Creare, modificare ed eliminare note (process_note richiede anche tasks:write e events:write)
tasks:read / tasks:write	Leggere / creare, modificare, completare ed eliminare attività
events:read / events:write	Leggere / creare, modificare ed eliminare eventi
reports:read	Leggere i tuoi report giornalieri, settimanali, mensili e annuali
tags:read / tags:write	Elencare le tue etichette / creare, fissare, eliminare e ripristinare etichette
profile:read	Leggere le informazioni del tuo account e il tuo abbonamento
offline_access	Restare connesso (emette un refresh token, così non devi accedere di nuovo a ogni sessione)

Gli scope limitano ciò che una connessione può fare: una connessione con solo notes:read non può chiamare uno strumento di scrittura. Il tuo piano imposta un secondo limite in aggiunta.

Le connessioni con bearer token non hanno scope singoli: sono regolate solo dalla modalità di lettura/scrittura del tuo piano.

Cosa puoi fare

Strumenti di lettura (10) - tutti i piani

Strumento	Cosa fa
get_notes	Elenca le note con filtri (etichette, intervallo di date, ricerca testuale)
get_note	Mostra una singola nota con le attività e gli eventi collegati e la trascrizione completa
get_notes_full	Ottiene più note con attività ed eventi incorporati in una sola chiamata
get_tasks	Elenca le attività filtrate per stato (da fare, completate, tutte), etichette o date
get_events	Elenca gli eventi di calendario, con filtro per intervallo di date
get_reports	Legge i tuoi report giornalieri, settimanali, mensili e annuali (markdown completo)
get_tags	Mostra tutte le tue etichette ordinate per utilizzo
get_profile	Mostra le informazioni del tuo account e quante note, attività ed eventi hai
search	Cerca tra note, attività ed eventi (testo + ricerca semantica per le note)
get_change_log	Mostra la cronologia delle modifiche di una nota, un'attività o un evento, e se ogni modifica è stata annullata

suggerimento

Lo strumento search supporta la ricerca semantica per le note: trova i risultati in base al significato, non solo alle parole chiave. Per esempio, cercando "riunioni sul budget" trova note su discussioni finanziarie anche se non contengono la parola "budget."

Strumenti di scrittura (17) - Pro e Ultra

Strumento	Cosa fa
process_note	Pipeline AI completa: invia testo o audio e ottieni una nota con attività, eventi ed etichette
create_note	Aggiunge una nota di testo semplice (senza analisi AI)
create_task	Aggiunge un'attività con priorità, scadenza, promemoria ed etichette
create_event	Aggiunge un evento di calendario con data, ora, luogo, promemoria, partecipanti e regola di ripetizione
update_note	Cambia titolo, riepilogo, tipo, etichette, priorità o stato di una nota
update_task	Cambia titolo, descrizione, priorità, scadenza, promemoria, etichette o stato di un'attività
complete_task	Segna un'attività come completata
update_event	Cambia dettagli, ora, luogo, promemoria, partecipanti, regola di ripetizione, etichette o stato di un evento
delete_note	Elimina una nota. Le sue attività e i suoi eventi restano
delete_task	Elimina un'attività
delete_event	Elimina un evento
undo_change_log_entry	Annulla una singola modifica tracciata, fatta dall'AI o da te, ripristinando il valore precedente del campo
restore_entity	Riporta indietro una nota o un'attività eliminata o archiviata, oppure un evento eliminato o annullato
create_tag	Crea una nuova etichetta, oppure trasforma un'etichetta suggerita automaticamente in una permanente
set_tag_pinned	Fissa o sblocca un'etichetta perché compaia in cima
delete_tag	Rimuove un'etichetta (si può ripristinare con restore_tag)
restore_tag	Riporta indietro un'etichetta eliminata

Tutte le operazioni di scrittura e di eliminazione compaiono subito sui tuoi dispositivi collegati (telefono, app web).

Riferimento degli strumenti

get_notes

Elenca le note con filtri facoltativi. I filtri di data usano recorded_at (quando hai registrato la nota vocale), oppure created_at per una nota che non lo ha.

Parametro	Tipo	Predefinito	Descrizione
limit	int	20	Numero di note da restituire (max 50)
offset	int	0	Salta questo numero di note (per la paginazione, max 10000)
tags	string	-	Filtra per etichette, separate da virgole (corrisponde a una qualsiasi)
search	string	-	Ricerca testuale su titolo e riepilogo
date_from	string	-	Data di inizio, AAAA-MM-GG (inclusa)
date_to	string	-	Data di fine, AAAA-MM-GG (esclusa)
standalone_only	bool	false	Se true, nasconde le note di aggiornamento (note collegate a una nota/attività/evento genitore) e restituisce solo le note indipendenti

Restituisce: elenco di note con id, title, summary, type, tags, priority, status, recorded_at, created_at.

get_note

Ottiene una singola nota con la trascrizione completa e tutte le attività e gli eventi collegati.

Parametro	Tipo	Descrizione
note_id	string	L'UUID della nota

Restituisce: nota con title, summary, transcript, type, tags, priority, status, metadata, created_at, più gli array tasks[] ed events[].

Restituisce anche transcript_speakers (turni della trascrizione con l'etichetta dell'interlocutore, per le riunioni con più interlocutori - altrimenti null), speaker_count (null a meno che la registrazione sia stata divisa per interlocutore) e parent_note_id/parent_task_id/parent_event_id (impostati quando questa nota è un aggiornamento di un altro elemento). Ogni voce di tasks[]/events[] include anche reminders_at/recurrence_rule (attività) oppure reminder_minutes/attendees/recurrence_rule (eventi).

get_notes_full

Ottiene più note con le loro attività ed eventi in una sola chiamata. Stessi filtri di get_notes tranne search, e ogni nota include tasks[] ed events[] incorporati.

Parametro	Tipo	Predefinito	Descrizione
limit	int	10	Numero di note (max 20)
offset	int	0	Salta questo numero di note
tags	string	-	Filtra per etichette
date_from	string	-	Data di inizio, AAAA-MM-GG
date_to	string	-	Data di fine, AAAA-MM-GG
standalone_only	bool	false	Se true, nasconde le note di aggiornamento (note collegate a una nota/attività/evento genitore) e restituisce solo le note indipendenti

get_tasks

Elenca le attività con filtri.

Parametro	Tipo	Predefinito	Descrizione
status	string	"todo"	Filtro: todo, done o all
limit	int	30	Numero di attività (max 100)
offset	int	0	Salta questo numero di attività
tags	string	-	Filtra per etichette, separate da virgole
date_from	string	-	Data di inizio, AAAA-MM-GG (filtra per scadenza; le attività senza scadenza sono escluse)
date_to	string	-	Data di fine, AAAA-MM-GG (filtra per scadenza; le attività senza scadenza sono escluse)

Restituisce: elenco di attività con id, title, description, status, priority, tags, deadline, reminder_at, reminders_at, completed_at, completed_by, source, created_at. reminder_at replica la prima voce di reminders_at per compatibilità con il passato: usa reminders_at per vedere tutti i promemoria di un'attività.

get_events

Elenca gli eventi di calendario con filtro per intervallo di date.

Parametro	Tipo	Predefinito	Descrizione
limit	int	30	Numero di eventi (max 100)
offset	int	0	Salta questo numero di eventi
date_from	string	-	Primo giorno, AAAA-MM-GG, nel tuo fuso orario (incluso). Gli eventi che si sovrappongono all'intervallo sono inclusi, quindi un evento di più giorni compare in ogni giorno che copre
date_to	string	-	Ultimo giorno, AAAA-MM-GG, nel tuo fuso orario (incluso)

Restituisce: elenco di eventi con id, title, description, status, start_at, end_at, location, is_all_day, tags, note_id, reminder_minutes, attendees, recurrence_rule, created_at.

get_reports

Ottiene i tuoi report generati dall'AI con il contenuto markdown completo.

Parametro	Tipo	Predefinito	Descrizione
report_type	string	"daily"	Tipo: daily, weekly, monthly o yearly
limit	int	5	Numero di report (max 10)

Restituisce: elenco di report con id, type, period_start, period_end, content_md, created_at.

nota

I report mensili sono lunghi (spesso ben oltre 1.000 parole). Usa limit=1 se il tuo strumento AI ha una finestra di contesto ridotta.

get_tags

Ottiene tutte le tue etichette, con prima quelle fissate, poi in ordine di numero di utilizzi.

Nessun parametro. Restituisce fino a 100 etichette, ognuna con tag, usage_count, is_pinned, is_manual.

get_profile

Ottiene le informazioni del tuo account e quante note, attività ed eventi hai.

Nessun parametro. Restituisce email, display_name, locale, transcription_locale, timezone, subscription, mcp_mode, created_at e stats (conteggi di note/attività/eventi).

search

Cerca contemporaneamente tra note, attività ed eventi. Per le note supporta sia la ricerca testuale sia quella semantica (trova i risultati in base al significato usando gli embedding AI).

Parametro	Tipo	Predefinito	Descrizione
query	string	obbligatorio	Testo da cercare (max 500 caratteri)
limit	int	20	Max risultati per tipo (max 20)
semantic	bool	true	Attiva la ricerca semantica per le note

Restituisce risultati raggruppati per tipo: notes[], tasks[], events[]. Ogni risultato ha id, type, title, detail, created_at.

Imposta semantic=false per una ricerca solo testuale più veloce.

get_change_log

Mostra la cronologia delle modifiche di una nota, un'attività o un evento: ogni modifica fatta dall'AI con un aggiornamento e ogni modifica manuale fatta da te, dalla più recente.

Parametro	Tipo	Predefinito	Descrizione
entity	string	obbligatorio	notes, tasks o events
entity_id	string	obbligatorio	L'UUID dell'elemento
include_manual	bool	false	Include anche le tue modifiche manuali, non solo quelle fatte dall'AI

Restituisce: elenco di voci di modifica con id (usalo come entry_id per annullare), field_name, old_value, new_value, source (follow_up, smart_context, correction_sync per una correzione di un nome che TellDone ha riportato su una nota, oppure manual), origin_note_id, edited_at e reverted_at (impostato una volta annullata).

process_note (Pro e Ultra)

Pipeline AI completa: funziona come registrare nell'app. Invia testo o audio e TellDone trascrive, analizza con l'AI e crea una nota strutturata con attività, eventi, etichette ed embedding estratti.

Questo strumento è asincrono: restituisce subito un audio_id ed elabora in background. I risultati arrivano con la sincronizzazione in tempo reale sui tuoi dispositivi collegati, oppure puoi controllare con get_notes().

Parametro	Tipo	Descrizione
text	string	Obbligatorio. Testo da analizzare. Se non è vuoto, viene usato come trascrizione e l'eventuale audio che invii non viene trascritto; invia "" per far trascrivere l'audio. Limite quando non viene inviato audio: Pro 20.000 / Ultra 50.000 caratteri
audio_base64	string	File audio codificato in Base64. L'intera richiesta è limitata a 10 MB, quindi l'audio stesso può essere di circa 7 MB. Viene trascritto solo quando text è vuoto
audio_format	string	m4a, ogg, wav, mp3, aac o webm (predefinito: m4a)
parent_task_id	string	UUID di un'attività di cui questa è un aggiornamento
parent_note_id	string	UUID di una nota di cui questa è un aggiornamento
parent_event_id	string	UUID di un evento di cui questo è un aggiornamento

Invia sempre text. Per far trascrivere l'audio a TellDone, invia audio_base64 con text impostato su una stringa vuota (""). Se text non è vuoto, TellDone lo usa come trascrizione e non trascrive l'audio. Imposta al massimo uno dei tre ID genitore.

Restituisce: {"audio_id": "...", "status": "processing", "mode": "text-only"} oppure "mode": "audio+stt" se è stato fornito l'audio.

nota

process_note è soggetto alle quote del tuo piano (caricamenti al giorno, note al mese, lunghezza massima del testo). get_profile mostra solo quante note, attività ed eventi hai, non i tuoi limiti. Controlla il tuo utilizzo nell'app in Impostazioni > Utilizzo.

create_note (Pro e Ultra)

Crea subito una nota di testo semplice. Non avvia l'analisi AI: non vengono estratte attività né eventi. Usa process_note quando vuoi che TellDone trovi attività ed eventi per te.

Parametro	Tipo	Limite	Descrizione
title	string	200 car.	Obbligatorio
summary	string	1000 car.	Facoltativo. Breve anteprima (1-3 frasi). Usato nei tuoi report, quindi tienilo breve
transcript	string	in base al piano	Facoltativo. Testo esteso mostrato nel dettaglio della nota. Non incluso nei report. Limiti: Pro 20.000 / Ultra 50.000 car.
type	string	-	Facoltativo. task, idea, info (predefinito), status, meeting, event o reflection
tags	string	20 etichette	Separate da virgole, facoltativo
suppress_external_sync	boolean	-	Facoltativo, predefinito false. Impostalo su true per elementi importati o in blocco: l'elemento non viene inviato alle tue app collegate né alle tue automazioni

create_task (Pro e Ultra)

Crea una nuova attività. L'attività viene creata anche nel tuo Todoist, Notion o Microsoft To Do collegato, e le tue automazioni ricevono task.created. Questo non succede se passi suppress_external_sync: true.

Parametro	Tipo	Limite	Descrizione
title	string	200 car.	Obbligatorio
description	string	2000 car.	Facoltativo
priority	string	-	low, medium (predefinito) o high
deadline	string	-	AAAA-MM-GG, facoltativo
reminder_at	string	-	Data e ora ISO 8601 (per esempio 2026-04-15T09:00:00Z), facoltativo
tags	string	20 etichette	Separate da virgole, facoltativo
note_id	string	-	UUID per collegare l'attività a una nota genitore, facoltativo
suppress_external_sync	boolean	-	Facoltativo, predefinito false. Impostalo su true per elementi importati o in blocco: l'elemento non viene inviato alle tue app collegate né alle tue automazioni

create_event (Pro e Ultra)

Crea un evento di calendario. L'evento viene creato anche nel tuo Notion collegato, e le tue automazioni ricevono calendar_event.created. Questo non succede se passi suppress_external_sync: true.

Parametro	Tipo	Limite	Descrizione
title	string	200 car.	Obbligatorio
start_at	string	-	Data e ora ISO 8601, obbligatorio
end_at	string	-	Data e ora ISO 8601 (predefinito: inizio + 1 ora; per un evento di tutto il giorno, un giorno)
description	string	2000 car.	Facoltativo
location	string	200 car.	Facoltativo
is_all_day	bool	-	Predefinito: false
tags	string	20 etichette	Separate da virgole, facoltativo
reminder_minutes	string	-	Minuti prima dell'evento, separati da virgole (per esempio 15,60), facoltativo
attendees	string	-	Nomi o email separati da virgole, facoltativo
recurrence_rule	string	-	Stringa RRULE (per esempio FREQ=WEEKLY;BYDAY=MO,WE,FR), facoltativo. Le regole più frequenti di una volta all'ora, o che non possono mai verificarsi, vengono rifiutate
note_id	string	-	UUID per collegare l'evento a una nota genitore, facoltativo
suppress_external_sync	boolean	-	Facoltativo, predefinito false. Impostalo su true per elementi importati o in blocco: l'elemento non viene inviato alle tue app collegate né alle tue automazioni

update_note (Pro e Ultra)

Aggiorna uno o più campi di una nota esistente. Vengono cambiati solo i campi che fornisci. Funziona esattamente come modificare la nota nell'app: titolo, riepilogo, etichette e tipo arrivano alla sua pagina Notion, le tue automazioni ricevono note.updated e la modifica compare nella cronologia delle modifiche, dove puoi annullarla. Anche una modifica alla trascrizione viene salvata e inviata a Notion, ma non compare nella cronologia.

Parametro	Tipo	Descrizione
note_id	string	Obbligatorio, l'UUID della nota
title	string	Nuovo titolo (max 200 car.)
summary	string	Nuovo riepilogo (max 1000 car., passa uno spazio " " per cancellarlo)
transcript	string	Nuova trascrizione (limite in base al piano, passa uno spazio " " per cancellarla)
type	string	task, idea, info, status, meeting, event o reflection
tags	string	Etichette separate da virgole (sostituisce tutte le etichette esistenti, max 20)
priority	string	low, medium o high
status	string	active o archived

attenzione

Per le note create dalla pipeline vocale, transcript è l'output originale del riconoscimento vocale. Sovrascriverlo sostituisce le tue parole originali. Per conservarle, aggiungi alla trascrizione invece di sostituirla.

update_task (Pro e Ultra)

Aggiorna uno o più campi di un'attività esistente. Vengono cambiati solo i campi che fornisci. Funziona esattamente come modificare l'attività nell'app: la modifica arriva alle sue copie in Todoist, Notion e Microsoft To Do, le tue automazioni ricevono task.updated e la modifica compare nella cronologia delle modifiche dell'attività, dove puoi annullarla. Impostare status su done la completa come complete_task. Una scadenza può essere una data oppure una data con ora completa (viene usata la data). Ogni etichetta può avere fino a 50 caratteri.

Parametro	Tipo	Descrizione
task_id	string	Obbligatorio, l'UUID dell'attività
title	string	Nuovo titolo
description	string	Nuova descrizione (passa uno spazio " " per cancellarla)
priority	string	low, medium o high
deadline	string	AAAA-MM-GG. Questo strumento non può cancellare una scadenza; cancellala nell'app
status	string	todo o done
tags	string	Etichette separate da virgole (sostituisce tutte le etichette esistenti, max 20)
reminder_at	string	Data e ora ISO 8601 (passa uno spazio per cancellarla)

Impostare status su done registra anche quando e come l'attività è stata completata.

complete_task (Pro e Ultra)

Scorciatoia per segnare un'attività come completata.

Parametro	Tipo	Descrizione
task_id	string	Obbligatorio, l'UUID dell'attività

Restituisce un errore se l'attività non esiste o è già completata.

update_event (Pro e Ultra)

Aggiorna uno o più campi di un evento esistente. Vengono cambiati solo i campi che fornisci. Funziona esattamente come modificare l'evento nell'app: la modifica arriva alla sua pagina Notion, le tue automazioni ricevono calendar_event.updated e la modifica compare nella cronologia delle modifiche, dove puoi annullarla.

Parametro	Tipo	Descrizione
event_id	string	Obbligatorio, l'UUID dell'evento
title	string	Nuovo titolo
description	string	Nuova descrizione (passa uno spazio per cancellarla)
start_at	string	Nuova ora di inizio (ISO 8601)
end_at	string	Nuova ora di fine (ISO 8601)
location	string	Nuovo luogo (passa uno spazio per cancellarlo)
status	string	confirmed, tentative o cancelled
tags	string	Etichette separate da virgole (sostituisce tutte le etichette esistenti, max 20)
is_all_day	string	"true" o "false"
reminder_minutes	string	Minuti prima dell'evento, separati da virgole (per esempio 15,60, passa uno spazio per cancellarli)
attendees	string	Nomi o email separati da virgole (passa uno spazio per cancellarli)
recurrence_rule	string	Stringa RRULE (passa uno spazio per cancellarla)

delete_note (Pro e Ultra)

Elimina una nota. Viene eliminata solo la nota: le sue attività e i suoi eventi restano. Funziona esattamente come eliminarla nell'app: le tue automazioni ricevono note.deleted. Un'eventuale copia della nota in Notion non viene rimossa (nemmeno l'app la rimuove).

Parametro	Tipo	Descrizione
note_id	string	Obbligatorio, l'UUID della nota

delete_task (Pro e Ultra)

Elimina un'attività. Funziona esattamente come eliminarla nell'app: vengono eliminate anche le sue copie in Todoist, Notion e Microsoft To Do, e le tue automazioni ricevono task.deleted. Puoi riportarla indietro con restore_entity.

Parametro	Tipo	Descrizione
task_id	string	Obbligatorio, l'UUID dell'attività

delete_event (Pro e Ultra)

Elimina un evento. Funziona esattamente come eliminarlo nell'app: le tue automazioni ricevono calendar_event.deleted. La pagina dell'evento in Notion non viene rimossa (nemmeno l'app la rimuove).

Parametro	Tipo	Descrizione
event_id	string	Obbligatorio, l'UUID dell'evento

undo_change_log_entry (Pro e Ultra)

Annulla una singola modifica tracciata: riporta il campo al valore che aveva prima di quella modifica, sia che l'abbia fatta l'AI (da una registrazione di aggiornamento) sia che l'abbia fatta tu direttamente.

Parametro	Tipo	Descrizione
entity	string	Obbligatorio, notes, tasks o events
entity_id	string	Obbligatorio, l'UUID dell'elemento
entry_id	string	Obbligatorio, l'id della voce di modifica da get_change_log

Restituisce: {"entry_id", "entity_type", "entity_id", "field_name", "restored_value", "reverted_at"}. Annullare due volte la stessa voce restituisce un errore: è già annullata.

restore_entity (Pro e Ultra)

Riporta indietro una nota o un'attività eliminata o archiviata, oppure un evento eliminato o annullato.

Parametro	Tipo	Descrizione
entity	string	Obbligatorio, notes, tasks o events
entity_id	string	Obbligatorio, l'UUID dell'elemento

Restituisce: l'elemento ripristinato in JSON.

create_tag (Pro e Ultra)

Crea una nuova etichetta, oppure trasforma un'etichetta esistente suggerita automaticamente in una permanente.

Parametro	Tipo	Descrizione
tag	string	Obbligatorio, 1-50 caratteri (salvata in minuscolo)
category	string	Facoltativo

set_tag_pinned (Pro e Ultra)

Fissa o sblocca un'etichetta perché compaia in cima al tuo elenco di etichette.

Parametro	Tipo	Descrizione
tag	string	Obbligatorio
pinned	bool	Obbligatorio

Le etichette che contengono il carattere / non possono essere fissate.

delete_tag (Pro e Ultra)

Rimuove un'etichetta. Si può riportare indietro con restore_tag.

Parametro	Tipo	Descrizione
tag	string	Obbligatorio

restore_tag (Pro e Ultra)

Riporta indietro un'etichetta eliminata.

Parametro	Tipo	Descrizione
tag	string	Obbligatorio

Limiti di input

Campo	Lunghezza massima	Usato in
title	200 caratteri	create/update note, task, event
description	2.000 caratteri	create/update task, event
summary	1.000 caratteri (rigido)	create/update note. Usato nei tuoi report, quindi tienilo breve
transcript	in base al piano: Pro 20.000 / Ultra 50.000	create/update note. Testo esteso, non nei report
text	in base al piano: Pro 20.000 / Ultra 50.000 (quando non viene inviato audio)	process_note
location	200 caratteri	create/update event
tags	20 etichette	create/update note, task, event
search query	500 caratteri	search
audio_base64	circa 7 MB di audio (l'intera richiesta è limitata a 10 MB)	process_note

Se superi un limite, lo strumento restituisce un messaggio di errore come "title too long (max 200 chars, got 250)".

Gestione degli errori

La maggior parte degli strumenti restituisce gli errori in JSON:

{"error": "description of what went wrong"}

Gli errori di piano, di scope e di limite di input arrivano come errore dello strumento con lo stesso messaggio.

Errori comuni:

Errore	Quando
"This TellDone connection is read-only. Creating and editing needs the Pro or Ultra plan."	Strumento di scrittura chiamato in modalità di sola lettura (Free e Basic, oppure Pro e Ultra passati alla sola lettura)
"Daily limit reached: the Free plan includes 100 TellDone requests a day..."	Il piano Free ha esaurito le sue 100 richieste del giorno
"Daily limit reached (N/M today)"	Oggi hai creato tramite assistenti AI tanti elementi quanti ne permette il tuo piano (process_note, create_note, create_task e create_event contano ciascuno)
"Notes limit reached (X/Y this month)"	Il limite mensile di note del tuo piano è esaurito
"Invalid note_id format"	Stringa non UUID passata come ID
"Note not found"	L'ID non esiste o appartiene a un altro utente
"Task not found or already completed"	complete_task su un'attività inesistente o già completata
"title too long (max 200 chars, got N)"	Limite di input superato
"Too many tags (max 20)"	Fornite più di 20 etichette

Errori a livello HTTP:

Codice	Significato
401	Token non valido, revocato o eliminato (disattivare MCP elimina il tuo token e rigenerarlo lo sostituisce)
429	Limite di frequenza superato (5 richieste/s, picco fino a 20)

Con Free, raggiungere il limite di 100 richieste al giorno viene segnalato con un messaggio di errore dello strumento (non con un codice HTTP) e si azzera a mezzanotte nel fuso orario salvato nel tuo account.

Esempi d'uso

Tutti gli esempi usano cURL con il protocollo JSON-RPC di MCP. Sostituisci YOUR_TOKEN con il tuo token di accesso.

Leggere i dati

# Get your profile and stats
curl -s -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"get_profile"}}'

# List recent notes (limit 5, from April 2026)
curl -s -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"get_notes","arguments":{"limit":5,"date_from":"2026-04-01"}}}'

# Search notes (hybrid text + semantic)
curl -s -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"search","arguments":{"query":"project deadline","limit":5}}}'

Scrivere i dati (Pro e Ultra)

# Process a note through full AI pipeline (extracts tasks + events)
curl -s -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":10,"method":"tools/call",
       "params":{"name":"process_note","arguments":{"text":"Need to buy groceries tomorrow. Meeting with Katie at 3pm at the cafe to discuss the project."}}}'

# Create a task with deadline and reminder
curl -s -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":11,"method":"tools/call",
       "params":{"name":"create_task","arguments":{"title":"Review PR","priority":"high","deadline":"2026-04-15","reminder_at":"2026-04-15T09:00:00Z","tags":"dev"}}}'

# Create a repeating event with reminders and attendees
curl -s -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":12,"method":"tools/call",
       "params":{"name":"create_event","arguments":{"title":"Team standup","start_at":"2026-04-12T10:00:00Z","reminder_minutes":"15","attendees":"Katie,John","recurrence_rule":"FREQ=DAILY;BYDAY=MO,TU,WE,TH,FR","tags":"meeting"}}}'

# Complete a task
curl -s -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":13,"method":"tools/call",
       "params":{"name":"complete_task","arguments":{"task_id":"<task-uuid>"}}}'

Una risposta positiva è fatta così:

{
  "jsonrpc": "2.0",
  "id": 11,
  "result": {
    "content": [{"type": "text", "text": "{\"id\":\"...\",\"title\":\"Review PR\",\"status\":\"todo\"}"}]
  }
}

nota

Gli strumenti di scrittura e aggiornamento restituiscono risposte brevi, per lo più id, title e status. Gli strumenti di eliminazione restituiscono id e deleted. Per ottenere i dettagli completi (etichette, priorità, scadenza, ecc.) dopo una scrittura, fai una chiamata di lettura successiva come get_tasks o get_note.

Gestione del token

Azione	Come
Vedere il token	iPhone: Impostazioni > Integrazioni > Agenti AI (MCP) > Per sviluppatori (oppure sul web, Impostazioni > Integrazioni > Agenti AI (MCP)), tocca Mostra
Copiare il token	Tocca Copia accanto al token
Rigenerare	Tocca Rigenera token e conferma. Il vecchio token smette di funzionare subito. Gli assistenti collegati con l'accesso OAuth non sono interessati; disconnettili sotto App connesse
Cambiare modalità	Pro e Ultra: scegli Solo lettura o Lettura e scrittura. Free e Basic sono sempre in sola lettura
Disattivare	Tocca Disattiva e conferma ("Verrà revocato l'accesso per tutti gli strumenti AI collegati."). Il tuo token viene eliminato e tutte le connessioni si interrompono. Se riattivi MCP, ricevi un nuovo token e le app collegate con l'accesso (OAuth) funzionano di nuovo senza dover accedere. Per rimuovere un'app definitivamente, tocca Disconnetti sotto App connesse

Cosa puoi chiedere al tuo agente AI

Una volta collegato, chiedi al tuo strumento AI cose come:

Rivedi la tua giornata:

• "Su cosa ho lavorato oggi?"
• "Mostrami le mie note di questa settimana"
• "Quali attività sono scadute?"

Gestisci le attività:

• "Crea un'attività: rivedere il report trimestrale, priorità alta, scadenza venerdì"
• "Segna come completata l'attività di Figma"
• "Su quali attività sto lavorando?"

Cerca e analizza:

• "Trova tutte le note sulla strategia di marketing"
• "Che eventi ho la prossima settimana?"
• "Riassumi i miei report giornalieri della settimana scorsa"

Pianifica in anticipo:

• "Crea un evento: riunione di team domani alle 10"
• "Cosa c'è sul mio calendario questa settimana?"
• "Mostrami le mie etichette principali: a cosa dedico più tempo?"

Il tuo assistente può leggere le tue note, attività, eventi e report e rispondere a domande complesse combinando le informazioni di più strumenti. Con Pro e Ultra, con Lettura e scrittura attiva, può anche crearli, aggiornarli ed eliminarli.

Da sapere

• Integrazioni e automazioni - process_note funziona come una registrazione, quindi la sua nota, le attività e gli eventi vanno alle tue integrazioni collegate e alle automazioni webhook. Gli elementi che crei, modifichi o elimini con gli altri strumenti di scrittura si comportano esattamente come nell'app: arrivano alle tue integrazioni collegate (gli eventi e le modifiche alle note arrivano solo a Notion) e alle tue automazioni. Ripristinare un'attività con restore_entity, o annullarne il completamento con undo_change_log_entry, la riapre anche nelle integrazioni con cui era sincronizzata.
• Modifiche fatte da un assistente AI - nella cronologia dell'elemento risultano fatte da un assistente. Non vengono usate per migliorare il riconoscimento vocale di TellDone e non vengono copiate negli altri elementi della nota. Le modifiche tramite un assistente condividono il limite dell'app di 30 modifiche al minuto.
• Ricerca semantica - le note create con process_note o create_note ottengono entrambe gli embedding, quindi compaiono nella ricerca semantica dopo un breve ritardo.
• Filtri di data - per le note, le date sono giorni UTC. Per gli eventi, le date sono i tuoi giorni locali e un evento che si sovrappone all'intervallo è incluso. Per le attività, il filtro è la data di scadenza.

Sicurezza

• Ogni utente riceve un token di accesso univoco a 384 bit
• Il tuo token viene revocato all'istante quando disattivi MCP o lo rigeneri
• Ogni richiesta è limitata al tuo account, quindi il tuo agente può accedere solo ai tuoi dati
• La connessione usa HTTPS con limitazione della frequenza (5 richieste/s, picco fino a 20)
• Le connessioni OAuth usano PKCE con codici di autorizzazione monouso e token di accesso di breve durata: puoi revocare una connessione in qualsiasi momento dall'app

Per un approfondimento tecnico (endpoint di discovery, durata dei token, il flusso OAuth completo), vedi il nostro riferimento open source del connettore su github.com/exp78/telldone-mcp, oppure interroga direttamente https://api.telldone.app/.well-known/oauth-protected-resource.

Privacy e flusso dei dati

Uno strumento AI collegato riceve i tuoi dati solo quando chiama TellDone, di solito perché gli hai chiesto qualcosa. Riceve solo le risposte a quelle chiamate, entro i permessi che hai approvato. Per limitare l'accesso, passa a Solo lettura, disconnetti l'app sotto App connesse, oppure rigenera o disattiva il tuo token di accesso nelle Impostazioni. Vedi l'Informativa sulla privacy per tutti i dettagli, oppure scrivi a support@telldone.app per qualsiasi domanda.

Risoluzione dei problemi

Sintomo	Causa / soluzione
La pagina di consenso OAuth dice "Wrong email or password"	Usa l'email e la password con cui accedi all'app, oppure scegli Sign in with Apple / Sign in with Google nella stessa pagina.
Collegato, ma l'AI non può creare né modificare nulla	Il tuo piano è Free o Basic (sola lettura), la tua modalità è di sola lettura, oppure la connessione non ha i permessi di scrittura. Se ti sei collegato prima di passare a un piano superiore, disconnetti l'app sotto App connesse e collegala di nuovo. Puoi controllare la tua modalità nelle Impostazioni.
Errore "Insufficient scope" da uno strumento	La connessione non ha quel permesso. Con Free e Basic i permessi di scrittura non vengono mai concessi, quindi creare e modificare richiede Pro o Ultra. Se ti sei collegato prima di passare a un piano superiore, disconnetti l'app sotto App connesse e collegala di nuovo.
Lo snippet copiato dice YOUR_TOKEN e il client non riesce a collegarsi	L'hai copiato mentre il token era nascosto. In Per sviluppatori, tocca Mostra, poi copia di nuovo lo snippet.
Gli strumenti non compaiono affatto	MCP non è attivo sul tuo account (Impostazioni > Integrazioni > Agenti AI (MCP) > Attiva).
"Daily limit reached"	Due limiti usano questo messaggio. "Daily limit reached: the Free plan includes 100 TellDone requests a day" è il limite di richieste di Free. "Daily limit reached (N/M today)" significa che oggi hai creato tramite assistenti AI tanti elementi quanti ne permette il tuo piano: process_note, create_note, create_task e create_event contano ciascuno, anche con Pro e Ultra. Entrambi si azzerano a mezzanotte nel fuso orario salvato nel tuo account.
Il mio client mi lascia scegliere solo da un elenco di connettori e TellDone non c'è	TellDone non è ancora nella directory dei connettori di nessun client: aggiungilo come connettore personalizzato con l'URL MCP, oppure usa il metodo con bearer token.

Vedi anche

• Automazioni webhook - invia dati a servizi esterni in automatico
• Todoist - sincronizzazione bidirezionale dedicata delle attività
• Notion - integrazione dedicata a Notion