Acesso MCP (agentes de IA)

O que mudou recentemente

O MCP agora está totalmente disponível no iPhone (além do web app). A tela do iPhone espelha a da web e inclui os mesmos snippets de configuração para todos os clientes de IA suportados.

Plano Pro e superiores

O acesso MCP requer um plano Pro ou Ultra. Os dois planos têm acesso completo de leitura + escrita (27 ferramentas) e podem alternar para o modo somente leitura se preferires.

O MCP (Model Context Protocol) permite conectar assistentes de IA de programação e ferramentas de automação direto aos teus dados do TellDone. Uma vez conectado, o teu agente de IA pode ler as tuas notas, tarefas, eventos, relatórios, tags e histórico de alterações - e criar, atualizar, excluir e restaurar itens. São 27 ferramentas no total: 10 para ler dados e 17 para escrever.

Disponível tanto no app do iPhone (Configurações → Integrações → Agentes de IA) quanto no web app (Configurações → Agentes de IA).

Duas formas de conectar

Há duas formas de autenticar um cliente de IA, e as duas são totalmente suportadas:

1. OAuth 2.1 (recomendado) - o fluxo de consentimento padrão "Entrar com o TellDone". É o que a interface de conectores do Claude Desktop e o Claude.ai usam. Sem copiar tokens - entras com a tua conta TellDone e aprovas as permissões que o cliente está pedindo.
2. Bearer token - copia o teu token de acesso pessoal das Configurações e cola na configuração do teu cliente. É o mais simples para scripts, CLIs e clientes que não têm um fluxo OAuth embutido.

Cliente	Recomendado
Claude Desktop / Cowork	OAuth - adiciona um conector personalizado com a URL do MCP e depois entra na tua conta
Claude Code (CLI)	Qualquer um - o claude mcp add te guia pelo OAuth no navegador, ou adiciona um cabeçalho Bearer para o método por token
Scripts ou o teu próprio código	Bearer token - o mais simples de automatizar
Um cliente que só permite escolher em um diretório de conectores listados	Usa o bearer token ou a ponte mcp-remote por enquanto - o TellDone ainda não está em nenhum diretório de conectores

Requisitos por plano

Plano	MCP
Free	Bloqueado
Basic	Bloqueado
Pro	Leitura + Escrita (27 ferramentas) - pode alternar para modo somente leitura
Ultra	Leitura + Escrita (27 ferramentas) - pode alternar para modo somente leitura

A tela dentro do app

A tela de Agentes de IA tem três estados dependendo do teu plano e se o MCP está ligado.

Bloqueado (Free e Basic)

Se estás no plano Free ou Basic, a tela explica o que o MCP faz e mostra um botão Fazer upgrade. Tocar abre o paywall para ires para o Pro ou Ultra.

Desativado (Pro e Ultra, recurso desligado)

Se estás no Pro ou Ultra mas ainda não ligaste o MCP, a tela mostra um resumo curto do que o teu plano pode fazer (número de ferramentas, modo de acesso, cotas) e um botão Ativar. Toca para gerar o teu token de conexão e iniciar a integração.

Ativado

Uma vez ativado, a tela mostra tudo o que precisas para conectar um cliente de IA:

• Alternador de modo - no Ultra podes trocar entre Somente leitura e Leitura + Escrita. No Pro o modo fica fixo em Leitura + Escrita.
• Linha do Token de acesso com um botão de olho para revelar ou ocultar o token e um botão de copiar.
• Seletor de configuração com abas para Claude Code, Cursor, Windsurf e Outros. O trecho de código correspondente aparece abaixo das abas - basta copiar e colar no teu cliente de IA.
• Botão Regenerar - rotaciona o token imediatamente e desconecta qualquer sessão ativa que estava usando o antigo.
• Botão Desativar - desliga o MCP e exclui o token. Podes reativar depois, mas um novo token será emitido.

dica

Mantém o teu token de conexão em segredo. Qualquer pessoa com o token pode acessar os teus dados do TellDone. Usa Regenerar se suspeitares que o token vazou.

Como ativar

Podes configurar o MCP por qualquer uma das plataformas:

• iPhone: Configurações → Integrações → Agentes de IA (MCP)
• Web: app.telldone.app → Configurações → Agentes de IA

Passos:

