# Conéctate mediante MCP

Conecta Claude Desktop, Claude Code, Cursor, Codex u otro cliente MCP a las herramientas de proyecto locales de Oleafly.

Oleafly puede actuar como servidor MCP (Model Context Protocol). Los clientes MCP como Claude Desktop, Claude Code, Cursor, Codex y Grok CLI pueden leer, editar, buscar y compilar un proyecto de Oleafly. No necesitas una clave de proveedor de IA en Oleafly, porque el cliente aporta el modelo.

Es la opción para cuando ya tienes una suscripción a Claude (o similar) y quieres que esa app de chat maneje Oleafly, sin pegar una clave de API en los [Ajustes](/docs/ai-setup/).

## Actívalo

1. Abre **Ajustes → Integraciones → Oleafly MCP**.
2. Activa **Activar el servidor MCP**.

El servidor solo se ejecuta mientras el proceso de Oleafly está abierto. Escucha únicamente en `127.0.0.1`, nunca en tu red local. Cerrar la ventana del proyecto no detiene el servidor. Desactivar MCP o salir de Oleafly, sí.

Oleafly prefiere el puerto `5323` (`http://127.0.0.1:5323/mcp`). Si no está disponible, el servidor enlaza automáticamente otro puerto local libre y lo guarda para el siguiente inicio. Los Ajustes muestran la URL activa. Su botón de reinicio reutiliza el puerto actual cuando es posible o selecciona otro libre.

## Conecta tu cliente

:::tip[Sin token que copiar]
El comando `oleafly` tiene su propio servidor MCP, que se comunica por la entrada y la salida estándar. Encuentra por sí mismo la app en ejecución y su token, así que no copias ninguna URL ni ningún token, y no necesitas Node.js. `oleafly mcp config --client claude-desktop` imprime la configuración; los nombres de cliente son `claude-code`, `claude-desktop`, `codex`, `cursor` y `gemini`. Consulta [Herramienta de línea de comandos](/docs/cli/#connect-an-agent-over-mcp).
:::

Los Ajustes muestran fragmentos para copiar y pegar para los clientes habituales. Copia la URL real, porque el puerto seleccionado puede ser distinto de `5323`, y luego sustituye `<token>` por el token de portador de los Ajustes (Mostrar / Copiar).

### Claude Code

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

### Claude Desktop

Añade a `claude_desktop_config.json` (puente stdio mediante `mcp-remote`, porque Desktop prefiere 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"
      ]
    }
  }
}
```

### Extensión de Claude Desktop

Cada versión incluye `oleafly.mcpb`, una extensión de Claude Desktop, así que no necesitas el archivo de configuración ni el token. Descárgala de la [última versión](https://github.com/Oleafly/Oleafly/releases/latest) y ábrela con Claude Desktop para instalarla.

La extensión inicia el comando `oleafly` que viene con la aplicación y trabaja en el proyecto que Oleafly tiene abierto, así que mantén Oleafly abierto con su servidor MCP activado. Si Claude Desktop no encuentra el comando, elígelo en los ajustes de la extensión: `oleafly-cli` dentro de `Oleafly.app/Contents/MacOS` en macOS, o `oleafly-cli.exe` en `%LOCALAPPDATA%\Oleafly` en Windows.

El MCP Registry lista la misma extensión como `io.github.Oleafly/oleafly`.

### Cursor / VS Code

En `.cursor/mcp.json` (o en la configuración MCP de tu cliente):

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

### Grok CLI

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

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

### Codex CLI

Usa el fragmento **Codex CLI** de los ajustes de Oleafly, que ofrece un puente stdio hacia el servidor en ejecución. Añade la entrada a tu configuración de Codex y usa la URL y el token reales que muestra 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"
]
```

El puente requiere Node.js y `npx`. Reinicia o vuelve a conectar el cliente después de cambiar su configuración.

