# 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](/docs/ai-setup/).

## Ative o servidor

1. Abra **Configurações → Integrações → Servidor MCP do Oleafly**.
2. 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

:::tip[Nenhum token para copiar]
O comando `oleafly` tem o próprio servidor MCP, que conversa por entrada e saída padrão. Ele encontra sozinho o aplicativo em execução e o token dele, então você não copia uma URL nem um token, e não precisa do Node.js. `oleafly mcp config --client claude-desktop` imprime a configuração; os nomes de cliente são `claude-code`, `claude-desktop`, `codex`, `cursor` e `gemini`. Veja [Ferramenta de linha de comando](/docs/cli/#connect-an-agent-over-mcp).
:::

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

```bash
claude mcp add --transport http oleafly http://127.0.0.1:5323/mcp --header "Authorization: Bearer <token>"
```

### Claude Desktop

Adicione ao `claude_desktop_config.json` (ponte stdio via `mcp-remote`, porque o Desktop prefere stdio):

```json
{
  "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

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](https://github.com/Oleafly/Oleafly/releases/latest) 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

Em `.cursor/mcp.json` (ou na configuração MCP do seu cliente):

```json
{
  "mcpServers": {
    "oleafly": {
      "url": "http://127.0.0.1:5323/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}
```

### Grok CLI

Em `~/.grok/config.toml`:

```toml
[mcp_servers.oleafly]
url = "http://127.0.0.1:5323/mcp"
headers = { Authorization = "Bearer <token>" }
```

### 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:

```toml title="~/.codex/config.toml"
[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

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

| 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

| 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.

### Edição

| 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

| 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_figure` a envolve em um ambiente `figure`.
- 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_figure` a envolve em `#figure`, põe o label depois dela e move as linhas `#import` para acima dela.
- Em um projeto Markdown, as duas ferramentas devolvem um erro e não mudam nada.

`load_image` funciona em qualquer projeto.

### Aplicativo

| Ferramenta | O que faz |
|---|---|
| `toggle_theme` | Alterna o modo claro / escuro |

### 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](/docs/skills/).

### Notas

Essas ferramentas ficam disponíveis enquanto **Notas** está ativado em **Configurações → Experimentação**, como descreve [Ative as Notas](/docs/notes/#turn-on-notes). 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

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/list` por 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çalho `Origin` de navegador são rejeitadas, e o `Host` precisa 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

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

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

| 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

![Configurações → Assistente de IA → MCP. Adicione um servidor, explore o registro ou importe configurações de outra ferramenta.](https://cdn.oleafly.com/images/screenshots/desktop/docs/settings-mcp-dark-window-v2.png#view=519,89,883,568)

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](/docs/integrations/research-sources/#alphaxiv) cobre os passos.

## Configure um servidor externo à mão

![Adicionar servidor → Formulário. Escolha Comando local ou URL remota, preencha os campos de conexão e depois use Adicionar e validar.](https://cdn.oleafly.com/images/screenshots/desktop/docs/mcp-add-server-dark-window-v2.png#view=670,228,578,625)

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:

```json title="Configuração de servidor local"
{
  "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`.

```json title="Configuração de servidor remoto"
{
  "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

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

1. Abra um projeto pequeno de prática no Oleafly.
2. Conecte o cliente externo usando o trecho copiado do aplicativo.
3. Peça ao cliente para chamar `get_status` e listar os arquivos do projeto.
4. Peça a ele para ler o documento principal e sugerir uma mudança de título.
5. Revise a ação no Oleafly antes de aprovar uma gravação.
6. 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.