1. Toca em Ativar.
2. Escolhe o teu modo de acesso (apenas Ultra - Pro é sempre Leitura + Escrita).
3. Revela e copia o teu token usando os ícones de olho e copiar.
4. Escolhe a tua ferramenta na seção Configuração (Claude Code, Cursor, Windsurf ou Outros).
5. Cola o snippet na configuração do teu cliente de IA.

Conectando com OAuth

O OAuth é o caminho recomendado para Claude Desktop, Claude.ai, Cowork e Claude Code - entras com a tua conta TellDone em vez de ficar copiando token de um lado para o outro.

URL do MCP para OAuth: https://api.telldone.app/mcp/user (sem /mcp no final - essa é outra URL, usada só no caminho por bearer token abaixo)

Claude Desktop / Cowork

1. No cliente, escolhe Add custom connector.
2. Informa a URL do servidor: https://api.telldone.app/mcp/user
3. O cliente abre a página de consentimento do TellDone no teu navegador. Vais ver qual app está pedindo acesso, as permissões exatas que ele quer e um formulário de login.
4. Entra com o e-mail e a senha da tua conta TellDone e clica em Allow.
5. O cliente recebe um token de acesso automaticamente e se conecta - sem token nenhum para copiar.

nota

O login na página de consentimento usa o e-mail e a senha da tua conta TellDone. Se a tua conta só tem Sign In da Apple ou do Google (sem senha definida), usa o método por bearer token abaixo por enquanto.

Claude Code

OAuth (abre um login no navegador):

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

O Claude Code descobre o fluxo OAuth automaticamente, mas não faz o login na primeira chamada - roda /mcp dentro do Claude Code e escolhe Authenticate para abrir o login no navegador. Depois disso ele renova o teu token de acesso sozinho - nada para manter.

Bearer token (sem navegador, bom para ambientes sem interface):

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

Pega o teu YOUR_TOKEN no app: Configurações → Integrações → Agentes de IA → Copiar token (vê Como ativar acima).

Conectando com um bearer token

Para clientes sem suporte a OAuth embutido - Cursor, Windsurf e outros - cola o teu token de acesso pessoal direto na configuração do cliente. Substitui YOUR_TOKEN pelo token das tuas configurações em todos os exemplos abaixo.

Cursor

Adiciona em .cursor/mcp.json:

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

Windsurf

Adiciona em .codeium/windsurf/mcp_config.json:

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

Outros

Usa estes snippets para clientes que o seletor dentro do app agrupa em Outros.

Codex

Adiciona em 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

Outros clientes MCP

Qualquer ferramenta que suporte MCP por HTTP pode se conectar. Usa o endpoint https://api.telldone.app/mcp/user/mcp com um cabeçalho de autorização Bearer YOUR_TOKEN.

Cabeçalho de autenticação alternativo

Se o teu cliente ou proxy reserva o cabeçalho Authorization (por exemplo, alguns gateways estilo Smithery), envia o token em X-MCP-Token: YOUR_TOKEN. Os dois cabeçalhos funcionam; se ambos estiverem presentes, Authorization ganha.

Testando a tua conexão

Podes verificar se o teu token funciona com um comando cURL simples:

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

Uma resposta bem-sucedida lista todas as ferramentas disponíveis.

Permissões (escopos)

As conexões por OAuth têm escopos - durante o login vês exatamente o que o cliente está pedindo e aprovas de forma explícita.

Escopo	Permite ao app...
notes:read	Ler as tuas notas, buscar, abrir os detalhes completos de uma nota
notes:write	Criar, editar e excluir notas (e rodar o pipeline de notas de voz)
tasks:read / tasks:write	Ler / criar, editar, concluir e excluir tarefas
events:read / events:write	Ler / criar, editar e excluir eventos
reports:read	Ler os teus relatórios diários, semanais, mensais e anuais
tags:read / tags:write	Listar as tuas tags / criar e renomear tags
profile:read	Ler o teu perfil e informações de assinatura
offline_access	Continuar conectado quando estiveres fora (emite um refresh token para não precisares de entrar a cada sessão)

Escopos são um teto, não uma garantia - uma conexão só com notes:read não consegue chamar uma ferramenta de escrita, não importa o que peças. O teu plano é uma segunda barreira além dos escopos.

Conexões por bearer token não têm escopos individuais - elas seguem apenas o modo de leitura/escrita do teu plano.

O que podes fazer

Ferramentas de leitura (10) - Pro e Ultra

