Accesso MCP (AI agents)

Cosa è cambiato di recente

MCP è ora pienamente disponibile su iPhone (oltre alla web app). La schermata su iPhone rispecchia quella web e include gli stessi snippet di setup per tutti i client AI supportati.

Piano Pro e superiori

L'accesso MCP richiede un piano Pro o Ultra. Entrambi i piani ottengono accesso completo read + write (27 strumenti) e possono passare alla modalità solo lettura se preferisci.

MCP (Model Context Protocol) ti permette di collegare assistenti AI per il coding e strumenti di automazione direttamente ai tuoi dati TellDone. Una volta connesso, il tuo AI agent può leggere note, attività, eventi, report, tag e cronologia delle modifiche - e creare, aggiornare, eliminare e ripristinare elementi. Ci sono 27 strumenti in totale: 10 per leggere i dati e 17 per scrivere.

Disponibile sia nell'app per iPhone (Impostazioni → Integrazioni → AI Agents) sia nella web app (Impostazioni → AI Agents).

Due modi per connettersi

Ci sono due modi per autenticare un client AI, ed entrambi sono pienamente supportati:

1. OAuth 2.1 (consigliato) - il classico flusso di consenso "Accedi con TellDone". È quello che usano l'interfaccia dei connettori di Claude Desktop e Claude.ai. Nessun token da copiare: accedi con il tuo account TellDone e approvi i permessi che il client richiede.
2. Bearer token - copia il tuo token di accesso personale dalle Impostazioni e incollalo nella configurazione del client. È il modo più semplice per script, CLI e client che non hanno un flusso OAuth integrato.

Client	Consigliato
Claude Desktop / Cowork	OAuth - aggiungi un connettore personalizzato con l'URL MCP, poi accedi
Claude Code (CLI)	Entrambi - claude mcp add ti guida attraverso OAuth nel browser, oppure aggiungi un header Bearer per il metodo con token
Script o codice tuo	Bearer token - il più semplice da automatizzare
Un client che permette solo di scegliere da una directory di connettori elencati	Per ora usa il bearer token o il bridge mcp-remote: TellDone non è ancora in nessuna directory di connettori

Requisiti del piano

Piano	MCP
Free	Bloccato
Basic	Bloccato
Pro	Read + Write (27 strumenti) - può passare alla modalità Read-only
Ultra	Read + Write (27 strumenti) - può passare alla modalità Read-only

La schermata in-app

La schermata AI Agents ha tre stati a seconda del tuo piano e del fatto che MCP sia attivato.

Bloccato (Free e Basic)

Se sei sul piano Free o Basic, la schermata spiega cosa fa MCP e mostra un pulsante Aggiorna. Toccandolo si apre il paywall dove puoi passare a Pro o Ultra.

Disattivato (Pro e Ultra, funzionalità spenta)

Se sei su Pro o Ultra ma non hai ancora attivato MCP, la schermata mostra un breve riepilogo di cosa può fare il tuo piano (numero di strumenti, modalità di accesso, quote) e un pulsante Attiva. Toccalo per generare il tuo token di connessione e avviare l'integrazione.

Attivato

Una volta attivato, la schermata mostra tutto ciò che ti serve per collegare un client AI:

• Toggle modalità - su Ultra puoi passare tra Read-only e Read + Write. Su Pro la modalità è fissa a Read + Write.
• Riga Access Token con un toggle a forma di occhio per mostrare o nascondere il token e un pulsante di copia.
• Selettore di setup con tab per Claude Code, Cursor, Windsurf e Other. Lo snippet di codice corrispondente appare sotto i tab: basta copiarlo e incollarlo nel tuo client AI.
• Pulsante Rigenera - ruota immediatamente il token e disconnette eventuali sessioni attive che usano quello vecchio.
• Pulsante Disattiva - spegne MCP ed elimina il token. Puoi riattivarlo più tardi, ma verrà emesso un nuovo token.

suggerimento

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

Come attivare

Puoi configurare MCP da entrambe le piattaforme:

• iPhone: Impostazioni → Integrazioni → AI Agents (MCP)
• Web: app.telldone.app → Impostazioni → AI Agents

Passaggi:

1. Tocca Attiva.
2. Scegli la modalità di accesso (solo Ultra: su Pro è sempre Read + Write).
3. Mostra e copia il tuo token usando le icone occhio e copia.
4. Scegli il tuo strumento nella sezione Setup (Claude Code, Cursor, Windsurf o Other).
5. Incolla lo snippet nella configurazione del tuo client AI.

Collegarsi con OAuth

OAuth è il percorso consigliato per Claude Desktop, Claude.ai, Cowork e Claude Code: accedi con il tuo account TellDone invece di copiare un token da una parte all'altra.

URL MCP per OAuth: https://api.telldone.app/mcp/user (senza /mcp finale: quello è un URL diverso, usato solo per il metodo con bearer token qui sotto)

Claude Desktop / Cowork

1. Nel client, scegli Add custom connector.
2. Inserisci l'URL del server: https://api.telldone.app/mcp/user
3. Il client apre la pagina di consenso di TellDone nel tuo browser. Vedrai quale app sta chiedendo l'accesso, i permessi esatti che richiede e un modulo di accesso.
4. Accedi con l'email e la password del tuo account TellDone, poi clicca su Allow.
5. Il client riceve automaticamente un token di accesso e si connette: nessun token da copiare.

nota

L'accesso dalla pagina di consenso usa l'email e la password del tuo account TellDone. Se il tuo account ha solo Apple o Google Sign In (nessuna password impostata), per ora usa il metodo con bearer token qui sotto.

Claude Code