El archivo `mcp.json` junto a los datos de Oleafly (que se muestra en los Ajustes) contiene la misma URL y el mismo token si prefieres automatizar la configuración con un script. Se escribe solo mientras el servidor está en ejecución (modo `0600` en Unix) y se elimina cuando el servidor se detiene. Trátalo como cualquier otro secreto local.

## Qué pueden hacer las herramientas

La mayoría de las herramientas MCP comparten sus nombres y esquemas con el asistente de la app. Las herramientas de descubrimiento y enrutamiento de proyectos las proporciona el backend de escritorio.

Las herramientas apuntan al proyecto abierto en la app cuando hay uno disponible. Con una ventana conectada, usa `list_projects` y `open_project` para seleccionar otro proyecto.

Cuando se cierra la última ventana, el backend mantiene disponibles `read_file`, `list_files` y `search_project`. Las escrituras, los reemplazos, las creaciones y los cambios de nombre nativos también siguen disponibles cuando la política de aprobación lo permite. Estas herramientas usan solo el último proyecto notificado por la app, y rechazan la llamada si ese proyecto ya no es válido. Nunca adivinan a partir de otros proyectos de la biblioteca. El estado, la selección de proyecto, la eliminación, la compilación, los registros, la inspección del PDF, los cambios de tema y las herramientas de figuras requieren una ventana conectada.

### Orientación

| Herramienta | Qué hace |
|---|---|
| `get_status` | Versión de Oleafly, proyecto abierto, su motor de documento, documento principal, estado de la última compilación, y por qué la última compilación falló o no pudo ejecutarse |
| `list_projects` | Proyectos con ID, nombres, motores, tipos, documentos principales, marcas de tiempo, colores, estado de la vista previa e historial de exportaciones |
| `open_project` | Abrir un proyecto por ID para que las demás herramientas lo usen como destino |
| `list_files` | Árbol de archivos del proyecto |
| `project_map` | Esquema, etiquetas, citas, macros, grafo de entradas, referencias sin resolver |
| `search_project` | Buscar texto en el proyecto actual |

### Lectura

| Herramienta | Qué hace |
|---|---|
| `read_file` | Leer un archivo del proyecto |
| `get_log` | Último registro de compilación |
| `get_pdf_text` | Texto extraído del PDF compilado |
| `verify_pdf_pages` | Comprobar si las páginas renderizadas del PDF tienen problemas de maquetación, a partir de imágenes de página o del texto de la página |

`get_pdf_text` y `verify_pdf_pages` leen el último PDF que tiene Oleafly. Cuando la última compilación falló o no pudo ejecutarse, su resultado dice que el PDF está obsoleto y por qué, porque viene de una compilación anterior o es uno parcial de la compilación fallida. `get_log` dice lo mismo cuando la última compilación no pudo ejecutarse, porque entonces su registro es de una compilación anterior.

### Edición

| Herramienta | Qué hace |
|---|---|
| `write_file` | Escribir o sobrescribir un archivo |
| `replace_in_file` | Buscar y reemplazar dentro de un archivo |
| `create_file` | Crear un archivo o una carpeta |
| `rename_file` | Renombrar o mover una ruta |
| `delete_file` | Eliminar un archivo o una carpeta |
| `set_main_doc` | Establecer el documento de entrada de la compilación |

### Compilación y figuras

| Herramienta | Qué hace |
|---|---|
| `compile` | Compilar el proyecto a PDF |
| `preview_figure` | Renderizar una figura por separado y devolver una imagen PNG |
| `insert_figure` | Insertar en el documento la última figura previsualizada |
| `load_image` | Cargar una imagen del proyecto para trabajar con figuras |

`compile` dice si la compilación funcionó, enumera sus errores, dice si hay un PDF y termina con la última parte del registro. Una compilación que terminó también informa de sus advertencias. Cuando la compilación no pudo ejecutarse, no terminó o necesita algo ajeno al código, como una instalación de TeX o una versión de Typst que no está, el resultado da el motivo y nombra la solución que Oleafly te ofrece en la app. La herramienta pide al cliente que te lo diga y que deje tu código en paz. Una compilación que detuviste se marca como detenida, para que el cliente no la trate como un error del código. El propio asistente de Oleafly recibe el mismo resultado.