Ferramenta	O que faz
get_notes	Lista notas com filtros (tags, intervalo de datas, busca de texto)
get_note	Visualiza uma única nota com suas tarefas, eventos e transcrição completa
get_notes_full	Obtém várias notas com tarefas e eventos embutidos em uma chamada
get_tasks	Lista tarefas filtradas por status (a fazer, concluídas, todas), tags ou datas
get_events	Lista eventos do calendário, filtra por intervalo de datas
get_reports	Lê os teus relatórios diários, semanais, mensais e anuais (markdown completo)
get_tags	Vê todas as tuas tags ordenadas por uso
get_profile	Vê informações da tua conta e estatísticas de uso
search	Busca em notas, tarefas e eventos (texto + busca semântica para notas)
get_change_log	Veja o histórico de edições de uma nota, tarefa ou evento, e se cada edição foi desfeita

dica

A ferramenta search suporta busca semântica para notas - ela encontra resultados por significado, não só por palavras-chave. Por exemplo, buscar "reuniões sobre orçamento" vai encontrar notas sobre discussões financeiras mesmo que não contenham a palavra "orçamento".

Ferramentas de escrita (17) - Pro e Ultra

Ferramenta	O que faz
process_note	Pipeline completo de IA - envia texto ou áudio, recebe uma nota com tarefas, eventos e tags
create_note	Adiciona uma nota de texto simples (sem análise de IA)
create_task	Adiciona uma tarefa com prioridade, prazo, lembrete e tags
create_event	Adiciona um evento de calendário com data, horário, local, lembretes, participantes e recorrência
update_note	Muda título, resumo, tipo, tags, prioridade ou status da nota
update_task	Muda título, descrição, prioridade, prazo, lembrete, tags ou status da tarefa
complete_task	Marca uma tarefa como concluída
update_event	Muda detalhes, horário, local, lembretes, participantes, recorrência, tags ou status do evento
delete_note	Exclui uma nota e todas as tarefas e eventos vinculados
delete_task	Exclui uma tarefa
delete_event	Exclui um evento
undo_change_log_entry	Desfaz uma única edição registrada - feita pela IA ou por ti - restaurando o valor anterior do campo
restore_entity	Recupera uma nota, tarefa ou evento excluído ou arquivado
create_tag	Cria uma nova tag, ou transforma uma tag sugerida automaticamente em permanente
set_tag_pinned	Fixa ou desafixa uma tag para que ela vá para o topo
delete_tag	Remove uma tag (pode ser restaurada com restore_tag)
restore_tag	Recupera uma tag excluída

Todas as operações de escrita e exclusão aparecem instantaneamente nos teus dispositivos conectados (celular, web app) via sincronização em tempo real.

Referência das ferramentas

get_notes

Lista notas com filtragem opcional. Filtros de data usam recorded_at (quando gravaste a nota de voz), não created_at.

Parâmetro	Tipo	Padrão	Descrição
limit	int	20	Número de notas a retornar (máx 50)
offset	int	0	Pula esse número de notas (para paginação, máx 10000)
tags	string	-	Filtra por tags, separadas por vírgulas (combina qualquer)
search	string	-	Busca de texto no título e resumo
date_from	string	-	Data de início, YYYY-MM-DD (inclusivo)
date_to	string	-	Data de fim, YYYY-MM-DD (exclusivo)
standalone_only	bool	false	Quando true, oculta notas de acompanhamento (notas vinculadas a uma nota, tarefa ou evento pai) e retorna apenas notas independentes

Retorna: lista de notas com id, title, summary, type, tags, priority, status, recorded_at, created_at.

get_note

Obtém uma única nota com a transcrição completa e todas as tarefas e eventos vinculados.

Parâmetro	Tipo	Descrição
note_id	string	O UUID da nota

Retorna: nota com title, summary, transcript, type, tags, priority, status, metadata, created_at, mais arrays tasks[] e events[].

Também retorna transcript_speakers (turnos da transcrição rotulados por locutor, para reuniões com vários participantes - nulo caso contrário), speaker_count (nulo a menos que a gravação tenha sido dividida por locutor) e parent_note_id/parent_task_id/parent_event_id (definidos quando esta nota é uma edição de continuação de outro item). Cada entrada de tasks[]/events[] também inclui reminders_at/recurrence_rule (tarefas) ou reminder_minutes/attendees/recurrence_rule (eventos).