OAuth (apre l'accesso nel browser):

claude mcp add --transport http telldone https://api.telldone.app/mcp/user

Claude Code rileva automaticamente il flusso OAuth, ma non ti fa accedere alla prima chiamata: esegui /mcp dentro Claude Code e scegli Authenticate per aprire l'accesso nel browser. Dopodiché aggiorna il token di accesso per te, senza altra manutenzione.

Bearer token (nessun browser, ideale per configurazioni headless):

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

Ottieni il tuo YOUR_TOKEN dall'app: Impostazioni → Integrazioni → AI Agents → Copia il token (vedi Come attivare sopra).

Collegarsi con un bearer token

Per i client senza supporto OAuth integrato - Cursor, Windsurf e altri - incolla il tuo token di accesso personale direttamente nella configurazione del client. Sostituisci YOUR_TOKEN con il token dalle tue impostazioni in tutti gli esempi qui sotto.

Cursor

Aggiungi a .cursor/mcp.json:

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

Windsurf

Aggiungi a .codeium/windsurf/mcp_config.json:

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

Other

Usa questi snippet per i client che il selettore in-app raggruppa sotto Other.

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 via HTTP può connettersi. 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 (ad esempio, alcuni gateway in stile Smithery), invia il token in X-MCP-Token: YOUR_TOKEN. Funzionano entrambi gli header; se sono entrambi presenti, vince Authorization.

Testare la connessione

Puoi verificare che il 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 riuscita elenca tutti gli strumenti disponibili.

Permessi (scope)

Le connessioni OAuth sono soggette a scope: durante l'accesso vedi esattamente cosa sta chiedendo il client e lo approvi in modo esplicito.

Scope	Permette all'app di...
notes:read	Leggere le tue note, cercare, aprire i dettagli completi di una nota
notes:write	Creare, modificare, eliminare note (ed eseguire la pipeline delle note vocali)
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 i tuoi tag / creare e rinominare tag
profile:read	Leggere le info del tuo profilo e dell'abbonamento
offline_access	Restare connessa anche quando non ci sei (emette un refresh token così non devi accedere a ogni sessione)

Gli scope sono un tetto massimo, non una garanzia: una connessione con solo notes:read non può chiamare uno strumento di scrittura, qualunque cosa tu le chieda di fare. Il tuo piano è un secondo filtro che si aggiunge agli scope.

Le connessioni con bearer token non hanno scope individuali: sono regolate solo dalla modalità read/write del tuo piano.

Cosa puoi fare

Strumenti di lettura (10) - Pro e Ultra

Strumento	Cosa fa
get_notes	Elenca le note con filtri (tag, intervallo di date, ricerca testuale)
get_note	Visualizza una singola nota con le sue attività ed eventi figli e la trascrizione completa
get_notes_full	Ottieni più note con attività ed eventi incorporati in una sola chiamata
get_tasks	Elenca le attività filtrate per stato (to-do, done, all), tag o date
get_events	Elenca gli eventi del calendario, filtra per intervallo di date
get_reports	Leggi i tuoi report giornalieri, settimanali, mensili e annuali (markdown completo)
get_tags	Visualizza tutti i tuoi tag ordinati per uso
get_profile	Vedi le info dell'account e le statistiche d'uso
search	Cerca tra note, attività ed eventi (ricerca testuale + semantica per le note)
get_change_log	Vedi la cronologia delle modifiche di una nota, attività o evento e se ciascuna modifica è stata annullata

suggerimento

Lo strumento search supporta la ricerca semantica per le note: trova risultati per significato, non solo per parole chiave. Ad esempio, cercare "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, ricevi una nota con attività, eventi e tag
create_note	Aggiungi una nota di testo semplice (nessuna analisi AI)
create_task	Aggiungi un'attività con priorità, scadenza, promemoria e tag
create_event	Aggiungi un evento del calendario con data, ora, luogo, promemoria, partecipanti e ricorrenza
update_note	Cambia titolo, riepilogo, tipo, tag, priorità o stato della nota
update_task	Cambia titolo, descrizione, priorità, scadenza, promemoria, tag o stato dell'attività
complete_task	Segna un'attività come fatta
update_event	Cambia dettagli, ora, luogo, promemoria, partecipanti, ricorrenza, tag o stato dell'evento
delete_note	Elimina una nota e tutte le sue attività ed eventi collegati
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	Ripristina una nota, attività o evento eliminato o archiviato
create_tag	Crea un nuovo tag, o trasforma un tag suggerito automaticamente in uno permanente
set_tag_pinned	Fissa o annulla il fissaggio di un tag così che venga ordinato in cima
delete_tag	Rimuovi un tag (può essere ripristinato con restore_tag)
restore_tag	Ripristina un tag eliminato

Tutte le operazioni di scrittura ed eliminazione appaiono istantaneamente sui tuoi dispositivi connessi (telefono, web app) tramite sincronizzazione in tempo reale.

Riferimento degli strumenti

get_notes

Elenca le note con filtraggio opzionale. I filtri di data usano recorded_at (quando hai registrato la nota vocale), non created_at.

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 tag, separati da virgola (corrisponde a uno qualsiasi)
search	string	-	Ricerca testuale su titolo e riepilogo
date_from	string	-	Data di inizio, YYYY-MM-DD (inclusiva)
date_to	string	-	Data di fine, YYYY-MM-DD (esclusiva)
standalone_only	bool	false	Se true, nasconde le note di follow-up (note collegate a una nota, attività o evento superiore) e restituisce solo le note autonome

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

get_note

Ottieni una singola nota con la trascrizione completa e tutte le attività ed 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 di trascrizione etichettati per interlocutore, per le riunioni con più interlocutori - altrimenti null), speaker_count (null a meno che la registrazione non sia stata divisa per interlocutore) e parent_note_id/parent_task_id/parent_event_id (impostati quando questa nota è una modifica di follow-up di un altro elemento). Ogni voce tasks[]/events[] include anche reminders_at/recurrence_rule (attività) o reminder_minutes/attendees/recurrence_rule (eventi).

get_notes_full