Llama primero a `get_status` para saber si el proyecto es de LaTeX, Typst o Markdown, y luego escribe el código en ese formato. `preview_figure` e `insert_figure` funcionan en proyectos de LaTeX y Typst:

- En LaTeX, la figura es código TikZ compilado en un pequeño documento independiente, e `insert_figure` lo envuelve en un entorno `figure`.
- En Typst, la figura es marcado de Typst, como un lienzo CeTZ o un diagrama de fletcher, renderizado con la versión de Typst del proyecto. `insert_figure` lo envuelve en `#figure`, coloca la etiqueta después y sube las líneas `#import` por encima.
- En un proyecto de Markdown, ambas herramientas devuelven un error y no cambian nada.

`load_image` funciona en todos los proyectos.

### App

| Herramienta | Qué hace |
|---|---|
| `toggle_theme` | Alternar el modo claro / oscuro |

### Habilidades

| Herramienta | Qué hace |
|---|---|
| `list_skills` | Enumerar las habilidades instaladas con su ID, nombre, descripción y si están activadas |
| `load_skill` | Cargar las instrucciones completas de una habilidad y su lista de archivos |
| `read_skill_file` | Leer una referencia o un script de la carpeta de una habilidad |

Las herramientas de habilidades funcionan justo después de conectar, sin proyecto abierto y sin ventana de Oleafly. Un cliente ve todas las habilidades válidas, incluidas las desactivadas en los Ajustes: los interruptores deciden qué habilidades usa el asistente propio de Oleafly, no lo que puede leer un cliente. Los agentes que leen habilidades desde una carpeta pueden usar **Compartir las habilidades con otros agentes de este equipo** en **Ajustes → Asistente de IA → Habilidades**. Consulta [Habilidades](/docs/skills/).

### Notas