get_notes_full

Obtém várias notas com suas tarefas e eventos em uma única chamada. Mesmos filtros que get_notes, mas cada nota inclui tasks[] e events[] embutidos.

Parâmetro	Tipo	Padrão	Descrição
limit	int	10	Número de notas (máx 20)
offset	int	0	Pula esse número de notas
tags	string	-	Filtra por tags
date_from	string	-	Data de início, YYYY-MM-DD
date_to	string	-	Data de fim, YYYY-MM-DD
standalone_only	bool	false	Quando true, oculta notas de acompanhamento (notas vinculadas a uma nota, tarefa ou evento pai) e retorna apenas notas independentes

get_tasks

Lista tarefas com filtragem.

Parâmetro	Tipo	Padrão	Descrição
status	string	"todo"	Filtro: todo, done ou all
limit	int	30	Número de tarefas (máx 100)
offset	int	0	Pula esse número de tarefas
tags	string	-	Filtra por tags, separadas por vírgulas
date_from	string	-	Data de início, YYYY-MM-DD (filtra por prazo; tarefas sem prazo são excluídas)
date_to	string	-	Data de fim, YYYY-MM-DD (filtra por prazo; tarefas sem prazo são excluídas)

Retorna: lista de tarefas com id, title, description, status, priority, tags, deadline, reminder_at, reminders_at, completed_at, completed_by, source, created_at. reminder_at espelha a primeira entrada de reminders_at para compatibilidade retroativa - usa reminders_at para ver todos os lembretes de uma tarefa.

get_events

Lista eventos de calendário com filtragem por intervalo de datas.

Parâmetro	Tipo	Padrão	Descrição
limit	int	30	Número de eventos (máx 100)
offset	int	0	Pula esse número de eventos
date_from	string	-	Data de início, YYYY-MM-DD (filtra por horário de início do evento)
date_to	string	-	Data de fim, YYYY-MM-DD

Retorna: lista de eventos com id, title, description, status, start_at, end_at, location, is_all_day, tags, note_id, reminder_minutes, attendees, recurrence_rule, created_at.

get_reports

Obtém os teus relatórios gerados por IA com conteúdo markdown completo.

Parâmetro	Tipo	Padrão	Descrição
report_type	string	"daily"	Tipo: daily, weekly, monthly ou yearly
limit	int	5	Número de relatórios (máx 10)

Retorna: lista de relatórios com id, type, period_start, period_end, content_md, created_at.

nota

Relatórios mensais podem ter 3.000 a 5.000 palavras. Usa limit=1 se a tua ferramenta de IA tem uma janela de contexto apertada.

get_tags

Obtém todas as tuas tags, ordenadas por fixadas primeiro, depois por contagem de uso.

Sem parâmetros. Retorna até 100 tags, cada uma com tag, usage_count, is_pinned, is_manual.

get_profile

Obtém informações da tua conta e estatísticas de uso.

Sem parâmetros. Retorna email, display_name, locale, transcription_locale, timezone, subscription, mcp_mode, created_at e stats (contagens de nota/tarefa/evento).

search

Busca em notas, tarefas e eventos ao mesmo tempo. Para notas, suporta tanto busca de texto quanto busca semântica (encontra resultados por significado usando embeddings de IA).

Parâmetro	Tipo	Padrão	Descrição
query	string	obrigatório	Texto de busca (máx 500 caracteres)
limit	int	20	Máximo de resultados por tipo (máx 20)
semantic	bool	true	Ativa busca semântica para notas

Retorna resultados agrupados por tipo: notes[], tasks[], events[]. Cada resultado tem id, type, title, detail, created_at.

Define semantic=false para busca de texto mais rápida apenas.

get_change_log

Vê o histórico de edições de uma nota, tarefa ou evento - cada edição de continuação feita pela IA e cada edição manual que tu mesmo fizeste, da mais recente para a mais antiga.

Parâmetro	Tipo	Padrão	Descrição
entity	string	obrigatório	notes, tasks ou events
entity_id	string	obrigatório	O UUID do item
include_manual	bool	false	Também inclui as tuas próprias edições manuais, não só as feitas pela IA

Retorna: lista de entradas de alteração com id (usa como entry_id para desfazer), field_name, old_value, new_value, source (follow_up, smart_context ou manual), origin_note_id, edited_at e reverted_at (definido quando desfeito).