Ottieni più note con le loro attività ed eventi in una sola chiamata. Stessi filtri di get_notes, ma 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 tag
date_from	string	-	Data di inizio, YYYY-MM-DD
date_to	string	-	Data di fine, YYYY-MM-DD
standalone_only	bool	false	Se true, nasconde le note di follow-up (note collegate a una nota, attività o evento superiore) e restituisce solo le note autonome

get_tasks

Elenca le attività con filtraggio.

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 tag, separati da virgola
date_from	string	-	Data di inizio, YYYY-MM-DD (filtra per scadenza; le attività senza scadenza sono escluse)
date_to	string	-	Data di fine, YYYY-MM-DD (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 rispecchia la prima voce di reminders_at per retrocompatibilità - usa reminders_at per vedere tutti i promemoria di un'attività.

get_events

Elenca gli eventi del calendario con filtraggio 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	-	Data di inizio, YYYY-MM-DD (filtra per ora di inizio dell'evento)
date_to	string	-	Data di fine, YYYY-MM-DD

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

Ottieni 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 possono essere lunghi 3.000-5.000 parole. Usa limit=1 se il tuo strumento AI ha una finestra di contesto stretta.

get_tags

Ottieni tutti i tuoi tag, ordinati prima per quelli fissati, poi per conteggio d'uso.

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

get_profile

Ottieni le info del tuo account e le statistiche d'uso.

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

search

Cerca tra note, attività ed eventi tutti insieme. Per le note supporta sia la ricerca testuale sia la ricerca semantica (trova risultati per significato usando embedding AI).

Parametro	Tipo	Predefinito	Descrizione
query	string	obbligatorio	Testo di ricerca (max 500 caratteri)
limit	int	20	Risultati massimi 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

Visualizza la cronologia delle modifiche di una nota, attività o evento - ogni modifica di follow-up fatta dall'AI 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	Includi anche le tue modifiche manuali, non solo quelle fatte dall'AI

Restituisce: elenco di voci di modifica con id (usalo come entry_id per l'annullamento), field_name, old_value, new_value, source (follow_up, smart_context o manual), origin_note_id, edited_at e reverted_at (impostato quando la modifica viene annullata).

process_note (Pro e Ultra)

Pipeline AI completa: funziona come la registrazione nell'app. Invia testo o audio e TellDone trascriverà, analizzerà con l'AI e creerà una nota strutturata con attività, eventi, tag ed embedding estratti.

Questo strumento è asincrono: restituisce subito un audio_id ed elabora in background. I risultati arrivano via sincronizzazione in tempo reale ai tuoi dispositivi connessi, oppure puoi fare polling con get_notes().

Parametro	Tipo	Descrizione
text	string	Testo da analizzare (salta la trascrizione se non viene fornito audio)
audio_base64	string	File audio codificato in Base64 (fino a 50 MB, attiva la trascrizione)
audio_format	string	m4a, ogg, wav, mp3, aac o webm (default: m4a)
parent_task_id	string	UUID di un'attività di cui questo è un follow-up
parent_note_id	string	UUID di una nota di cui questo è un follow-up
parent_event_id	string	UUID di un evento di cui questo è un follow-up

Devi fornire o text o audio_base64 (o entrambi: l'audio ha la priorità per la trascrizione).

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

nota

process_note è soggetto alle quote del tuo piano (upload al giorno, note al mese, lunghezza massima del testo). Usa get_profile per controllare l'utilizzo attuale.

create_note (Pro e Ultra)

Crea una nota di testo semplice all'istante. Non attiva l'analisi AI: nessuna attività o evento viene estratto. Per l'analisi AI completa con estrazione di attività/eventi, usa invece process_note.

Parametro	Tipo	Limite	Descrizione
title	string	200 caratteri	Obbligatorio
summary	string	1000 caratteri	Opzionale. Breve teaser (1-3 frasi). Incluso nei prompt dei report, quindi tienilo conciso
transcript	string	per piano	Opzionale. Corpo lungo mostrato nel dettaglio della nota. Non incluso nei report. Limiti: Free 2.000 / Basic 8.000 / Pro 20.000 / Ultra 50.000 caratteri
type	string	-	Opzionale. task, idea, info (default), status, meeting, event o reflection
tags	string	20 tag	Separati da virgola, opzionale

create_task (Pro e Ultra)

Crea una nuova attività.

Parametro	Tipo	Limite	Descrizione
title	string	200 caratteri	Obbligatorio
description	string	2000 caratteri	Opzionale
priority	string	-	low, medium (default) o high
deadline	string	-	YYYY-MM-DD, opzionale
reminder_at	string	-	Datetime ISO 8601 (es. 2026-04-15T09:00:00Z), opzionale
tags	string	20 tag	Separati da virgola, opzionale
note_id	string	-	UUID per collegare l'attività a una nota padre, opzionale

create_event (Pro e Ultra)

Crea un evento del calendario.

Parametro	Tipo	Limite	Descrizione
title	string	200 caratteri	Obbligatorio
start_at	string	-	Datetime ISO 8601, obbligatorio
end_at	string	-	Datetime ISO 8601 (default: inizio + 1 ora)
description	string	2000 caratteri	Opzionale
location	string	200 caratteri	Opzionale
is_all_day	bool	-	Default: false
tags	string	20 tag	Separati da virgola, opzionale
reminder_minutes	string	-	Minuti prima dell'evento separati da virgola (es. 15,60), opzionale
attendees	string	-	Nomi o email separati da virgola, opzionale
recurrence_rule	string	-	Stringa RRULE (es. FREQ=WEEKLY;BYDAY=MO,WE,FR), opzionale
note_id	string	-	UUID per collegare l'evento a una nota padre, opzionale

update_note (Pro e Ultra)

Aggiorna uno o più campi di una nota esistente. Vengono cambiati solo i campi che fornisci.

Parametro	Tipo	Descrizione
note_id	string	Obbligatorio, l'UUID della nota
title	string	Nuovo titolo (max 200 caratteri)
summary	string	Nuovo riepilogo (max 1000 caratteri, passa uno spazio " " per cancellare)
transcript	string	Nuova trascrizione (limite per piano, passa uno spazio " " per cancellare)
type	string	task, idea, info, status, meeting, event o reflection
tags	string	Tag separati da virgola (sostituisce tutti i tag 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 di speech-to-text. Sovrascriverlo sostituisce la fonte canonica: se vuoi preservare l'originale, è meglio aggiungere il testo in coda invece di sostituirlo.

update_task (Pro e Ultra)

Aggiorna uno o più campi di un'attività esistente. Vengono cambiati solo i campi che fornisci.

Parametro	Tipo	Descrizione
task_id	string	Obbligatorio, l'UUID dell'attività
title	string	Nuovo titolo
description	string	Nuova descrizione (passa uno spazio " " per cancellare)
priority	string	low, medium o high
deadline	string	YYYY-MM-DD (passa uno spazio per cancellare)
status	string	todo o done
tags	string	Tag separati da virgola (sostituisce tutti i tag esistenti, max 20)
reminder_at	string	Datetime ISO 8601 (passa uno spazio per cancellare)

Impostando status a done viene anche registrato quando e come l'attività è stata completata.

complete_task (Pro e Ultra)

Scorciatoia per segnare un'attività come fatta.

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.

Parametro	Tipo	Descrizione
event_id	string	Obbligatorio, l'UUID dell'evento
title	string	Nuovo titolo
description	string	Nuova descrizione (passa uno spazio per cancellare)
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 cancellare)
status	string	confirmed, tentative o cancelled
tags	string	Tag separati da virgola (sostituisce tutti i tag esistenti, max 20)
is_all_day	string	"true" o "false"
reminder_minutes	string	Minuti prima dell'evento separati da virgola (es. 15,60)
attendees	string	Nomi o email separati da virgola
recurrence_rule	string	Stringa RRULE (passa uno spazio per cancellare)

delete_note (Pro e Ultra)

Elimina una nota. Questo elimina anche tutte le attività ed eventi creati da questa nota.

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

delete_task (Pro e Ultra)

Elimina un'attività.

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

delete_event (Pro e Ultra)

Elimina un evento.

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

undo_change_log_entry (Pro e Ultra)

Annulla una singola modifica tracciata - ripristina il campo al valore che aveva prima di quella modifica, sia che la modifica sia stata fatta dall'AI (da una registrazione di follow-up) sia direttamente da te.

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à stata annullata.

restore_entity (Pro e Ultra)

Ripristina una nota, attività o evento eliminato o archiviato.

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

Restituisce: l'elemento ripristinato come JSON.

create_tag (Pro e Ultra)

Crea un nuovo tag, o trasforma un tag suggerito automaticamente esistente in uno permanente.

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

set_tag_pinned (Pro e Ultra)

Fissa o annulla il fissaggio di un tag così che venga ordinato in cima al tuo elenco di tag.

Parametro	Tipo	Descrizione
tag	string	Obbligatorio
pinned	bool	Obbligatorio

I tag che contengono un carattere / non possono essere fissati.

delete_tag (Pro e Ultra)

Rimuovi un tag. Può essere ripristinato con restore_tag.

Parametro	Tipo	Descrizione
tag	string	Obbligatorio

restore_tag (Pro e Ultra)

Ripristina un tag eliminato.

Parametro	Tipo	Descrizione
tag	string	Obbligatorio

Limiti di input

Campo	Lunghezza massima	Usato in
title	200 caratteri	create/update note, attività, evento
description	2.000 caratteri	create/update attività, evento
summary	1.000 caratteri (hard)	create/update note. Incluso nei prompt dei report, tenuto corto per controllare il costo dei token
transcript	per piano: Free 2.000 / Basic 8.000 / Pro 20.000 / Ultra 50.000	create/update note. Corpo lungo, non nei report
location	200 caratteri	create/update evento
tags	20 tag	create/update note, attività, evento
query di ricerca	500 caratteri	search
audio_base64 (decodificato)	50 MB	process_note

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

Gestione degli errori

Tutti gli strumenti restituiscono JSON. Gli errori usano questo formato:

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

Errori comuni:

Errore	Quando
"MCP access is read-only..."	Strumento di scrittura chiamato in modalità read-only
"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 attività inesistente o già fatta
"title too long (max 200 chars, got N)"	Limite di input superato
"Too many tags (max 20)"	Più di 20 tag forniti

Errori a livello HTTP:

Codice	Significato
401	Bearer token non valido o mancante
403	MCP disattivato o piano che non consente MCP
429	Limite di velocità superato (5 req/s, burst fino a 20)

Esempi d'uso

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

Lettura dei 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}}}'

Scrittura dei 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 recurring 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 riuscita appare così:

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

nota

Gli strumenti di scrittura e aggiornamento restituiscono risposte minime con solo id, title e status. Per ottenere i dettagli completi (tag, priorità, scadenza, ecc.) dopo una scrittura, fai una chiamata di lettura di follow-up come get_tasks o get_note.

Gestione del token

Azione	Come
Visualizza il token	iPhone Impostazioni → Integrazioni → AI Agents (o Web Impostazioni → AI Agents), tocca l'icona dell'occhio
Copia il token	Tocca l'icona di copia accanto al token
Rigenera	Tocca Rigenera e conferma. Il vecchio token smette di funzionare immediatamente e tutte le sessioni attive si disconnettono
Cambia modalità	Solo Ultra: passa tra Read-only e Read + Write. Su Pro la modalità è fissa a Read + Write
Disattiva	Tocca Disattiva e conferma. Il token viene eliminato e tutte le connessioni si fermano. Puoi riattivare più tardi (verrà emesso un nuovo token)

Cosa puoi chiedere al tuo AI agent

Una volta connesso, 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 in ritardo?"

Gestisci le attività:

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

Cerca e analizza:

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

Pianifica avanti:

• "Crea un evento: standup del team domani alle 10"
• "Cosa ho in calendario questa settimana?"
• "Mostrami i miei top tag: a cosa dedico più tempo?"

L'AI agent ha pieno accesso a note, attività, eventi e report. Può leggere, creare, aggiornare ed eliminare dati e rispondere a domande complesse combinando informazioni da più strumenti.

Note importanti

• Due modi per creare note - create_note crea una nota di testo semplice all'istante (nessuna analisi AI). process_note esegue la pipeline AI completa (come la registrazione nell'app): analizza il testo, estrae attività ed eventi, genera tag ed embedding. Usa process_note quando vuoi che TellDone faccia il lavoro per te.
• Niente sincronizzazione integrazioni - elementi creati o aggiornati via MCP non attivano automazioni webhook o sincronizzazioni di integrazione (Todoist, Notion). Appariranno nelle tue app alla prossima sincronizzazione.
• La ricerca semantica dipende dallo strumento - le note create con process_note ottengono embedding e appaiono nella ricerca semantica. Le note create con create_note non ottengono embedding, quindi appaiono solo nella ricerca testuale.
• Le risposte di scrittura sono minime - gli strumenti di create e update restituiscono solo id, title e status. Per ottenere tutti i campi dopo una scrittura, fai una chiamata di lettura di follow-up.
• I filtri di data usano UTC - i parametri date_from/date_to sono confrontati come timestamp UTC. Per utenti in fusi orari diversi da UTC, le date di confine possono includere o escludere elementi dei giorni adiacenti.
• Rate limit - 5 richieste al secondo, con burst fino a 20. Per operazioni in massa, distribuisci le richieste.