Estas herramientas están disponibles mientras **Notas** está activado en **Ajustes → Experimentación**, como describe [Activa Notas](/docs/notes/#turn-on-notes). Funcionan con tus notas, no con el proyecto abierto, y necesitan una ventana conectada.

| Herramienta | Qué hace |
|---|---|
| `list_knowledge_notes` | Enumerar tus notas, las más recientes primero, con ID, títulos, etiquetas, proyectos vinculados y resúmenes breves. Filtra por etiqueta o proyecto |
| `search_notes` | Buscar en tus notas y devolver ID, títulos, etiquetas, enlaces y fragmentos que coinciden |
| `read_note_by_id` | Leer una nota como Markdown con su front matter |
| `today_note` | Leer la nota diaria de hoy, o el título que tendría si todavía no existe |
| `list_note_tasks` | Enumerar las tareas con casilla de tus notas, empezando por la nota más reciente. Filtra por nota y por pendientes o hechas |
| `note_backlinks` | Enumerar las notas que enlazan con una nota, con el texto que rodea cada enlace |
| `append_to_note` | Añadir Markdown al final de una nota o de la nota diaria de hoy |
| `edit_note_section` | Reescribir la parte de una nota que está bajo un título, o añadir algo al final de ella |
| `create_note` | Crear una nota con un título, Markdown, etiquetas y un proyecto vinculado |

`append_to_note` y `edit_note_section` no escriben en la nota. Sus cambios se muestran en ella como sugerencias hasta que los aceptes en Oleafly. `create_note` espera tu aprobación en Oleafly, y también `append_to_note` cuando tiene que crear antes la nota diaria de hoy. Con **Confiar en esta conexión**, crear una nota no pregunta. Una nota compartida a través de un servidor de colaboración se puede leer pero no cambiar de esta manera. **Solo lectura** quita las tres herramientas que cambian notas.

## Aprobaciones y seguridad

Muchos clientes MCP preguntan antes de llamar a una herramienta. Oleafly también aplica la política seleccionada en **Ajustes → Integraciones → Oleafly MCP**:

- **Confirmar todos los cambios** es el valor predeterminado. Las escrituras, los cambios de nombre y las eliminaciones muestran una tarjeta de aprobación mientras hay una ventana de la app conectada. Sin ventana, esas operaciones se rechazan porque no hay dónde mostrar la tarjeta.
- **Aprobar las ediciones, confirmar las eliminaciones** deja que las escrituras y los cambios de nombre se ejecuten en el backend. Las eliminaciones siguen necesitando una ventana conectada para confirmar.
- **Confiar en esta conexión** deja que las escrituras y los cambios de nombre del backend se ejecuten sin un aviso de Oleafly. La eliminación sigue requiriendo una ventana conectada. Usa esta política solo cuando confíes en el cliente y en sus propios controles de aprobación.

Dos interruptores más lo refuerzan:

- **Solo lectura** (un interruptor aparte) quita por completo las herramientas que modifican de `tools/list`, así que una app externa puede leer y compilar pero nunca modificar archivos, sea cual sea la política anterior.
- **Token de portador**: un valor aleatorio de 256 bits guardado en un almacenamiento local cifrado y autenticado dentro de `~/.oleafly/`. Regéneralo para invalidar a los clientes antiguos. Las lecturas de configuración general nunca exponen el token. Solo los controles de conexión del servidor en ejecución pueden mostrarlo en los Ajustes.

Y dos invariantes que no configuras:

- **Solo localhost**: la dirección de enlace es `127.0.0.1`. Las solicitudes que llevan una cabecera `Origin` de navegador se rechazan, y `Host` debe ser de loopback.
- **Confinamiento al proyecto**: las herramientas de archivos del backend aceptan rutas relativas al proyecto y confinan las rutas canónicas al proyecto notificado por la app. Una llamada a una herramienta no puede proporcionar el ID de otro proyecto ni hacer que el backend elija un proyecto distinto de la biblioteca.

## Míralo trabajar

Mientras hay una ventana conectada, una pestaña **Actividad de MCP** registra las llamadas entrantes. Las llamadas del backend pueden continuar después de que se cierre la última ventana, pero no hay panel de actividad ni tarjeta de aprobación hasta que una ventana se vuelve a conectar.

## Por qué claude.ai en el navegador no puede conectarse

Un servicio de chat en la nube no puede llegar a `127.0.0.1` de tu equipo. Usa en su lugar **Claude Desktop** (o Claude Code, Cursor, etc.). No abras un túnel del puerto MCP a internet pública: eso permitiría a cualquiera que tenga la URL editar y eliminar los archivos de tu proyecto local.

## Solución de problemas

| Síntoma | Qué probar |
|---|---|
| Algunas herramientas no están disponibles | Las vistas previas de figuras y otras herramientas que solo funcionan en la interfaz necesitan una ventana de Oleafly. Abre la app y el proyecto, y vuelve a intentar `tools/list`. |
| El puerto cambió de `5323` | El puerto preferido no estaba disponible, así que Oleafly seleccionó uno libre. Copia la URL real de los Ajustes. |
| HTTP 401 | El token no coincide (por ejemplo, tras Regenerar). Copia el token nuevo en el cliente. |
| HTTP 403 | El cliente envió una cabecera `Origin` o un `Host` que no es de loopback. Usa un cliente MCP nativo, no una pestaña del navegador. |
| La llamada agotó el tiempo | Cada llamada a una herramienta espera hasta **5 minutos** (300 s) para las compilaciones o para que hagas clic en Aprobar. Aprueba o rechaza las tarjetas pendientes, o vuelve a intentarlo. Una compilación puede tardar más, hasta una hora en un cuaderno de Quarto o Calepin. Sigue ejecutándose en Oleafly después de que la llamada agote el tiempo, y las herramientas que necesitan la ventana de Oleafly esperan a que termine, así que déjala terminar antes de volver a intentarlo. |
| `compile` devuelve un motivo en lugar de errores | La compilación no pudo ejecutarse, por ejemplo porque no hay TeX instalado. Usa la solución que Oleafly ofrece en la app, como instalar TinyTeX, y vuelve a compilar. |
| No se puede conectar | Oleafly debe estar en ejecución con MCP activado. Este servidor se detiene cuando sales; para usar las herramientas de proyecto con la app cerrada, conecta el cliente a `oleafly mcp`. |

## Añade herramientas externas a Oleafly

![Ajustes → Asistente de IA → MCP. Añade un servidor, explora el registro o importa configuraciones de otra herramienta.](https://cdn.oleafly.com/images/screenshots/desktop/docs/settings-mcp-dark-window-v2.png#view=519,89,883,568)

Para dar más herramientas al asistente integrado, abre **Ajustes → Asistente de IA → MCP**.

- **Explorar el registro** para encontrar un servidor y revisar su configuración.
- **Importar de otras herramientas** para seleccionar configuraciones de servidor existentes. Revisa las entradas seleccionadas antes de importar.
- **Añadir un servidor** para introducir un servidor tú mismo y luego validar la conexión.

Los servidores conectados exponen sus herramientas al asistente. Puedes inspeccionar el estado de la conexión y activar o desactivar servidores desde la misma página. Las credenciales y los comandos pertenecen a la configuración de cada servidor; revísalos antes de conectar un servidor nuevo.

alphaXiv también se conecta como servidor MCP, pero lo configuras en **Ajustes → Integraciones → alphaXiv** con una clave de API en lugar de aquí. Una vez conectado, aparece en esta lista como **alphaXiv**. [Conecta fuentes de investigación](/docs/integrations/research-sources/#alphaxiv) cubre los pasos.

## Configura un servidor externo a mano

![Añadir un servidor → Formulario. Elige Comando local o URL remota, rellena los campos de conexión y usa Añadir y validar.](https://cdn.oleafly.com/images/screenshots/desktop/docs/mcp-add-server-dark-window-v2.png#view=670,228,578,625)

En **Ajustes → Asistente de IA → MCP**, elige **Añadir un servidor**. Un servidor local ejecuta un comando por stdio; un servidor remoto se conecta a una URL. El formulario JSON usa el formato de servidor de Oleafly:

```json title="Configuración de servidor local"
{
  "name": "Research tools",
  "enabled": true,
  "transport": "stdio",
  "command": "your-mcp-server",
  "args": ["--stdio"],
  "env": {}
}
```

Sustituye el comando y los argumentos por los que documente el servidor que instalaste. Los valores de entorno van en el objeto `env`.

```json title="Configuración de servidor remoto"
{
  "name": "Research service",
  "enabled": true,
  "transport": "remote",
  "url": "https://your-server.example/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_TOKEN"
  }
}
```

Sustituye la URL y el token de ejemplo por los datos de conexión del servicio. Usa **Validar** para comprobar la conexión y luego revisa las herramientas que expone el servidor. Activa o desactiva el servidor desde su fila. Usa su acción de edición para cambiar la configuración y su acción de quitar para desconectarlo.

## Importa configuraciones MCP existentes

Elige **Importar de otras herramientas**, inspecciona las configuraciones descubiertas y selecciona los servidores que quieras. Revisa las rutas de los ejecutables, las variables de entorno, las URL y las credenciales antes de importar. Esto importa ajustes de conexión; no instala por ti el ejecutable del servidor.

## Prueba la conexión

1. Abre un proyecto de práctica pequeño en Oleafly.
2. Conecta el cliente externo usando el fragmento copiado de la app.
3. Pide al cliente que llame a `get_status` y enumere los archivos del proyecto.
4. Pídele que lea el documento principal y sugiera un cambio de título.
5. Revisa la acción en Oleafly antes de aprobar una escritura.
6. Compila e inspecciona el PDF.

Para una herramienta externa conectada dentro de Oleafly, empieza con una petición sencilla de solo lectura que admita ese servidor e inspecciona la tarjeta de herramienta resultante en el chat.