process_note (Pro e Ultra)

Pipeline completo de IA - funciona igual a gravar no app. Envia texto ou áudio, e o TellDone vai transcrever, analisar com IA e criar uma nota estruturada com tarefas, eventos, tags e embeddings extraídos.

Esta ferramenta é assíncrona: retorna na hora com um audio_id e processa em segundo plano. Os resultados chegam via sincronização em tempo real aos teus dispositivos conectados, ou podes consultar com get_notes().

Parâmetro	Tipo	Descrição
text	string	Texto a analisar (pula a transcrição se não houver áudio)
audio_base64	string	Arquivo de áudio codificado em base64 (até 50MB, dispara a transcrição)
audio_format	string	m4a, ogg, wav, mp3, aac ou webm (padrão: m4a)
parent_task_id	string	UUID de uma tarefa que isto é continuação
parent_note_id	string	UUID de uma nota que isto é continuação
parent_event_id	string	UUID de um evento que isto é continuação

Deves fornecer text ou audio_base64 (ou os dois - o áudio tem prioridade para transcrição).

Retorna: {"audio_id": "...", "status": "processing", "mode": "text-only"} ou "mode": "audio+stt" se o áudio foi fornecido.

nota

process_note está sujeito às cotas do teu plano (envios por dia, notas por mês, comprimento máximo de texto). Usa get_profile para verificar o teu uso atual.

create_note (Pro e Ultra)

Cria uma nota de texto simples instantaneamente. Não dispara análise de IA - nenhuma tarefa ou evento é extraído. Para análise completa de IA com extração de tarefa/evento, usa process_note.

Parâmetro	Tipo	Limite	Descrição
title	string	200 caracteres	Obrigatório
summary	string	1000 caracteres	Opcional. Teaser curto (1-3 frases). Incluído em prompts de relatório, então mantém conciso
transcript	string	depende do plano	Opcional. Corpo longo exibido nos detalhes da nota. Não incluído em relatórios. Limites: Free 2.000 / Basic 8.000 / Pro 20.000 / Ultra 50.000 caracteres
type	string	-	Opcional. task, idea, info (padrão), status, meeting, event ou reflection
tags	string	20 tags	Separadas por vírgulas, opcional

create_task (Pro e Ultra)

Cria uma nova tarefa.

Parâmetro	Tipo	Limite	Descrição
title	string	200 caracteres	Obrigatório
description	string	2000 caracteres	Opcional
priority	string	-	low, medium (padrão) ou high
deadline	string	-	YYYY-MM-DD, opcional
reminder_at	string	-	ISO 8601 datetime (por exemplo, 2026-04-15T09:00:00Z), opcional
tags	string	20 tags	Separadas por vírgulas, opcional
note_id	string	-	UUID para vincular a tarefa a uma nota pai, opcional

create_event (Pro e Ultra)

Cria um evento de calendário.

Parâmetro	Tipo	Limite	Descrição
title	string	200 caracteres	Obrigatório
start_at	string	-	ISO 8601 datetime, obrigatório
end_at	string	-	ISO 8601 datetime (padrão: início + 1 hora)
description	string	2000 caracteres	Opcional
location	string	200 caracteres	Opcional
is_all_day	bool	-	Padrão: false
tags	string	20 tags	Separadas por vírgulas, opcional
reminder_minutes	string	-	Minutos antes do evento separados por vírgulas (por exemplo, 15,60), opcional
attendees	string	-	Nomes ou e-mails separados por vírgulas, opcional
recurrence_rule	string	-	String RRULE (por exemplo, FREQ=WEEKLY;BYDAY=MO,WE,FR), opcional
note_id	string	-	UUID para vincular o evento a uma nota pai, opcional

update_note (Pro e Ultra)

Atualiza um ou mais campos em uma nota existente. Apenas os campos que forneceres são alterados.

Parâmetro	Tipo	Descrição
note_id	string	Obrigatório, o UUID da nota
title	string	Novo título (máx 200 caracteres)
summary	string	Novo resumo (máx 1000 caracteres, passa um espaço " " para limpar)
transcript	string	Nova transcrição (limite por plano, passa um espaço " " para limpar)
type	string	task, idea, info, status, meeting, event ou reflection
tags	string	Tags separadas por vírgulas (substitui todas as existentes, máx 20)
priority	string	low, medium ou high
status	string	active ou archived

atenção

