Agentes de IA (MCP)
O MCP funciona em todos os planos. Free e Basic têm acesso somente leitura às 10 ferramentas de leitura (o Free é limitado a 100 solicitações por dia). Pro e Ultra têm acesso completo de leitura e escrita (27 ferramentas) e podem mudar para o modo somente leitura, se preferirem.
O MCP (Model Context Protocol) permite conectar assistentes de IA, como o ChatGPT e o Claude, assistentes de programação e ferramentas de automação diretamente aos seus dados do TellDone. Depois de conectado, o seu assistente pode ler suas notas, tarefas, eventos, relatórios, tags e o histórico de alterações. No Pro ou superior, ele também pode criar, atualizar, excluir e restaurar itens. São 27 ferramentas: 10 de leitura (todos os planos) e 17 de escrita (Pro ou superior).
No iPhone, Configurações > Integrações > Agentes de IA (MCP) abre a tela de configuração do MCP, com o seu token de acesso oculto por padrão:
E na web:
Duas formas de conectar
Há duas formas de conectar um cliente de IA:
- Entrar com o TellDone (OAuth) (recomendado) - você entra com a sua conta do TellDone e aprova o que o app pede. O ChatGPT e o Claude usam esta forma, e não há token para copiar.
- Token bearer - copie o seu token de acesso nas Configurações e cole na configuração do seu cliente. É a forma mais simples para scripts, ferramentas de linha de comando e clientes que não têm um fluxo de OAuth integrado.
| Cliente | Recomendado |
|---|---|
| ChatGPT (chatgpt.com ou o app do ChatGPT para computador, não o app para celular) | OAuth - adicione um servidor MCP personalizado com a URL do MCP e depois entre |
| Claude (site, Desktop, app para iPhone) / Cowork | OAuth - adicione um conector personalizado com a URL do MCP e depois entre |
| Claude Code (CLI) | Token bearer, por enquanto - adicione o cabeçalho Authorization com o seu token |
| Scripts ou o seu próprio código | Token bearer - o mais simples para automatizar |
| Um cliente que só permite escolher em um diretório de conectores listados | Adicione o TellDone como um conector personalizado com a URL do MCP ou use um token bearer. O TellDone ainda não está em nenhum diretório de conectores |
Requisitos de plano
| Plano | MCP |
|---|---|
| Free | Somente leitura (10 ferramentas de leitura), 100 solicitações por dia |
| Basic | Somente leitura (10 ferramentas de leitura), sem limite diário |
| Pro | Leitura e escrita (27 ferramentas) - pode mudar para o modo somente leitura |
| Ultra | Leitura e escrita (27 ferramentas) - pode mudar para o modo somente leitura |
O limite de 100 solicitações por dia no Free conta só as chamadas de ferramentas. Conectar, entrar e listar as ferramentas não contam. O dia segue o fuso horário salvo na sua conta e termina à meia-noite. Quando você atinge o limite, o seu assistente recebe uma mensagem avisando. As ferramentas de escrita são recusadas no Free e no Basic. Com um token de acesso, elas respondem que a conexão é somente leitura e que criar e editar exige o Pro ou superior. Com login (OAuth), a maioria responde "Insufficient scope", porque as conexões do Free e do Basic nunca recebem permissões de escrita.
A tela no app
Abra Configurações > Integrações e, na seção Agentes de IA, toque em Agentes de IA (MCP). A tela diz "Deixe o ChatGPT, o Claude e outros assistentes de IA trabalharem com suas notas, tarefas e eventos do TellDone." e mostra o seu plano:
- Free: "Seu plano: acesso somente leitura, 100 solicitações por dia. A escrita vem com o Pro."
- Basic: "Seu plano: acesso somente leitura"
- Pro e Ultra: "Seu plano: acesso de leitura e escrita"
Enquanto o MCP está desativado, toque em Ativar para ligá-lo.
Depois de ativado, a tela mostra:
- Modo de acesso (Pro e Ultra) - escolha Somente leitura ou Leitura e escrita a qualquer momento.
- Conectar um assistente - passos para o ChatGPT, o Claude e Outro assistente. Você entra no TellDone dentro do assistente, então não é preciso token.
- Aplicativos conectados - os assistentes que você conectou, cada um com um botão Desconectar. Fica vazio até a primeira conexão.
- Para desenvolvedores (recolhido por padrão) - o campo Token de acesso (oculto, com Mostrar / Ocultar e Copiar), Gerar novo token e um seletor Claude Code / Cursor / Outro com texto pronto e o próprio botão Copiar. O Claude Code dá o comando
claude mcp add, o Cursor dá o JSON para.cursor/mcp.jsone Outro lista o endereço do servidor, a opção de login por OAuth e o cabeçalhoAuthorization: Bearer. Enquanto o token está oculto, os trechos mostramYOUR_TOKEN. Toque em Mostrar e eles passam a conter o seu token de verdade.
A web tem os mesmos controles em outro layout, sem a seção recolhida para desenvolvedores: o endereço do OAuth com um botão Copiar, os controles do seu token, Aplicativos conectados com Desconectar e Configuração manual com token bearer com seis opções de cliente (Claude Code, Cursor, Windsurf, Codex, OpenClaw e cURL). Na web, os trechos sempre contêm o seu token de verdade, mesmo com o campo do token oculto, então trate-os como o próprio token.
- Documentação - um link para esta página.
- Desativar - desliga o MCP. Você confirma com "Isso vai revogar o acesso de todas as ferramentas de IA conectadas." Seu token é excluído e todas as conexões param. Se você ativar o MCP de novo, recebe um token novo, e os apps conectados por login (OAuth) voltam a funcionar sem entrar de novo. Para remover um app de vez, toque em Desconectar em Aplicativos conectados.
Mantenha o seu token de acesso em sigilo. Quem tiver o token pode acessar os seus dados do TellDone. Toque em Gerar novo token se suspeitar que ele vazou.
Como ativar
Você pode configurar o MCP em qualquer uma das plataformas:
- iPhone: Configurações > Integrações > Agentes de IA (MCP)
- Web: app.telldone.app > Configurações > Integrações > Agentes de IA (MCP)
Passos:
- Toque em Ativar.
- No Pro e no Ultra, escolha o modo de acesso (Somente leitura ou Leitura e escrita). O Free e o Basic são somente leitura.
- Para conectar o ChatGPT ou o Claude, toque nele em Conectar um assistente e siga os passos (veja abaixo). Não é preciso token.
- Para um cliente de programação no iPhone, abra Para desenvolvedores, toque em Mostrar, escolha Claude Code, Cursor ou Outro e toque em Copiar abaixo do trecho. Se você copiar antes de tocar em Mostrar, o trecho traz
YOUR_TOKENno lugar do seu token. Na web, escolha o seu cliente em Configuração manual com token bearer e copie o trecho; ele já contém o seu token. - Cole o trecho no seu cliente ou no arquivo de configuração dele.
Conectar com OAuth
O OAuth é o caminho recomendado para o ChatGPT, o Claude e o Cowork - você entra com a sua conta do TellDone em vez de copiar um token.
URL do MCP para OAuth: https://api.telldone.app/mcp/user
O mesmo servidor também responde em https://api.telldone.app/mcp/user/mcp, e os dois endereços aceitam um token bearer. Para o login por OAuth, use o primeiro.
ChatGPT
Você pode adicionar um servidor MCP personalizado em chatgpt.com ou no app do ChatGPT para computador. O app do ChatGPT para celular não adiciona conectores personalizados, e o app do TellDone diz assim: "O aplicativo do ChatGPT só adiciona conectores do próprio catálogo." Toque em Enviar os passos para o meu computador no TellDone para receber as instruções em um computador. Depois de adicionado lá, o TellDone também fica disponível no app do ChatGPT para celular.
Os passos no app:
- Em um computador, abra chatgpt.com/plugins, clique em Add e escolha Add custom MCP server.
- Dê o nome TellDone, cole o endereço abaixo (
https://api.telldone.app/mcp/user) e escolha OAuth. - Confirme e instale, depois entre no TellDone e permita o acesso.
Veja o guia da OpenAI sobre servidores MCP personalizados se os nomes dos menus mudarem.
Claude (site, Desktop, app para iPhone) / Cowork
Os passos no app:
- No Claude, abra Customize → Connectors e toque em Add custom connector.
- Cole o endereço abaixo (
https://api.telldone.app/mcp/user). - Entre no TellDone e permita o acesso.
Quando você entra, a página de consentimento do TellDone mostra qual app está pedindo acesso e as permissões exatas que ele quer. Entre com o seu email e a sua senha do TellDone e clique em Allow access, ou toque em Entrar com a Apple ou Entrar com o Google, que aprova o acesso na mesma etapa. O Claude se conecta sozinho - não há token para copiar.
Se os nomes dos menus mudarem, veja o guia da Anthropic sobre como adicionar um conector personalizado.
Conectar com um token bearer
Para o Claude Code, o Cursor e outros clientes sem login por OAuth integrado, cole o seu token de acesso direto na configuração do cliente. Em todos os exemplos abaixo, troque YOUR_TOKEN pelo token dos seus ajustes.
Claude Code (token bearer)
claude mcp add --transport http telldone \
https://api.telldone.app/mcp/user/mcp \
--header "Authorization: Bearer YOUR_TOKEN"
Você não precisa digitar isso: em Configurações > Integrações > Agentes de IA (MCP) > Para desenvolvedores, toque em Mostrar, escolha Claude Code e toque em Copiar. O comando copiado já contém o seu token.
Cursor
Adicione a .cursor/mcp.json (ou copie em Para desenvolvedores > Cursor depois de tocar em Mostrar):
{
"mcpServers": {
"telldone": {
"url": "https://api.telldone.app/mcp/user/mcp",
"headers": { "Authorization": "Bearer YOUR_TOKEN" }
}
}
}
Outros clientes
Configurações para outros clientes MCP:
Codex
Adicione 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
Outros clientes MCP
Qualquer ferramenta que aceite MCP por HTTP pode se conectar. Use o endpoint https://api.telldone.app/mcp/user/mcp com um cabeçalho de autorização Bearer YOUR_TOKEN.
Se o seu cliente ou proxy reserva o cabeçalho Authorization (por exemplo, alguns gateways no estilo Smithery), envie o token em X-MCP-Token: YOUR_TOKEN. Os dois cabeçalhos funcionam; se os dois estiverem presentes, o Authorization prevalece.
Testar a conexão
Você pode conferir se o seu 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 você vê exatamente o que o cliente está pedindo e o aprova de forma explícita.
| Escopo | Permite que o app... |
|---|---|
notes:read | Ler suas notas e abrir os detalhes completos de uma nota (a ferramenta search também precisa de tasks:read e events:read) |
notes:write | Criar, editar e excluir notas (process_note também precisa de tasks:write e events:write) |
tasks:read / tasks:write | Ler / criar, editar, concluir e excluir tarefas |
events:read / events:write | Ler / criar, editar e excluir eventos |
reports:read | Ler seus relatórios diários, semanais, mensais e anuais |
tags:read / tags:write | Listar suas tags / criar, fixar, excluir e restaurar tags |
profile:read | Ler as informações da sua conta e a assinatura |
offline_access | Continuar conectado (emite um refresh token para você não precisar entrar de novo a cada sessão) |
Os escopos limitam o que uma conexão pode fazer: uma conexão só com notes:read não consegue chamar uma ferramenta de escrita. O seu plano define um segundo limite, além desse.
As conexões por token bearer não têm escopos individuais - elas são regidas só pelo modo de leitura e escrita do seu plano.
O que você pode fazer
Ferramentas de leitura (10) - todos os planos
| Ferramenta | O que faz |
|---|---|
| get_notes | Lista notas com filtros (tags, intervalo de datas, busca por texto) |
| get_note | Mostra uma única nota com as tarefas, os eventos e a transcrição completa dela |
| get_notes_full | Obtém várias notas com tarefas e eventos incorporados em uma só chamada |
| get_tasks | Lista tarefas filtradas por status (a fazer, concluídas, todas), tags ou datas |
| get_events | Lista eventos de calendário, com filtro por intervalo de datas |
| get_reports | Lê seus relatórios diários, semanais, mensais e anuais (markdown completo) |
| get_tags | Mostra todas as suas tags, ordenadas por uso |
| get_profile | Mostra as informações da sua conta e quantas notas, tarefas e eventos você tem |
| search | Busca em notas, tarefas e eventos (texto + busca semântica para notas) |
| get_change_log | Mostra o histórico de edições de uma nota, tarefa ou evento e se cada edição foi desfeita |
A ferramenta search aceita busca semântica para notas - ela encontra resultados pelo sentido, não só por palavras-chave. Por exemplo, buscar "reuniões sobre orçamento" encontra notas sobre discussões financeiras mesmo que elas não contenham a palavra "orçamento".
Ferramentas de escrita (17) - Pro e Ultra
| Ferramenta | O que faz |
|---|---|
| process_note | Pipeline completo de IA - envie texto ou áudio e receba 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, hora, local, lembretes, participantes e regra de repetição |
| update_note | Altera o título, o resumo, o tipo, as tags, a prioridade ou o status da nota |
| update_task | Altera o título, a descrição, a prioridade, o prazo, o lembrete, as tags ou o status da tarefa |
| complete_task | Marca uma tarefa como concluída |
| update_event | Altera os detalhes, o horário, o local, os lembretes, os participantes, a regra de repetição, as tags ou o status do evento |
| delete_note | Exclui uma nota. As tarefas e os eventos dela continuam |
| 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 você - e restaura o valor anterior do campo |
| restore_entity | Traz de volta uma nota ou tarefa excluída ou arquivada, ou um evento excluído ou cancelado |
| create_tag | Cria uma tag nova ou transforma uma tag sugerida automaticamente em permanente |
| set_tag_pinned | Fixa ou desafixa uma tag para ela ir para o topo |
| delete_tag | Remove uma tag (pode ser restaurada com restore_tag) |
| restore_tag | Traz de volta uma tag excluída |
Todas as operações de escrita e exclusão aparecem na hora nos seus dispositivos conectados (celular, app web).
Referência das ferramentas
get_notes
Lista notas com filtros opcionais. Os filtros de data usam recorded_at (quando você gravou a nota de voz) ou created_at, para uma nota que não tem esse campo.
| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
limit | int | 20 | Número de notas a retornar (máx. 50) |
offset | int | 0 | Pula esta quantidade de notas (para paginação, máx. 10000) |
tags | string | - | Filtra por tags, separadas por vírgula (corresponde a qualquer uma) |
search | string | - | Busca por texto no título e no resumo |
date_from | string | - | Data inicial, AAAA-MM-DD (inclusiva) |
date_to | string | - | Data final, AAAA-MM-DD (exclusiva) |
standalone_only | bool | false | Quando true, oculta as notas de complemento (notas anexadas a uma nota, tarefa ou evento pai) e retorna só as 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 ligados a ela.
| 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, além das listas tasks[] e events[].
Também retorna transcript_speakers (turnos da transcrição com o falante identificado, para reuniões com vários falantes - null nos outros casos), speaker_count (null, a menos que a gravação tenha sido dividida por falante) e parent_note_id/parent_task_id/parent_event_id (definidos quando esta nota é uma edição de complemento 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 as tarefas e os eventos delas em uma só chamada. Os mesmos filtros de get_notes, exceto search, e cada nota inclui tasks[] e events[] incorporados.
| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
limit | int | 10 | Número de notas (máx. 20) |
offset | int | 0 | Pula esta quantidade de notas |
tags | string | - | Filtra por tags |
date_from | string | - | Data inicial, AAAA-MM-DD |
date_to | string | - | Data final, AAAA-MM-DD |
standalone_only | bool | false | Quando true, oculta as notas de complemento (notas anexadas a uma nota, tarefa ou evento pai) e retorna só as notas independentes |
get_tasks
Lista tarefas com filtros.
| 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 esta quantidade de tarefas |
tags | string | - | Filtra por tags, separadas por vírgula |
date_from | string | - | Data inicial, AAAA-MM-DD (filtra pelo prazo; tarefas sem prazo ficam de fora) |
date_to | string | - | Data final, AAAA-MM-DD (filtra pelo prazo; tarefas sem prazo ficam de fora) |
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 o primeiro item de reminders_at por compatibilidade com versões anteriores - use reminders_at para ver todos os lembretes de uma tarefa.
get_events
Lista eventos de calendário com filtro 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 esta quantidade de eventos |
date_from | string | - | Primeiro dia, AAAA-MM-DD, no seu próprio fuso horário (inclusivo). Os eventos que se sobrepõem ao intervalo são incluídos, então um evento de vários dias aparece em todos os dias que cobre |
date_to | string | - | Último dia, AAAA-MM-DD, no seu próprio fuso horário (inclusivo) |
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 seus relatórios gerados pela IA com o conteúdo completo em markdown.
| 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.
Os relatórios mensais são longos (em geral bem mais de 1.000 palavras). Use limit=1 se a sua ferramenta de IA tiver uma janela de contexto apertada.
get_tags
Obtém todas as suas tags, ordenadas primeiro pelas fixadas e depois pela quantidade de usos.
Sem parâmetros. Retorna até 100 tags, cada uma com tag, usage_count, is_pinned, is_manual.
get_profile
Obtém as informações da sua conta e quantas notas, tarefas e eventos você tem.
Sem parâmetros. Retorna email, display_name, locale, transcription_locale, timezone, subscription, mcp_mode, created_at e stats (contagens de notas, tarefas e eventos).
search
Busca em notas, tarefas e eventos de uma vez. Para notas, aceita busca por texto e busca semântica (encontra resultados pelo sentido, usando embeddings de IA).
| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
query | string | obrigatório | Texto da busca (máx. 500 caracteres) |
limit | int | 20 | Máximo de resultados por tipo (máx. 20) |
semantic | bool | true | Ativa a busca semântica para notas |
Retorna os resultados agrupados por tipo: notes[], tasks[], events[]. Cada resultado tem id, type, title, detail, created_at.
Defina semantic=false para uma busca só por texto, mais rápida.
get_change_log
Mostra o histórico de edições de uma nota, tarefa ou evento - toda edição de complemento feita pela IA e toda edição manual que você mesmo fez, 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 | Inclui também as suas edições manuais, não só as feitas pela IA |
Retorna: lista de entradas de alteração com id (use como entry_id para desfazer), field_name, old_value, new_value, source (follow_up, smart_context, correction_sync para a correção de um nome que o TellDone levou para outra nota, ou manual), origin_note_id, edited_at e reverted_at (definido depois de desfeita).
process_note (Pro e Ultra)
Pipeline completo de IA - funciona igual a gravar no app. Envie texto ou áudio, e o TellDone transcreve, analisa com IA e cria uma nota estruturada com as tarefas, os eventos, as tags e os embeddings extraídos.
Esta ferramenta é assíncrona: ela retorna na hora com um audio_id e processa em segundo plano. Os resultados chegam por sincronização em tempo real aos seus dispositivos conectados, ou você pode consultar com get_notes().
| Parâmetro | Tipo | Descrição |
|---|---|---|
text | string | Obrigatório. Texto a analisar. Se não estiver vazio, é usado como a transcrição e qualquer áudio enviado não é transcrito; envie "" para o áudio ser transcrito. Limite quando nenhum áudio é enviado: Pro 20.000 / Ultra 50.000 caracteres |
audio_base64 | string | Arquivo de áudio codificado em Base64. A requisição inteira é limitada a 10 MB, então o áudio em si pode ter cerca de 7 MB. Ele só é transcrito quando text está vazio |
audio_format | string | m4a, ogg, wav, mp3, aac ou webm (padrão: m4a) |
parent_task_id | string | UUID de uma tarefa da qual esta é um complemento |
parent_note_id | string | UUID de uma nota da qual esta é um complemento |
parent_event_id | string | UUID de um evento do qual esta é um complemento |
Envie sempre text. Para o TellDone transcrever o áudio, envie audio_base64 com text definido como uma string vazia (""). Se text não estiver vazio, o TellDone o usa como a transcrição e não transcreve o áudio. Defina no máximo um dos três IDs pai.
Retorna: {"audio_id": "...", "status": "processing", "mode": "text-only"} ou "mode": "audio+stt" se o áudio foi enviado.
O process_note está sujeito às cotas do seu plano (envios por dia, notas por mês, tamanho máximo do texto). O get_profile mostra só quantas notas, tarefas e eventos você tem, não os seus limites. Confira o seu uso no app em Configurações > Uso.
create_note (Pro e Ultra)
Cria uma nota de texto simples na hora. Não dispara análise de IA - nenhuma tarefa nem evento é extraído. Use process_note quando quiser que o TellDone encontre tarefas e eventos para você.
| Parâmetro | Tipo | Limite | Descrição |
|---|---|---|---|
title | string | 200 caracteres | Obrigatório |
summary | string | 1000 caracteres | Opcional. Resumo curto (1 a 3 frases). Usado nos seus relatórios, então mantenha curto |
transcript | string | conforme o plano | Opcional. Corpo longo mostrado nos detalhes da nota. Não entra nos relatórios. Limites: 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írgula, opcional |
suppress_external_sync | boolean | - | Opcional, padrão false. Defina como true para itens importados ou em massa: assim o item não é enviado aos seus apps conectados nem às suas automações |
create_task (Pro e Ultra)
Cria uma tarefa nova. A tarefa também é criada no Todoist, no Notion ou no Microsoft To Do que você conectou, e as suas automações recebem task.created. Isso não acontece quando você envia suppress_external_sync: true.
| 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 | - | AAAA-MM-DD, opcional |
reminder_at | string | - | Data e hora ISO 8601 (por exemplo 2026-04-15T09:00:00Z), opcional |
tags | string | 20 tags | Separadas por vírgula, opcional |
note_id | string | - | UUID para ligar a tarefa a uma nota pai, opcional |
suppress_external_sync | boolean | - | Opcional, padrão false. Defina como true para itens importados ou em massa: assim o item não é enviado aos seus apps conectados nem às suas automações |
create_event (Pro e Ultra)
Cria um evento de calendário. O evento também é criado no Notion que você conectou, e as suas automações recebem calendar_event.created. Isso não acontece quando você envia suppress_external_sync: true.
| Parâmetro | Tipo | Limite | Descrição |
|---|---|---|---|
title | string | 200 caracteres | Obrigatório |
start_at | string | - | Data e hora ISO 8601, obrigatório |
end_at | string | - | Data e hora ISO 8601 (padrão: início + 1 hora; em um evento de dia inteiro, um dia) |
description | string | 2000 caracteres | Opcional |
location | string | 200 caracteres | Opcional |
is_all_day | bool | - | Padrão: false |
tags | string | 20 tags | Separadas por vírgula, opcional |
reminder_minutes | string | - | Minutos antes do evento, separados por vírgula (por exemplo 15,60), opcional |
attendees | string | - | Nomes ou emails separados por vírgula, opcional |
recurrence_rule | string | - | String RRULE (por exemplo FREQ=WEEKLY;BYDAY=MO,WE,FR), opcional. Regras mais frequentes que a cada hora, ou que nunca podem acontecer, são recusadas |
note_id | string | - | UUID para ligar o evento a uma nota pai, opcional |
suppress_external_sync | boolean | - | Opcional, padrão false. Defina como true para itens importados ou em massa: assim o item não é enviado aos seus apps conectados nem às suas automações |
update_note (Pro e Ultra)
Atualiza um ou mais campos de uma nota existente. Só os campos que você informar são alterados. Funciona exatamente como editar a nota no app: o título, o resumo, as tags e o tipo chegam à página dela no Notion, as suas automações recebem note.updated, e a edição aparece no histórico, onde pode ser desfeita. Uma alteração na transcrição também é salva e enviada ao Notion, mas não aparece no histórico.
| 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, envie um espaço " " para limpar) |
transcript | string | Nova transcrição (limite conforme o plano, envie um espaço " " para limpar) |
type | string | task, idea, info, status, meeting, event ou reflection |
tags | string | Tags separadas por vírgula (substitui todas as tags existentes, máx. 20) |
priority | string | low, medium ou high |
status | string | active ou archived |
Nas notas criadas pelo pipeline de voz, transcript é o resultado original da transcrição de fala. Sobrescrevê-lo substitui as suas palavras originais. Para mantê-las, acrescente à transcrição em vez de substituí-la.
update_task (Pro e Ultra)
Atualiza um ou mais campos de uma tarefa existente. Só os campos que você informar são alterados. Funciona exatamente como editar a tarefa no app: a alteração chega às cópias dela no Todoist, no Notion e no Microsoft To Do, as suas automações recebem task.updated, e a edição aparece no histórico da tarefa, onde pode ser desfeita. Definir status como done conclui a tarefa do mesmo jeito que o complete_task. O prazo pode ser uma data ou uma data com horário (só a data é usada). Cada tag pode ter até 50 caracteres.
| Parâmetro | Tipo | Descrição |
|---|---|---|
task_id | string | Obrigatório, o UUID da tarefa |
title | string | Novo título |
description | string | Nova descrição (envie um espaço " " para limpar) |
priority | string | low, medium ou high |
deadline | string | AAAA-MM-DD. Esta ferramenta não consegue limpar um prazo; limpe-o no app |
status | string | todo ou done |
tags | string | Tags separadas por vírgula (substitui todas as tags existentes, máx. 20) |
reminder_at | string | Data e hora ISO 8601 (envie 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 um erro se a tarefa não existir ou já estiver concluída.
update_event (Pro e Ultra)
Atualiza um ou mais campos de um evento existente. Só os campos que você informar são alterados. Funciona exatamente como editar o evento no app: a alteração chega à página dele no Notion, as suas automações recebem calendar_event.updated, e a edição aparece no histórico, onde pode ser desfeita.
| Parâmetro | Tipo | Descrição |
|---|---|---|
event_id | string | Obrigatório, o UUID do evento |
title | string | Novo título |
description | string | Nova descrição (envie 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 (envie um espaço para limpar) |
status | string | confirmed, tentative ou cancelled |
tags | string | Tags separadas por vírgula (substitui todas as tags existentes, máx. 20) |
is_all_day | string | "true" ou "false" |
reminder_minutes | string | Minutos antes do evento, separados por vírgula (por exemplo 15,60, envie um espaço para limpar) |
attendees | string | Nomes ou emails separados por vírgula (envie um espaço para limpar) |
recurrence_rule | string | String RRULE (envie um espaço para limpar) |
delete_note (Pro e Ultra)
Exclui uma nota. Só a nota é excluída: as tarefas e os eventos dela continuam. Funciona exatamente como excluir no app: as suas automações recebem note.deleted. Uma cópia da nota no Notion não é removida (o app também não a remove).
| Parâmetro | Tipo | Descrição |
|---|---|---|
note_id | string | Obrigatório, o UUID da nota |
delete_task (Pro e Ultra)
Exclui uma tarefa. Funciona exatamente como excluir no app: as cópias dela no Todoist, no Notion e no Microsoft To Do também são excluídas, e as suas automações recebem task.deleted. Traga-a de volta com restore_entity.
| Parâmetro | Tipo | Descrição |
|---|---|---|
task_id | string | Obrigatório, o UUID da tarefa |
delete_event (Pro e Ultra)
Exclui um evento. Funciona exatamente como excluir no app: as suas automações recebem calendar_event.deleted. A página do evento no Notion não é removida (o app também não a remove).
| 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 tinha antes dessa edição, seja ela feita pela IA (a partir de uma gravação de complemento) ou por você 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 em 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)
Traz de volta uma nota ou tarefa excluída ou arquivada, ou um evento excluído ou cancelado.
| 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 em JSON.
create_tag (Pro e Ultra)
Cria uma tag nova ou transforma uma tag existente sugerida automaticamente em permanente.
| Parâmetro | Tipo | Descrição |
|---|---|---|
tag | string | Obrigatório, de 1 a 50 caracteres (guardada em minúsculas) |
category | string | Opcional |
set_tag_pinned (Pro e Ultra)
Fixa ou desafixa uma tag para ela ir para o topo da sua 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 trazida de volta com restore_tag.
| Parâmetro | Tipo | Descrição |
|---|---|---|
tag | string | Obrigatório |
restore_tag (Pro e Ultra)
Traz de volta uma tag excluída.
| Parâmetro | Tipo | Descrição |
|---|---|---|
tag | string | Obrigatório |
Limites de entrada
| Campo | Tamanho 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. Usado nos seus relatórios, então mantenha curto |
| transcript | conforme o plano: Pro 20.000 / Ultra 50.000 | criar/atualizar nota. Corpo longo, não entra nos relatórios |
| text | conforme o plano: Pro 20.000 / Ultra 50.000 (quando nenhum áudio é enviado) | process_note |
| location | 200 caracteres | criar/atualizar evento |
| tags | 20 tags | criar/atualizar nota, tarefa, evento |
| search query | 500 caracteres | search |
| audio_base64 | cerca de 7 MB de áudio (a requisição inteira é limitada a 10 MB) | process_note |
Se você passar de um limite, a ferramenta retorna uma mensagem de erro como "title too long (max 200 chars, got 250)".
Tratamento de erros
A maioria das ferramentas retorna os erros em JSON:
{"error": "description of what went wrong"}
Os erros de plano, de escopo e de limite de entrada voltam como um erro da ferramenta com a mesma mensagem.
Erros comuns:
| Erro | Quando |
|---|---|
"This TellDone connection is read-only. Creating and editing needs the Pro or Ultra plan." | Ferramenta de escrita chamada no modo somente leitura (Free e Basic, ou Pro e Ultra no modo somente leitura) |
"Daily limit reached: the Free plan includes 100 TellDone requests a day..." | O plano Free usou as 100 solicitações do dia |
"Daily limit reached (N/M today)" | Você criou hoje, por meio de assistentes de IA, tantos itens quanto o seu plano permite (process_note, create_note, create_task e create_event contam cada um) |
"Notes limit reached (X/Y this month)" | O limite mensal de notas do seu plano foi usado |
"Invalid note_id format" | String que não é um UUID passada como ID |
"Note not found" | O ID não existe ou pertence a outro usuário |
"Task not found or already completed" | complete_task em uma 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 informadas |
Erros no nível de HTTP:
| Código | Significado |
|---|---|
| 401 | Token inválido, revogado ou excluído (desativar o MCP exclui o seu token, e gerar um novo o substitui) |
| 429 | Limite de taxa excedido (5 req/s, picos de até 20) |
No Free, atingir o limite de 100 solicitações por dia é informado como uma mensagem de erro da ferramenta (não como um código HTTP) e é zerado à meia-noite no fuso horário salvo na sua conta.
Exemplos de uso
Todos os exemplos usam cURL com o protocolo JSON-RPC do MCP. Troque YOUR_TOKEN pelo seu token de acesso.
Ler dados
# 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}}}'
Gravar dados (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>"}}}'
Uma resposta bem-sucedida é assim:
{
"jsonrpc": "2.0",
"id": 11,
"result": {
"content": [{"type": "text", "text": "{\"id\":\"...\",\"title\":\"Review PR\",\"status\":\"todo\"}"}]
}
}
As ferramentas de escrita e de atualização retornam respostas curtas, principalmente id, title e status. As ferramentas de exclusão retornam id e deleted. Para ver os detalhes completos (tags, prioridade, prazo etc.) depois de uma escrita, faça uma chamada de leitura em seguida, como get_tasks ou get_note.
Gerenciar o token
| Ação | Como |
|---|---|
| Ver o token | No iPhone, Configurações > Integrações > Agentes de IA (MCP) > Para desenvolvedores (ou, na web, Configurações > Integrações > Agentes de IA (MCP)), toque em Mostrar |
| Copiar o token | Toque em Copiar ao lado do token |
| Gerar um novo | Toque em Gerar novo token e confirme. O token antigo para de funcionar na hora. Os assistentes conectados por login com OAuth não são afetados; desconecte-os em Aplicativos conectados |
| Mudar o modo | Pro e Ultra: escolha Somente leitura ou Leitura e escrita. O Free e o Basic são sempre somente leitura |
| Desativar | Toque em Desativar e confirme ("Isso vai revogar o acesso de todas as ferramentas de IA conectadas."). Seu token é excluído e todas as conexões param. Se você ativar o MCP de novo, recebe um token novo, e os apps conectados por login (OAuth) voltam a funcionar sem entrar de novo. Para remover um app de vez, toque em Desconectar em Aplicativos conectados |
O que você pode pedir ao seu agente de IA
Depois de conectar, peça à sua ferramenta de IA coisas como:
Revise o seu dia:
- "No que eu trabalhei hoje?"
- "Mostre minhas notas desta semana"
- "Quais tarefas estão atrasadas?"
Gerenciar tarefas:
- "Crie uma tarefa: revisar o relatório trimestral, prioridade alta, prazo sexta-feira"
- "Marque a tarefa do Figma como concluída"
- "Em quais tarefas estou trabalhando?"
Buscar e analisar:
- "Encontre todas as notas sobre a estratégia de marketing"
- "Quais eventos eu tenho na semana que vem?"
- "Resuma meus relatórios diários da semana passada"
Planejar o futuro:
- "Crie um evento: reunião de equipe amanhã às 10h"
- "O que tem na minha agenda esta semana?"
- "Mostre minhas principais tags - em que eu gasto mais tempo?"
Seu assistente pode ler suas notas, tarefas, eventos e relatórios e responder a perguntas complexas combinando informações de várias ferramentas. No Pro e no Ultra, com Leitura e escrita ativada, ele também pode criá-los, atualizá-los e excluí-los.
Bom saber
- Integrações e automações - o
process_notefunciona como uma gravação, então a nota, as tarefas e os eventos dele vão para as suas integrações conectadas e automações por webhook. Os itens que você cria, edita ou exclui com as outras ferramentas de escrita se comportam exatamente como no app: chegam às suas integrações conectadas (os eventos e as edições de notas só chegam ao Notion) e às suas automações. Restaurar uma tarefa comrestore_entity, ou desfazer a conclusão dela comundo_change_log_entry, também a reabre nas integrações com as quais ela foi sincronizada. - Edições feitas por um assistente de IA - ficam marcadas no histórico do item como feitas por um assistente. Elas não são usadas para ensinar o reconhecimento de fala do TellDone e não são copiadas para os outros itens da nota. As edições feitas por um assistente contam no mesmo limite do app, de 30 edições por minuto.
- Busca semântica - as notas criadas com
process_noteoucreate_noterecebem embeddings, então aparecem na busca semântica depois de um breve atraso. - Filtros de data - para notas, as datas são dias em UTC. Para eventos, as datas são os seus dias locais, e um evento que se sobrepõe ao intervalo é incluído. Para tarefas, o filtro é a data do prazo.
Segurança
- Cada usuário recebe um token de acesso único de 384 bits
- Seu token é revogado na hora quando você desativa o MCP ou gera um novo
- Toda requisição é restrita à sua conta, então o seu agente só acessa os seus próprios dados
- A conexão usa HTTPS com limite de taxa (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 - você pode revogar uma conexão a qualquer momento no app
Para um aprofundamento técnico - endpoints de descoberta, duração dos tokens, o fluxo completo de OAuth - veja nossa referência open source do conector em github.com/exp78/telldone-mcp ou consulte https://api.telldone.app/.well-known/oauth-protected-resource diretamente.
Privacidade e fluxo de dados
Uma ferramenta de IA conectada só recebe os seus dados quando chama o TellDone, em geral porque você perguntou alguma coisa. Ela recebe apenas as respostas a essas chamadas, dentro das permissões que você aprovou. Para limitar o acesso, mude para Somente leitura, desconecte o app em Aplicativos conectados ou gere um novo token de acesso, ou desative-o, nas Configurações. Veja a Política de Privacidade para todos os detalhes ou escreva para support@telldone.app se tiver dúvidas.
Solução de problemas
| Sintoma | Causa / solução |
|---|---|
| A página de consentimento do OAuth diz "Wrong email or password" | Use o email e a senha com que você entra no app, ou escolha Entrar com a Apple / Entrar com o Google na mesma página. |
| Conectou, mas a IA não consegue criar nem editar nada | Seu plano é Free ou Basic (somente leitura), seu modo é somente leitura ou a conexão não tem permissões de escrita. Se você conectou antes de fazer upgrade, desconecte o app em Aplicativos conectados e conecte de novo. Você pode conferir o seu modo nas Configurações. |
| Erro "Insufficient scope" de uma ferramenta | A conexão não tem essa permissão. No Free e no Basic, as permissões de escrita nunca são concedidas, então criar e editar exige o Pro ou o Ultra. Se você conectou antes de fazer upgrade, desconecte o app em Aplicativos conectados e conecte de novo. |
O trecho copiado diz YOUR_TOKEN e o cliente não consegue conectar | Você o copiou com o token oculto. Em Para desenvolvedores, toque em Mostrar e copie o trecho de novo. |
| As ferramentas não aparecem | O MCP não está ativado na sua conta (Configurações > Integrações > Agentes de IA (MCP) > Ativar). |
| "Daily limit reached" | Duas situações usam essa mensagem. "Daily limit reached: the Free plan includes 100 TellDone requests a day" é o limite de solicitações do Free. "Daily limit reached (N/M today)" significa que você criou hoje, por meio de assistentes de IA, tantos itens quanto o seu plano permite: process_note, create_note, create_task e create_event contam cada um, inclusive no Pro e no Ultra. Os dois são zerados à meia-noite no fuso horário salvo na sua conta. |
| Meu cliente só deixa escolher em uma lista de conectores e o TellDone não está nela | O TellDone ainda não está no diretório de conectores de nenhum cliente - adicione-o como um conector personalizado com a URL do MCP ou use o método do token bearer. |
Veja também
- Automações por webhook - envie dados para serviços externos automaticamente
- Todoist - sincronização dedicada de tarefas nos dois sentidos
- Notion - integração dedicada com o Notion