Ir al contenido
Oleaflyv0.4.12

Conexiones

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.

MCP en ambos sentidosEn un sentido, un cliente MCP de tu ordenador, como Claude Desktop, Cursor o Codex, se conecta al servidor MCP de Oleafly en 127.0.0.1 con un token de portador. Puede leer, editar y compilar el proyecto, y tu política de aprobación decide qué cambios te esperan. En el otro sentido, el asistente integrado de Oleafly usa herramientas de los servidores MCP que añadas: un servidor local que ejecuta un comando o un servidor remoto en una URL.Tu cliente MCP usa las herramientas de OleaflyEl asistente de Oleafly usa otros servidores MCPCliente MCPClaude Desktop,Cursor, CodexOleafly MCPSolo 127.0.0.1ProyectoLeer, editar, compilarToken de portadorAprobacionesAsistenteIntegrado en OleaflyServidor localEjecuta un comandoServidor remotoSe conecta a una URLMCP en ambos sentidosEn un sentido, un cliente MCP de tu ordenador, como Claude Desktop, Cursor o Codex, se conecta al servidor MCP de Oleafly en 127.0.0.1 con un token de portador. Puede leer, editar y compilar el proyecto, y tu política de aprobación decide qué cambios te esperan. En el otro sentido, el asistente integrado de Oleafly usa herramientas de los servidores MCP que añadas: un servidor local que ejecuta un comando o un servidor remoto en una URL.Tu cliente MCP usa OleaflyEl asistente de Oleafly usa servidoresCliente MCPClaude Desktop, CursorOleafly MCPSolo 127.0.0.1ProyectoLeer, editar, compilarToken de portadorAprobacionesAsistenteIntegrado en OleaflyServidor localEjecuta un comandoServidor remotoSe conecta a una URL
Un cliente MCP de tu ordenador llega a las herramientas de proyecto de Oleafly a través de 127.0.0.1 y un token. En el otro sentido, el asistente de Oleafly puede usar herramientas de los servidores MCP que añadas.
  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.

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

Ventana del terminal
claude mcp add --transport http oleafly http://127.0.0.1:5323/mcp --header "Authorization: Bearer <token>"

Añade a claude_desktop_config.json (puente stdio mediante mcp-remote, porque Desktop prefiere stdio):

{
"mcpServers": {
"oleafly": {
"command": "npx",
"args": [
"-y",
"mcp-remote@latest",
"http://127.0.0.1:5323/mcp",
"--header",
"Authorization: Bearer <token>",
"--transport",
"http-only"
]
}
}
}

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 (se abre en una pestaña nueva) 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.

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

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

En ~/.grok/config.toml:

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

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:

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

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.

HerramientaQué hace
get_statusVersió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_projectsProyectos con ID, nombres, motores, tipos, documentos principales, marcas de tiempo, colores, estado de la vista previa e historial de exportaciones
open_projectAbrir un proyecto por ID para que las demás herramientas lo usen como destino
list_filesÁrbol de archivos del proyecto
project_mapEsquema, etiquetas, citas, macros, grafo de entradas, referencias sin resolver
search_projectBuscar texto en el proyecto actual
HerramientaQué hace
read_fileLeer un archivo del proyecto
get_logÚltimo registro de compilación
get_pdf_textTexto extraído del PDF compilado
verify_pdf_pagesComprobar 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.

HerramientaQué hace
write_fileEscribir o sobrescribir un archivo
replace_in_fileBuscar y reemplazar dentro de un archivo
create_fileCrear un archivo o una carpeta
rename_fileRenombrar o mover una ruta
delete_fileEliminar un archivo o una carpeta
set_main_docEstablecer el documento de entrada de la compilación
HerramientaQué hace
compileCompilar el proyecto a PDF
preview_figureRenderizar una figura por separado y devolver una imagen PNG
insert_figureInsertar en el documento la última figura previsualizada
load_imageCargar 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.

HerramientaQué hace
toggle_themeAlternar el modo claro / oscuro
HerramientaQué hace
list_skillsEnumerar las habilidades instaladas con su ID, nombre, descripción y si están activadas
load_skillCargar las instrucciones completas de una habilidad y su lista de archivos
read_skill_fileLeer 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.

Estas herramientas están disponibles mientras Notas está activado en Ajustes → Experimentación, como describe Activa Notas. Funcionan con tus notas, no con el proyecto abierto, y necesitan una ventana conectada.

HerramientaQué hace
list_knowledge_notesEnumerar tus notas, las más recientes primero, con ID, títulos, etiquetas, proyectos vinculados y resúmenes breves. Filtra por etiqueta o proyecto
search_notesBuscar en tus notas y devolver ID, títulos, etiquetas, enlaces y fragmentos que coinciden
read_note_by_idLeer una nota como Markdown con su front matter
today_noteLeer la nota diaria de hoy, o el título que tendría si todavía no existe
list_note_tasksEnumerar las tareas con casilla de tus notas, empezando por la nota más reciente. Filtra por nota y por pendientes o hechas
note_backlinksEnumerar las notas que enlazan con una nota, con el texto que rodea cada enlace
append_to_noteAñadir Markdown al final de una nota o de la nota diaria de hoy
edit_note_sectionReescribir la parte de una nota que está bajo un título, o añadir algo al final de ella
create_noteCrear 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.

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.

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

Sección titulada «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.

SíntomaQué probar
Algunas herramientas no están disponiblesLas 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 5323El puerto preferido no estaba disponible, así que Oleafly seleccionó uno libre. Copia la URL real de los Ajustes.
HTTP 401El token no coincide (por ejemplo, tras Regenerar). Copia el token nuevo en el cliente.
HTTP 403El 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 tiempoCada 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 erroresLa 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 conectarOleafly 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.
Ajustes → Asistente de IA → MCP. Añade un servidor, explora el registro o importa configuraciones de otra herramienta.
Ajustes → Asistente de IA → MCP. Añade un servidor, explora el registro o importa configuraciones de otra herramienta. Abrir la captura completa

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 cubre los pasos.

Añadir un servidor → Formulario. Elige Comando local o URL remota, rellena los campos de conexión y usa Añadir y validar.
Añadir un servidor → Formulario. Elige Comando local o URL remota, rellena los campos de conexión y usa Añadir y validar. Abrir la captura completa

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:

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.

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.

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.

  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.

Vista previa de la imagen

No se pudieron cargar las respuestas de la IA

Inténtalo de nuevo o busca en la documentación.