Conexões
Conecte-se via MCP
Conecte o Claude Desktop, o Claude Code, o Cursor, o Codex ou outro cliente MCP às ferramentas locais de projeto do Oleafly.
O Oleafly pode atuar como um servidor MCP (Model Context Protocol). Clientes MCP como Claude Desktop, Claude Code, Cursor, Codex e Grok CLI podem ler, editar, buscar e compilar um projeto do Oleafly. Você não precisa de uma chave de provedor de IA no Oleafly, porque o cliente fornece o modelo.
Esta é a opção para quando você já tem uma assinatura do Claude (ou parecida) e quer que aquele aplicativo de chat conduza o Oleafly, sem colar uma chave de API nas Configurações.
Ative o servidor
Seção intitulada “Ative o servidor”- Abra Configurações → Integrações → Servidor MCP do Oleafly.
- Ligue Ativar o servidor MCP.
O servidor funciona apenas enquanto o processo do Oleafly está aberto. Ele escuta somente em 127.0.0.1, nunca na sua rede local. Fechar a janela do projeto não para o servidor. Desligar o MCP ou encerrar o Oleafly, sim.
O Oleafly prefere a porta 5323 (http://127.0.0.1:5323/mcp). Se ela estiver ocupada, o servidor se vincula automaticamente a outra porta local livre e a guarda para a próxima inicialização. As Configurações mostram a URL ativa. O botão de reiniciar delas reaproveita a porta atual quando possível ou escolhe outra livre.
Conecte o seu cliente
Seção intitulada “Conecte o seu cliente”As Configurações mostram trechos prontos para copiar e colar para os clientes comuns. Copie a URL ativa, porque a porta escolhida pode ser diferente de 5323, e depois substitua <token> pelo token Bearer das Configurações (Revelar / Copiar).
Claude Code
Seção intitulada “Claude Code”claude mcp add --transport http oleafly http://127.0.0.1:5323/mcp --header "Authorization: Bearer <token>"Claude Desktop
Seção intitulada “Claude Desktop”Adicione ao claude_desktop_config.json (ponte stdio via mcp-remote, porque o Desktop prefere stdio):
{ "mcpServers": { "oleafly": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "http://127.0.0.1:5323/mcp", "--header", "Authorization: Bearer <token>", "--transport", "http-only" ] } }}Extensão do Claude Desktop
Seção intitulada “Extensão do Claude Desktop”Cada versão inclui oleafly.mcpb, uma extensão do Claude Desktop, então você não precisa do arquivo de configuração nem do token. Baixe-a da versão mais recente (abre em uma nova guia) e abra-a com o Claude Desktop para instalá-la.
A extensão inicia o comando oleafly que vem com o aplicativo e trabalha no projeto aberto no Oleafly, então mantenha o Oleafly aberto com o servidor MCP ativado. Se o Claude Desktop não encontrar o comando, escolha-o nas configurações da extensão: oleafly-cli dentro de Oleafly.app/Contents/MacOS no macOS, ou oleafly-cli.exe em %LOCALAPPDATA%\Oleafly no Windows.
O MCP Registry lista a mesma extensão como io.github.Oleafly/oleafly.
Cursor / VS Code
Seção intitulada “Cursor / VS Code”Em .cursor/mcp.json (ou na configuração MCP do seu cliente):
{ "mcpServers": { "oleafly": { "url": "http://127.0.0.1:5323/mcp", "headers": { "Authorization": "Bearer <token>" } } }}Grok CLI
Seção intitulada “Grok CLI”Em ~/.grok/config.toml:
[mcp_servers.oleafly]url = "http://127.0.0.1:5323/mcp"headers = { Authorization = "Bearer <token>" }Codex CLI
Seção intitulada “Codex CLI”Use o trecho Codex CLI nas configurações do Oleafly, que fornece uma ponte stdio para o servidor em execução. Adicione a entrada à sua configuração do Codex e use a URL ativa e o token mostrados pelo Oleafly:
[mcp_servers.oleafly]command = "npx"args = [ "-y", "mcp-remote@latest", "http://127.0.0.1:5323/mcp", "--header", "Authorization: Bearer <token>", "--transport", "http-only"]A ponte exige o Node.js e o npx. Reinicie ou reconecte o cliente depois de mudar a configuração dele.
O arquivo mcp.json, ao lado dos seus dados do Oleafly (mostrado nas Configurações), guarda a mesma URL e o mesmo token, se você preferir automatizar a configuração com um script. Ele é gravado apenas enquanto o servidor está em execução (modo 0600 no Unix) e excluído quando o servidor para. Trate-o como qualquer outro segredo local.
O que as ferramentas podem fazer
Seção intitulada “O que as ferramentas podem fazer”A maioria das ferramentas MCP compartilha nomes e esquemas com o assistente interno do aplicativo. As ferramentas de descoberta e roteamento de projetos são fornecidas pelo backend do aplicativo.
As ferramentas atuam no projeto aberto no aplicativo, quando houver um. Com uma janela conectada, use list_projects e open_project para selecionar outro projeto.
Depois do fechamento da última janela, o backend mantém read_file, list_files e search_project disponíveis. Gravações, substituições, criações e renomeações nativas também continuam disponíveis quando a política de aprovação as permite. Essas ferramentas usam apenas o último projeto informado pelo aplicativo e recusam a chamada se esse projeto não for mais válido. Elas nunca adivinham a partir de outros projetos da biblioteca. Status, seleção de projetos, exclusão, compilação, logs, inspeção de PDF, mudanças de tema e ferramentas de figuras exigem uma janela conectada.
Orientação
Seção intitulada “Orientação”| Ferramenta | O que faz |
|---|---|
get_status | Versão do Oleafly, projeto aberto, motor de documento dele, documento principal, status da última compilação e por que a última compilação falhou ou não pôde rodar |
list_projects | Projetos com IDs, nomes, motores, tipos, documentos principais, datas e horas, cores, estado de prévia e histórico de exportação |
open_project | Abre um projeto pelo id para que as outras ferramentas atuem nele |
list_files | Árvore de arquivos do projeto |
project_map | Sumário, labels, citações, macros, grafo de entradas, referências não resolvidas |
search_project | Busca texto no projeto atual |
Leitura
Seção intitulada “Leitura”| Ferramenta | O que faz |
|---|---|
read_file | Lê um arquivo do projeto |
get_log | Log da última compilação |
get_pdf_text | Texto extraído do PDF compilado |
verify_pdf_pages | Confere as páginas renderizadas do PDF em busca de problemas de layout, a partir de imagens ou do texto das páginas |
get_pdf_text e verify_pdf_pages leem o último PDF que o Oleafly tem. Quando a última compilação falhou ou não pôde rodar, o resultado delas diz que o PDF está desatualizado e por quê, porque ele vem de uma compilação anterior ou é um PDF parcial da compilação que falhou. get_log diz o mesmo quando a última compilação não pôde rodar, porque o log então é de uma compilação anterior.
| Ferramenta | O que faz |
|---|---|
write_file | Grava ou substitui um arquivo |
replace_in_file | Busca e substitui dentro de um arquivo |
create_file | Cria um arquivo ou pasta |
rename_file | Renomeia ou move um caminho |
delete_file | Exclui um arquivo ou pasta |
set_main_doc | Define o documento de entrada da compilação |
Compilação e figuras
Seção intitulada “Compilação e figuras”| Ferramenta | O que faz |
|---|---|
compile | Compila o projeto para PDF |
preview_figure | Renderiza uma figura isolada e devolve uma imagem PNG |
insert_figure | Insere no documento a última figura pré-visualizada |
load_image | Carrega uma imagem do projeto para trabalhar em figuras |
O compile diz se a compilação funcionou, lista os erros dela, diz se há um PDF e termina com a última parte do log. Uma compilação que terminou também informa os avisos dela. Quando a compilação não pôde rodar, não terminou ou precisa de algo fora do código-fonte, como uma instalação TeX ou uma versão do Typst que não está lá, o resultado dá o motivo e nomeia a correção que o Oleafly está oferecendo a você no aplicativo. A ferramenta pede ao cliente que avise você e deixe o seu código-fonte em paz. Uma compilação que você interrompeu é marcada como interrompida, para o cliente não tratá-la como um erro no código. O próprio assistente do Oleafly recebe o mesmo resultado.
Chame get_status primeiro para saber se o projeto é LaTeX, Typst ou Markdown, e então escreva o código-fonte nesse formato. preview_figure e insert_figure funcionam em projetos LaTeX e Typst:
- No LaTeX, a figura é um código TikZ compilado em um pequeno documento standalone, e
insert_figurea envolve em um ambientefigure. - No Typst, a figura é uma marcação Typst, como um canvas do CeTZ ou um diagrama do fletcher, renderizada com a versão de Typst do projeto.
insert_figurea envolve em#figure, põe o label depois dela e move as linhas#importpara acima dela. - Em um projeto Markdown, as duas ferramentas devolvem um erro e não mudam nada.
load_image funciona em qualquer projeto.
Aplicativo
Seção intitulada “Aplicativo”| Ferramenta | O que faz |
|---|---|
toggle_theme | Alterna o modo claro / escuro |
Habilidades
Seção intitulada “Habilidades”| Ferramenta | O que faz |
|---|---|
list_skills | Lista as habilidades instaladas com o ID, o nome, a descrição e se estão ligadas |
load_skill | Carrega as instruções completas de uma habilidade e a lista de arquivos dela |
read_skill_file | Lê uma referência ou um script da pasta de uma habilidade |
As ferramentas de habilidades funcionam logo depois de conectar, sem projeto aberto e sem janela do Oleafly. Um cliente vê toda habilidade válida, inclusive as desligadas nas Configurações: os interruptores decidem quais habilidades o próprio assistente do Oleafly usa, não o que um cliente pode ler. Agentes que leem habilidades de uma pasta, em vez disso, podem usar Compartilhar habilidades com outros agentes deste computador em Configurações → Assistente de IA → Habilidades. Veja Habilidades.
Essas ferramentas ficam disponíveis enquanto Notas está ativado em Configurações → Experimentação, como descreve Ative as Notas. Elas trabalham nas suas notas, não no projeto aberto, e precisam de uma janela conectada.
| Ferramenta | O que faz |
|---|---|
list_knowledge_notes | Lista as suas notas, das mais novas para as mais antigas, com IDs, títulos, tags, projetos vinculados e resumos curtos. Filtre por tag ou por projeto |
search_notes | Busca nas suas notas e devolve IDs, títulos, tags, links e trechos que correspondem |
read_note_by_id | Lê uma nota como Markdown, com o front matter dela |
today_note | Lê a nota diária de hoje, ou o título que ela teria se ainda não existisse |
list_note_tasks | Lista as tarefas com caixa de seleção das suas notas, da nota mais nova para a mais antiga. Filtre por nota e por abertas ou concluídas |
note_backlinks | Lista as notas que apontam para uma nota, com o texto em volta de cada link |
append_to_note | Adiciona Markdown ao fim de uma nota ou da nota diária de hoje |
edit_note_section | Reescreve a parte de uma nota sob um título, ou acrescenta ao fim dela |
create_note | Cria uma nota com título, Markdown, tags e um projeto vinculado |
append_to_note e edit_note_section não gravam na nota. As mudanças delas aparecem na nota como sugestões até você aceitá-las no Oleafly. create_note espera pela sua aprovação no Oleafly, e append_to_note também espera quando precisa criar antes a nota diária de hoje. Em Confiar nesta conexão, criar uma nota não pergunta. Uma nota compartilhada por um servidor de colaboração pode ser lida, mas não alterada por aqui. Somente leitura remove as três ferramentas que alteram notas.
Aprovações e segurança
Seção intitulada “Aprovações e segurança”Muitos clientes MCP perguntam antes de chamar uma ferramenta. O Oleafly também aplica a política escolhida em Configurações → Integrações → Servidor MCP do Oleafly:
- Confirmar cada mudança é o padrão. Gravações, renomeações e exclusões mostram um cartão de aprovação enquanto uma janela do aplicativo está conectada. Sem uma janela, essas operações são recusadas porque não há onde mostrar o cartão.
- Aprovar edições automaticamente, confirmar exclusões deixa gravações e renomeações rodarem no backend. As exclusões ainda precisam de uma janela conectada para confirmação.
- Confiar nesta conexão deixa gravações e renomeações do backend rodarem sem um aviso do Oleafly. A exclusão ainda exige uma janela conectada. Use esta política apenas quando você confia no cliente e nos controles de aprovação dele.
Dois outros interruptores reforçam isso:
- Somente leitura (interruptor separado) remove as ferramentas de modificação de
tools/listpor completo, então um aplicativo externo pode ler e compilar, mas nunca modificar arquivos, seja qual for a política acima. - Token Bearer: um valor aleatório de 256 bits guardado em um armazenamento local criptografado e autenticado sob
~/.oleafly/. Gere um novo para invalidar os clientes antigos. Leituras gerais de configuração nunca expõem o token. Só os controles de conexão do servidor em execução podem revelá-lo nas Configurações.
E duas invariantes que você não configura:
- Somente localhost: o endereço de escuta é
127.0.0.1. Requisições com um cabeçalhoOriginde navegador são rejeitadas, e oHostprecisa ser loopback. - Confinamento ao projeto: as ferramentas de arquivo do backend aceitam caminhos relativos ao projeto e restringem os caminhos canônicos ao projeto informado pelo aplicativo. Uma chamada de ferramenta não pode fornecer outro ID de projeto nem fazer o backend escolher um projeto diferente da biblioteca.
Veja funcionar
Seção intitulada “Veja funcionar”Enquanto uma janela está conectada, uma aba de Atividade MCP registra as chamadas recebidas. As chamadas do backend podem continuar depois do fechamento da última janela, mas não há painel de atividade nem cartão de aprovação até uma janela se reconectar.
Por que o claude.ai no navegador não consegue conectar
Seção intitulada “Por que o claude.ai no navegador não consegue conectar”Um serviço de chat na nuvem não alcança o 127.0.0.1 da sua máquina. Use o Claude Desktop (ou o Claude Code, o Cursor etc.) em vez disso. Não crie um túnel da porta do MCP para a internet pública: isso deixaria qualquer pessoa com a URL editar e excluir os arquivos do seu projeto local.
Solução de problemas
Seção intitulada “Solução de problemas”| Sintoma | O que tentar |
|---|---|
| Algumas ferramentas não estão disponíveis | Prévias de figuras e outras ferramentas só de interface precisam de uma janela do Oleafly. Abra o aplicativo e o projeto e tente tools/list de novo. |
A porta mudou de 5323 | A porta preferida estava ocupada, então o Oleafly escolheu uma livre. Copie a URL ativa das Configurações. |
| HTTP 401 | Divergência de token (por exemplo, depois de Gerar novo). Copie o token novo para o cliente. |
| HTTP 403 | O cliente enviou um cabeçalho Origin ou um Host fora do loopback. Use um cliente MCP nativo, não uma aba do navegador. |
| A chamada expirou | Cada chamada de ferramenta espera até 5 minutos (300 s) por compilações ou por você clicar em Aprovar. Aprove ou rejeite os cartões pendentes, ou tente de novo. Uma compilação pode demorar mais, até uma hora para um notebook Quarto ou Calepin. Ela continua rodando no Oleafly depois que a chamada expira, e as ferramentas que precisam da janela do Oleafly esperam por ela, então deixe-a terminar antes de tentar de novo. |
compile devolve um motivo em vez de erros | A compilação não pôde rodar, por exemplo porque o TeX não está instalado. Use a correção que o Oleafly oferece no aplicativo, como instalar o TinyTeX, e compile de novo. |
| Não conecta | O Oleafly precisa estar em execução com o MCP ativado. Este servidor para quando você encerra o aplicativo; para ter as ferramentas do projeto com o aplicativo fechado, conecte o cliente ao oleafly mcp. |
Adicione ferramentas externas ao Oleafly
Seção intitulada “Adicione ferramentas externas ao Oleafly”
Para dar mais ferramentas ao assistente integrado, abra Configurações → Assistente de IA → MCP.
- Explorar o registro para encontrar um servidor e revisar a configuração dele.
- Importar de outras ferramentas para selecionar configurações de servidor existentes. Revise as entradas escolhidas antes de importar.
- Adicionar servidor para digitar um servidor você mesmo e depois validar a conexão.
Os servidores conectados expõem as ferramentas deles ao assistente. Você pode inspecionar o estado da conexão e ativar ou desativar servidores na mesma página. Credenciais e comandos pertencem a cada configuração de servidor; revise-os antes de conectar um servidor novo.
O alphaXiv também se conecta como um servidor MCP, mas você o configura em Configurações → Integrações → alphaXiv, com uma chave de API, em vez de aqui. Depois de conectado, ele aparece nesta lista como alphaXiv. Conecte fontes de pesquisa cobre os passos.
Configure um servidor externo à mão
Seção intitulada “Configure um servidor externo à mão”
Em Configurações → Assistente de IA → MCP, escolha Adicionar servidor. Um servidor local executa um comando por stdio; um servidor remoto se conecta a uma URL. O formulário JSON usa o formato de servidor do Oleafly:
{ "name": "Research tools", "enabled": true, "transport": "stdio", "command": "your-mcp-server", "args": ["--stdio"], "env": {}}Substitua o comando e os argumentos pelos documentados pelo servidor que você instalou. Valores de ambiente ficam no objeto env.
{ "name": "Research service", "enabled": true, "transport": "remote", "url": "https://your-server.example/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN" }}Substitua a URL e o token de exemplo pelos dados de conexão do serviço. Use Validar para verificar a conexão e depois revise as ferramentas que o servidor expõe. Ative ou desative o servidor na linha dele. Use a ação de editar para mudar a configuração e a de remover para desconectá-lo.
Importe configurações MCP existentes
Seção intitulada “Importe configurações MCP existentes”Escolha Importar de outras ferramentas, inspecione as configurações descobertas e selecione os servidores que você quer. Revise caminhos de executáveis, variáveis de ambiente, URLs e credenciais antes de importar. Isso importa configurações de conexão; não instala o executável do servidor para você.
Teste a conexão
Seção intitulada “Teste a conexão”- Abra um projeto pequeno de prática no Oleafly.
- Conecte o cliente externo usando o trecho copiado do aplicativo.
- Peça ao cliente para chamar
get_statuse listar os arquivos do projeto. - Peça a ele para ler o documento principal e sugerir uma mudança de título.
- Revise a ação no Oleafly antes de aprovar uma gravação.
- Compile e inspecione o PDF.
Para uma ferramenta externa conectada dentro do Oleafly, comece com uma requisição simples de somente leitura suportada por esse servidor e inspecione o cartão de ferramenta resultante no chat.