Notezbeta
Voltar ao blog

O Claude Code agora coloca imagens nas suas anotações: upload de arquivos via MCP

ProductDenis Povarov

Peça a um assistente de IA para escrever o relatório do incidente de ontem e ele faz um bom trabalho, até chegar ao gráfico. A captura de tela está na sua área de trabalho, a nota diz "ver anexo", e não há nada anexado. Até agora, o servidor MCP do Notez lia, escrevia e reorganizava suas notas, mas um arquivo no seu computador estava fora do alcance dele.

O Notez v0.11.0 fecha essa lacuna. Qualquer assistente MCP que rode comandos no shell — Claude Code, Cursor, Codex CLI — agora envia uma imagem ou um arquivo local e o coloca direto em uma nota.

Como fica na prática

Você pede:

Adicione ./grafana-latency.png à minha nota Incidente 2026-09-10, logo abaixo do título Linha do tempo, e anexe os logs brutos de ./incident-logs.zip.

O assistente envia os dois arquivos e edita a nota. A captura de tela aparece no texto, sob Linha do tempo; o arquivo compactado vira um chip de arquivo que você clica para baixar. Os dois aparecem na sua página Arquivos, contam no seu armazenamento como qualquer outro arquivo e seguem os mesmos formatos e limites de tamanho do editor.

Funciona em qualquer lugar onde uma nota é escrita: ao criar uma nota nova, ao editar parte de uma nota ou ao reescrevê-la.

Por que o arquivo nunca passa pelo chat

O design óbvio é uma ferramenta que recebe o arquivo como argumento. Chamadas de ferramentas MCP são JSON, então o arquivo viajaria como texto base64 dentro da própria saída do modelo: cerca de 35.000 tokens para uma captura de tela de 100 KB, e um PDF nem caberia. O protocolo ainda não tem como transferir arquivos; uma proposta exatamente para isso continua em rascunho.

Por isso usei o caminho que o editor do Notez já usa. Quando você solta uma imagem no editor, o navegador pede ao servidor um upload assinado e envia os bytes direto para o armazenamento. Um assistente faz a mesma coisa em três passos:

  1. Ele pede um upload. A ferramenta create_upload recebe o nome do arquivo, o tipo e o tamanho exato, e responde com um comando curl pronto para rodar, assinado só para esse arquivo.

  2. Ele roda o comando. O arquivo vai da sua máquina direto para o armazenamento. Nada passa pela conversa, então um PDF de 20 MB não custa mais tokens que um de 20 KB.

  3. Ele confirma. confirm_upload verifica se o arquivo chegou de fato e devolve um snippet de uma linha que o assistente cola na nota.

O porém é simples e honesto: o passo 2 exige um shell. Assistentes que rodam comandos, como o Claude Code e o Cursor, fazem isso sem que você peça. Clientes só de chat, como o Claude Desktop, não conseguem, e dizem isso em vez de fingir: eles mandam você para o app.

Conferindo se o arquivo chegou mesmo

Um agente pode dizer "pronto" sobre um comando que falhou. Em vez de acreditar na palavra dele, confirm_upload pergunta ao armazenamento pelo arquivo. Se não houver nada lá, o assistente recebe a instrução de rodar o comando de novo. Se os bytes que chegaram não tiverem o tamanho declarado, o upload é recusado e ele recomeça. O tamanho declarado é o que a sua cota de armazenamento conta, então um arquivo que informa o tamanho errado nunca é registrado.

Foi nesta parte que passei mais tempo.

O Notez acompanha cada arquivo que uma nota usa. É com esse controle que o Notez faz a limpeza por você: quando você apaga uma imagem de uma nota, o espaço dela no armazenamento acaba sendo liberado, e um arquivo enviado mas nunca usado é removido depois de três dias. No editor você nunca vê nada disso, porque cada imagem que ele insere leva um id de arquivo oculto.

Um assistente escreve Markdown à mão. Depois de um upload, a coisa mais natural do mundo para um modelo é escrever um link de imagem simples: ![latency](https://…/grafana.png). Ele renderiza. Parece certo. E não leva id de arquivo nenhum, então, para o Notez, a nota não usa aquele arquivo. Três dias depois a limpeza o remove, e uma nota que você compartilhou na semana passada passa a mostrar, sem aviso, uma imagem quebrada.

Percebi isso enquanto construía o recurso, não depois do lançamento, e fechei o problema pelos dois lados:

  • O assistente recebe a marcação certa. confirm_upload devolve um snippet que já leva o id do arquivo, e as instruções do servidor mandam o assistente colá-lo sem alterações.

  • O Notez recusa a marcação errada. Se o assistente grava uma nota com um link para um arquivo recém-enviado só pelo endereço, a gravação é rejeitada com uma explicação, e ele tenta de novo com o snippet. Links para qualquer outra coisa continuam funcionando: imagens de outros sites e arquivos que já estão guardados em outra nota.

A mesma proteção vale para o chat de IA do app, então nenhum dos dois assistentes deixa uma bomba-relógio nas suas notas.

O que saber antes de testar

  • Os uploads ficam acessíveis pelo endereço exato, como as imagens que você cola no editor. Nada os lista e não dá para adivinhar os endereços, mas não envie nada que você não colocaria em uma nota.

  • O armazenamento é do proprietário do espaço de trabalho. Os uploads entram na cota da conta dona do espaço de trabalho, seja qual for o jeito como o assistente se conectou.

  • As capturas de tela ficam no tamanho original. O editor comprime as imagens no seu navegador; o upload de um assistente chega exatamente como o arquivo está no disco.

  • O chat de IA do app não faz upload. Ele roda no seu navegador, sem acesso aos seus arquivos. As duas ferramentas de upload, e list_workspaces para conexões por login, são as únicas que o servidor MCP tem e o chat não.

Experimente

  1. No Notez, abra Configurações → Integrações → Servidor MCP do Notez e clique em Gerar chave MCP.

  2. Adicione a chave ao Claude Code com o comando mostrado nessa página, ou ao Cursor com a configuração JSON.

  3. Peça algo que envolva um arquivo: "Coloque ./architecture.png na minha nota Design do sistema."

A referência completa (cada ferramenta, erro e limite) está em Configuração do servidor MCP, e Arquivos e anexos trata de formatos e armazenamento.

Perguntas frequentes

O Claude Code consegue enviar imagens para o Notez?

Sim. O Claude Code roda comandos no shell, então usa as ferramentas create_upload e confirm_upload para colocar uma imagem ou um arquivo local em qualquer nota de um espaço de trabalho ao qual está conectado.

Funciona no Claude Desktop?

Não de fábrica. O passo de upload roda um comando curl, e o Claude Desktop não roda comandos a menos que você tenha dado a ele uma ferramenta que faça isso. Ele vai pedir que você adicione o arquivo pelo app.

Quais arquivos um assistente de IA consegue enviar?

Os mesmos do editor: imagens (JPG, PNG, GIF, SVG, WEBP e outras), PDFs e documentos do Office, vídeo e arquivos compactados ZIP ou RAR, até o limite por arquivo do seu plano.

Um arquivo enviado conta no meu armazenamento?

Sim: no armazenamento da conta do proprietário do espaço de trabalho, exatamente como um arquivo adicionado no editor.

O que significa NOTE_UPLOAD_NOT_LINKED?

O assistente tentou apontar para um arquivo enviado só pelo endereço. O Notez recusa isso porque o arquivo não seria rastreado e seria removido depois de três dias. O assistente deve colar o snippet que confirm_upload devolveu; a maioria tenta de novo sozinha.

Continue lendo