Para notas criadas pelo pipeline de voz, transcript é a saída original de speech-to-text. Sobrescrever substitui a fonte canônica - considera acrescentar a ela se quiseres preservar o original.

update_task (Pro e Ultra)

Atualiza um ou mais campos em uma tarefa existente. Apenas os campos que forneceres são alterados.

Parâmetro	Tipo	Descrição
task_id	string	Obrigatório, o UUID da tarefa
title	string	Novo título
description	string	Nova descrição (passa um espaço " " para limpar)
priority	string	low, medium ou high
deadline	string	YYYY-MM-DD (passa um espaço para limpar)
status	string	todo ou done
tags	string	Tags separadas por vírgulas (substitui todas as existentes, máx 20)
reminder_at	string	ISO 8601 datetime (passa um espaço para limpar)

Definir status como done também registra quando e como a tarefa foi concluída.

complete_task (Pro e Ultra)

Atalho para marcar uma tarefa como concluída.

Parâmetro	Tipo	Descrição
task_id	string	Obrigatório, o UUID da tarefa

Retorna erro se a tarefa não existe ou já está concluída.

update_event (Pro e Ultra)

Atualiza um ou mais campos em um evento existente. Apenas os campos que forneceres são alterados.

Parâmetro	Tipo	Descrição
event_id	string	Obrigatório, o UUID do evento
title	string	Novo título
description	string	Nova descrição (passa um espaço para limpar)
start_at	string	Novo horário de início (ISO 8601)
end_at	string	Novo horário de fim (ISO 8601)
location	string	Novo local (passa um espaço para limpar)
status	string	confirmed, tentative ou cancelled
tags	string	Tags separadas por vírgulas (substitui todas as existentes, máx 20)
is_all_day	string	"true" ou "false"
reminder_minutes	string	Minutos antes do evento separados por vírgulas (por exemplo, 15,60)
attendees	string	Nomes ou e-mails separados por vírgulas
recurrence_rule	string	String RRULE (passa um espaço para limpar)

delete_note (Pro e Ultra)

Exclui uma nota. Isso também exclui todas as tarefas e eventos criados a partir dessa nota.

Parâmetro	Tipo	Descrição
note_id	string	Obrigatório, o UUID da nota

delete_task (Pro e Ultra)

Exclui uma tarefa.

Parâmetro	Tipo	Descrição
task_id	string	Obrigatório, o UUID da tarefa

delete_event (Pro e Ultra)

Exclui um evento.

Parâmetro	Tipo	Descrição
event_id	string	Obrigatório, o UUID do evento

undo_change_log_entry (Pro e Ultra)

Desfaz uma única edição registrada - restaura o campo ao valor que ele tinha antes daquela edição, seja a edição feita pela IA (a partir de uma gravação de continuação) ou por ti diretamente.

Parâmetro	Tipo	Descrição
entity	string	Obrigatório, notes, tasks ou events
entity_id	string	Obrigatório, o UUID do item
entry_id	string	Obrigatório, o id da entrada de alteração vindo de get_change_log

Retorna: {"entry_id", "entity_type", "entity_id", "field_name", "restored_value", "reverted_at"}. Desfazer a mesma entrada duas vezes retorna um erro - ela já foi desfeita.

restore_entity (Pro e Ultra)

Recupera uma nota, tarefa ou evento excluído ou arquivado.

Parâmetro	Tipo	Descrição
entity	string	Obrigatório, notes, tasks ou events
entity_id	string	Obrigatório, o UUID do item

Retorna: o item restaurado como JSON.

create_tag (Pro e Ultra)

Cria uma nova tag, ou transforma uma tag sugerida automaticamente já existente em permanente.

Parâmetro	Tipo	Descrição
tag	string	Obrigatório, 1-50 caracteres (armazenado em minúsculas)
category	string	Opcional

set_tag_pinned (Pro e Ultra)

Fixa ou desafixa uma tag para que ela fique no topo da tua lista de tags.

Parâmetro	Tipo	Descrição
tag	string	Obrigatório
pinned	bool	Obrigatório

Tags que contêm o caractere / não podem ser fixadas.

delete_tag (Pro e Ultra)

Remove uma tag. Pode ser recuperada com restore_tag.

Parâmetro	Tipo	Descrição
tag	string	Obrigatório

restore_tag (Pro e Ultra)

Recupera uma tag excluída.