Sicurezza

• Ogni utente riceve un token di connessione univoco a 384 bit
• Il tuo token viene revocato istantaneamente quando disattivi MCP o lo rigeneri
• Tutti i dati sono rigorosamente isolati al tuo account: il tuo agent può accedere solo ai tuoi dati
• Ogni richiesta è scoped al tuo utente: non c'è modo per un agent di accedere ai dati di un altro utente
• La connessione usa HTTPS con rate limiting (5 req/s, burst 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, flusso OAuth completo - consulta il nostro riferimento open source per i connettori su github.com/exp78/telldone-mcp, oppure interroga direttamente https://api.telldone.app/.well-known/oauth-protected-resource.

Privacy e flusso dei dati

I tuoi dati vengono trasmessi a uno strumento AI connesso solo quando gli chiedi esplicitamente di fare qualcosa, ad esempio quando gli chiedi di leggere o modificare le tue note. Lo strumento riceve solo le risposte alle chiamate specifiche che effettua, limitate ai permessi che hai approvato. Il controllo è tuo: puoi cambiare la modalità read/write del tuo piano, restringere gli scope OAuth che approvi al momento dell'accesso, oppure rigenerare e disattivare il tuo bearer token, tutto dalle Impostazioni. Consulta la Privacy Policy per tutti i dettagli, oppure scrivi a support@telldone.app se hai domande.

Risoluzione dei problemi

Sintomo	Causa / soluzione
La pagina di consenso OAuth dice "Wrong email or password"	Usa l'email e la password del tuo account TellDone (quelle con cui accedi all'app). Se il tuo account ha solo Apple o Google Sign In e nessuna password, usa invece il metodo con bearer token.
Connesso, ma l'AI non riesce a creare o modificare niente	Il tuo piano o la modalità sono in sola lettura, oppure alla connessione non sono stati concessi gli scope di scrittura: riconnettiti e approvali, o controlla la modalità nelle Impostazioni.
Errore "Insufficient scope" da uno strumento	Alla connessione OAuth non è stato concesso quello scope. Riconnettiti e approva il permesso che serve allo strumento.
Gli strumenti non compaiono affatto	MCP non è attivo sul tuo account (Impostazioni → AI Agents), oppure il tuo piano non include MCP.
Il mio client mi fa 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 automaticamente i dati a servizi esterni
• Todoist - sincronizzazione bidirezionale dedicata delle attività
• Notion - integrazione Notion dedicata