Parâmetro	Tipo	Descrição
tag	string	Obrigatório

Limites de entrada

Campo	Comprimento máximo	Usado em
title	200 caracteres	criar/atualizar nota, tarefa, evento
description	2.000 caracteres	criar/atualizar tarefa, evento
summary	1.000 caracteres (rígido)	criar/atualizar nota. Incluído em prompts de relatório, mantido curto para controlar custo de tokens
transcript	depende do plano: Free 2.000 / Basic 8.000 / Pro 20.000 / Ultra 50.000	criar/atualizar nota. Corpo longo, não em relatórios
location	200 caracteres	criar/atualizar evento
tags	20 tags	criar/atualizar nota, tarefa, evento
consulta de busca	500 caracteres	search
audio_base64 (decodificado)	50 MB	process_note

Se excederes um limite, a ferramenta retorna uma mensagem de erro como "title too long (max 200 chars, got 250)".

Tratamento de erros

Todas as ferramentas retornam JSON. Erros usam este formato:

{"error": "descrição do que deu errado"}

Erros comuns:

Erro	Quando
"MCP access is read-only..."	Ferramenta de escrita chamada em modo somente leitura
"Invalid note_id format"	String não-UUID passada como ID
"Note not found"	ID não existe ou pertence a outro usuário
"Task not found or already completed"	complete_task em tarefa inexistente ou já concluída
"title too long (max 200 chars, got N)"	Limite de entrada excedido
"Too many tags (max 20)"	Mais de 20 tags fornecidas

Erros no nível HTTP:

Código	Significado
401	Bearer token inválido ou ausente
403	MCP desativado ou plano não permite MCP
429	Limite de requisições excedido (5 req/s, picos de até 20)

Exemplos de uso

Todos os exemplos usam cURL com o protocolo JSON-RPC do MCP. Substitui YOUR_TOKEN pelo teu token de conexão.

Lendo dados

# Obter seu perfil e estatísticas
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"}}'

# Listar notas recentes (limite 5, de abril de 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"}}}'

# Buscar notas (texto híbrido + semântico)
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":"prazo do projeto","limit":5}}}'

Escrevendo dados (Pro e Ultra)

# Processar uma nota pelo pipeline completo de IA (extrai tarefas + eventos)
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":"Preciso comprar mercado amanhã. Reunião com a Katie às 15h no café para discutir o projeto."}}}'

# Criar uma tarefa com prazo e lembrete
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":"Revisar PR","priority":"high","deadline":"2026-04-15","reminder_at":"2026-04-15T09:00:00Z","tags":"dev"}}}'

# Criar um evento recorrente com lembretes e participantes
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":"Daily do time","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"}}}'

# Concluir uma tarefa
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>"}}}'

Uma resposta bem-sucedida tem esta cara:

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

nota

Ferramentas de escrita e atualização retornam respostas mínimas apenas com id, title e status. Para ver todos os detalhes (tags, prioridade, prazo, etc.) depois de uma escrita, faça uma chamada de leitura subsequente como get_tasks ou get_note.

Gerenciamento de token

Ação	Como
Ver token	Configurações do iPhone → Integrações → Agentes de IA (ou Configurações na web → Agentes de IA), toca no ícone de olho
Copiar token	Toca no ícone de copiar ao lado do token
Regenerar	Toca em Regenerar e confirma. O token antigo para de funcionar na hora e qualquer sessão ativa desconecta
Mudar modo	Só no Ultra - alterna entre Somente leitura e Leitura + Escrita. No Pro o modo fica fixo em Leitura + Escrita
Desativar	Toca em Desativar e confirma. O token é excluído e todas as conexões param. Podes reativar depois (um novo token será emitido)

O que podes pedir ao teu agente de IA

Uma vez conectado, pede ao teu cliente de IA coisas como:

Revê o teu dia:

• "No que trabalhei hoje?"
• "Mostre minhas notas desta semana"
• "Quais tarefas estão atrasadas?"

Gerencia tarefas:

• "Crie uma tarefa: revisar relatório trimestral, alta prioridade, prazo sexta"
• "Marque a tarefa do Figma como concluída"
• "Em quais tarefas estou trabalhando?"

Busca e analisa:

• "Encontre todas as notas sobre a estratégia de marketing"
• "Quais eventos eu tenho na próxima semana?"
• "Resuma meus relatórios diários da semana passada"

Planeja:

• "Crie um evento: daily do time amanhã às 10h"
• "O que tem na minha agenda esta semana?"
• "Mostre minhas tags do topo - no que passo mais tempo?"

O agente de IA tem acesso completo às tuas notas, tarefas, eventos e relatórios. Ele pode ler, criar, atualizar e excluir dados e responder a perguntas complexas combinando informações de várias ferramentas.

Notas importantes

• Duas formas de criar notas - create_note cria uma nota de texto simples instantaneamente (sem análise de IA). process_note roda o pipeline completo de IA (igual a gravar no app) - analisa o texto, extrai tarefas e eventos, gera tags e embeddings. Usa process_note quando quiseres que o TellDone pense por ti.
• Sem sincronização com integrações - itens criados ou atualizados via MCP não disparam automações de webhook nem sincronizações de integração (Todoist, Notion). Eles vão aparecer nos teus apps na próxima sincronização.
• A busca semântica depende da ferramenta - notas criadas com process_note recebem embeddings e aparecem na busca semântica. Notas criadas com create_note não recebem embeddings, então só aparecem na busca por texto.
• As respostas de escrita são mínimas - ferramentas de criação e atualização retornam apenas id, title e status. Para ver todos os campos depois de uma escrita, faça uma chamada de leitura subsequente.
• Filtros de data usam UTC - os parâmetros date_from/date_to são comparados como timestamps UTC. Para usuários em fusos horários diferentes de UTC, datas-limite podem incluir ou excluir itens de dias adjacentes.
• Limite de requisições - 5 requisições por segundo, com picos de até 20. Para operações em lote, espaça as tuas requisições.

Segurança

• Cada usuário recebe um token de conexão único de 384 bits
• O teu token é revogado na hora quando desativas o MCP ou o regeneras
• Todos os dados são estritamente isolados na tua conta - o teu agente só pode acessar os teus próprios dados
• Cada requisição é escopada ao teu usuário - não há jeito de um agente acessar dados de outro usuário
• A conexão usa HTTPS com limite de requisições (5 req/s, picos de até 20)
• As conexões por OAuth usam PKCE com códigos de autorização de uso único e tokens de acesso de curta duração - podes revogar uma conexão a qualquer momento pelo app

Para um mergulho técnico - endpoints de descoberta, tempo de vida dos tokens, o fluxo OAuth completo - vê a nossa referência de conector open source em github.com/exp78/telldone-mcp, ou consulta https://api.telldone.app/.well-known/oauth-protected-resource direto.

Privacidade e fluxo de dados

Os teus dados são transmitidos a uma ferramenta de IA conectada apenas quando lhe pedes algo de forma explícita - por exemplo, quando lhe pedes para ler ou modificar as tuas notas. A ferramenta só recebe as respostas das chamadas específicas que ela faz, limitadas às permissões que aprovaste. Estás no controle: muda o modo de leitura/escrita do teu plano, restringe os escopos OAuth que aprovas no login, ou regenera e desativa o teu bearer token, tudo pelas Configurações. Vê a Política de Privacidade para todos os detalhes, ou fala com support@telldone.app se tiveres dúvidas.

Resolução de problemas

Sintoma	Causa / solução
A página de consentimento do OAuth diz "Wrong email or password"	Usa o e-mail e a senha da tua conta TellDone (a mesma com que entras no app). Se a tua conta só tem Sign In da Apple ou do Google e não tem senha, usa o método por bearer token.
Conectou, mas a IA não consegue criar nem editar nada	O teu plano ou modo está em somente leitura, ou a conexão não recebeu escopos de escrita - reconecta e aprova os escopos, ou confere o teu modo nas Configurações.
Erro "Insufficient scope" vindo de uma ferramenta	A conexão OAuth não recebeu esse escopo. Reconecta e aprova a permissão que a ferramenta precisa.
As ferramentas não aparecem	O MCP não está ativado na tua conta (Configurações → Agentes de IA), ou o teu plano não inclui MCP.
Meu cliente só me deixa escolher em uma lista de conectores e o TellDone não está lá	O TellDone ainda não está no diretório de conectores de nenhum cliente - adiciona como conector personalizado com a URL do MCP, ou usa o método por bearer token.

Vê também

• Automações com webhooks - envia dados para serviços externos automaticamente
• Todoist - sincronização dedicada de tarefas em mão dupla
• Notion - integração dedicada com o Notion