Skip to main content
Usa esta guía si quieres que Codex trabaje con tus datos de Paperzilla. Codex admite dos vías para Paperzilla:
  • Paperzilla MCP para llamadas nativas a herramientas mediante el endpoint MCP
  • CLI de Paperzilla (pz) para flujos locales de terminal
No necesitas un plugin para la configuración básica de MCP. Para la mayoría, la configuración de MCP más sencilla está en Integrations & MCP de Codex. Usa un plugin solo si quieres un paquete instalable de Codex con instrucciones de Paperzilla, una declaración de endpoint MCP de Paperzilla, una skill de CLI de Paperzilla o una combinación.

​
Elegir la vía adecuada

Usa Paperzilla MCP cuando:
  • quieres que Codex razone directamente sobre herramientas de Paperzilla
  • no quieres tener pz como dependencia local
  • quieres la misma superficie remota de Paperzilla que usas con otros clientes MCP
  • prefieres una configuración gráfica en la aplicación Codex
Usa pz cuando:
  • Codex ya trabaja en la terminal o repositorio donde está instalado pz
  • quieres resultados deterministas de CLI
  • quieres reutilizar pz login en una sesión existente
Usa un plugin de Codex cuando:
  • quieres distribuir una configuración reutilizable de Codex a un equipo
  • quieres un paquete instalable en lugar de configurar manualmente la skill y MCP
No uses un plugin de Codex solo para conectar Paperzilla MCP. Las instalaciones actuales de plugins de Codex no recopilan claves de API de Paperzilla MCP para servidores MCP sin OAuth. Aunque instales un plugin de Paperzilla para Codex, conecta Paperzilla en Integrations & MCP o configura la clave de MCP en la configuración de MCP de Codex.

​
Antes de empezar

  • Una cuenta de Paperzilla con al menos un proyecto
  • Acceso a Codex en el cliente que usas
  • Tu clave de API de MCP de Paperzilla desde Clave de API de MCP en el panel para la vía MCP
  • pz instalado y autenticado con pz login para la vía CLI

​
Opción 1: añadir Paperzilla MCP en la configuración de Codex

Codex admite servidores MCP mediante Streamable HTTP. En la aplicación Codex, añade Paperzilla desde Settings > Integrations & MCP.

​
Paso 1: copiar la clave MCP de Paperzilla

  1. Abre tu panel.
  2. Haz clic en Clave de API de MCP.
  3. Genera o copia la clave.
  4. Mantenla en privado.

​
Paso 2: añadir Paperzilla en Integrations & MCP

  1. Abre la configuración de Codex. En macOS, pulsa Cmd + ,.
  2. Abre Integrations & MCP.
  3. Haz clic en Add your own o la acción equivalente para un servidor MCP personalizado.
  4. En Connect to a custom MCP, completa la configuración así:
Sustituye pzmcp_... por tu clave real. Comprueba que seleccionaste Streamable HTTP. No uses STDIO para Paperzilla. Si aún ves campos como Command to launch, Arguments, Environment variables o Working directory, sigues en la pantalla STDIO.
  1. Haz clic en Save.
Configuración MCP de Codex con Paperzilla como servidor Streamable HTTP y una URL de Paperzilla MCP ocultada.

Añadir Paperzilla como servidor MCP personalizado en Codex

La URL MCP completa debe tener este aspecto:
Esta es la configuración más sencilla de la aplicación Codex porque se adapta a clientes que solo solicitan una URL de servidor MCP. Si prefieres autenticación por encabezado o la aplicación Codex abre el archivo para configuración avanzada, usa este bloque de ~/.codex/config.toml:
Sustituye pzmcp_... por tu clave MCP real de Paperzilla. No necesitas una variable de entorno independiente. La URL ?key=<key> es más sencilla en la interfaz gráfica. El bloque http_headers resulta más limpio para quienes editan la configuración de Codex.

​
Paso 3: confirmar que el servidor está activo

En Codex, ejecuta /mcp o /mcp paperzilla para confirmar que paperzilla está disponible y activo. En la aplicación Codex, la entrada de Paperzilla debe mostrar Enabled. La columna Auth puede mostrar Unsupported. En esta configuración, significa que Codex no ofrece un inicio OAuth interactivo para Paperzilla; no demuestra que falte la clave estática de http_headers de API. Si no ves de inmediato la configuración actualizada, vuelve a abrir Codex y compruébala. Después, pide a Codex cosas como:
  • «Lista mis proyectos de Paperzilla».
  • «Muestra los artículos de lectura imprescindible de esta semana de mi proyecto de agentes».
  • «Busca artículos sobre grafos de proximidad en mi proyecto de evaluación».
  • «Obtén el Markdown del artículo de lectura imprescindible más reciente de mi proyecto de recuperación».
Para conocer el contrato MCP genérico y todas las herramientas, consulta Usar Paperzilla con MCP.

​
Cómo usa Codex Paperzilla MCP

En la práctica, Codex suele seguir un flujo como este:
  • projects_list para encontrar el proyecto
  • projects_get cuando necesitas la configuración o los detalles del proyecto
  • feed_get para explorar la lista
  • feed_search para buscar por título, autor, resumen del artículo o resumen con IA en toda la lista
  • paper_get cuando necesitas metadatos independientes
  • paper_markdown cuando tienes el ID del artículo canónico
Los resultados incluyen el ID de recomendación del proyecto y los metadatos anidados del artículo canónico. Como feed_get y feed_search ya incluyen metadatos, Codex suele omitir paper_get salvo que necesite una búsqueda independiente. Por tanto, un patrón habitual de Codex con MCP es:
  1. Buscar en la lista con feed_search.
  2. Tomar el paper.id del resultado.
  3. Llamar a paper_markdown con ese ID.
paper_markdown devuelve un estado estructurado:
  • ready cuando el contenido Markdown se devuelve de inmediato
  • queued cuando Paperzilla aceptó la solicitud pero aún no está listo
  • unavailable cuando el artículo no tiene una fuente Markdown utilizable
Para forzar la vía MCP cuando están disponibles tanto MCP como CLI, indícalo explícitamente. Por ejemplo:
  • «Usa paperzilla como servidor MCP. No uses pz».

​
Opcional: añadir una skill de Codex para un comportamiento MCP repetible

Sí. Para la vía MCP, la skill debe hacer más que indicar «preferir Paperzilla». Una buena skill de Codex explica lo que Codex necesita para que la vía de Paperzilla MCP funcione de forma fiable:
  • cuándo debe activarse
  • cómo verificar que paperzilla está instalado y activo como servidor MCP
  • dónde está la documentación de configuración de Paperzilla
  • qué secuencia de herramientas de Paperzilla MCP seguir
  • cuándo no recurrir a pz
  • que la autenticación pertenece a Codex en Integrations & MCP o a la configuración MCP de Codex, no a la skill
Esto coincide con el funcionamiento previsto de Codex: una skill puede agrupar instrucciones, referencias y scripts opcionales para un flujo reutilizable. Guarda una skill del repositorio en .agents/skills/paperzilla-mcp/ o una personal en $HOME/.agents/skills/paperzilla-mcp/. Una estructura práctica es:
SKILL.md contiene las instrucciones del flujo. references/setup.md contiene el contexto de instalación y solución de problemas que Codex puede consultar. Ejemplo recomendado:
Ejemplo de references/setup.md:
Esta estructura proporciona a Codex el flujo y las notas de apoyo. La skill se mantiene específica y el contexto más largo reside en references/. Puedes invocar la skill con /skills o mencionando $paperzilla-mcp. Codex también puede seleccionarla mediante description cuando coincida la tarea.

​
Opción 2: permitir que Codex use la CLI de Paperzilla

Codex ya puede ejecutar comandos del shell en tu espacio. Por tanto, la vía CLI funciona sin una skill personalizada de Codex.

​
Paso 1: confirmar que la CLI funciona donde se ejecuta Codex

Si pz project list no funciona en el mismo entorno donde se ejecuta Codex, corrígelo primero.

​
Paso 2: pedir a Codex que use pz

Puedes pedir cosas como:
  • «Usa pz para listar mis proyectos de Paperzilla».
  • «Usa pz para mostrar los artículos Must Read más recientes de mi proyecto de agentes».
  • «Usa pz feed search para buscar grafos de proximidad en mi proyecto de evaluación».
  • «Usa pz para obtener el Markdown de ese artículo».
En la práctica, Codex suele seguir este flujo de CLI:
Este flujo coincide con la forma en que Paperzilla separa las recomendaciones del proyecto de los artículos canónicos. pz project list --json devuelve una matriz resumida que suele bastar para que Codex elija el project-id correcto.

​
Cómo usa Codex los objetos de Paperzilla

  • pz project list proporciona a Codex el ID necesario para trabajar con el proyecto
  • pz feed y pz feed search devuelven recomendaciones de una lista
  • cada recomendación incluye su ID y el ID del artículo canónico
  • pz paper es la vía adecuada para metadatos canónicos
  • pz rec es la vía adecuada para contexto como Must Read frente a Related, valoraciones y puesta en cola de Markdown
Si este modelo es nuevo para ti, consulta ¿Cuál es la diferencia entre un artículo canónico y una recomendación?.

​
Resultados JSON y comportamiento de Markdown

Usa --json cuando Codex deba leer resultados estructurados en lugar de tablas de terminal. En la CLI, --json está disponible en project list, project, feed, feed search, paper, rec y feedback. Las excepciones principales son login y update. El comportamiento de Markdown también depende del objeto:
  • pz paper <paper-id> --markdown imprime Markdown solo cuando ya está listo
  • pz rec <project-paper-id> --markdown puede poner en cola la generación porque tiene contexto del proyecto
Para Codex y otros agentes, pz rec --markdown suele ser mejor después de una búsqueda.

​
Opcional: añadir una skill de Codex para un comportamiento CLI repetible

Una skill de Codex resulta útil para que Codex sepa cuándo usar pz sin volver a explicar el flujo. Guarda una skill del repositorio en .agents/skills/paperzilla-cli/SKILL.md o una personal en $HOME/.agents/skills/.... Ejemplo mínimo:
La skill enseña a Codex a usar pz. No sustituye el binario pz ni el inicio de sesión en Paperzilla.

​
Cuándo merece la pena un plugin

No necesitas un plugin solo para conectar Codex con Paperzilla MCP. Crea un plugin de Codex solo si quieres un paquete reutilizable e instalable para otros usuarios de Codex. El plugin puede agrupar:
  • la declaración del endpoint MCP de Paperzilla
  • una skill para flujos de Paperzilla MCP
  • un directorio skills/ para flujos de CLI de Paperzilla
  • ambas opciones para incluir MCP y CLI en un paquete
Para Paperzilla MCP, el plugin no elimina la necesidad del bloque de autenticación MCP de Codex:
Para usuarios normales, usa Settings > Integrations & MCP. Si solo instalas desde la interfaz Plugins de Codex, verifica /mcp paperzilla antes de esperar herramientas activas de Paperzilla. En otras palabras:
  • servidor MCP: superficie de integración de Paperzilla
  • skill: instrucciones para que Codex use Paperzilla mediante MCP, CLI o ambos
  • plugin: contenedor de distribución de uno o ambos
Si después quieres publicar una configuración de Codex, agrupar la configuración MCP de Paperzilla y una o varias skills de Paperzilla en un plugin es el siguiente paso adecuado.

​
Solucionar el acceso MCP del plugin

Si Codex indica que no están expuestas las herramientas de Paperzilla MCP, la skill puede estar instalada sin paperzilla como servidor MCP autenticado. Comprueba /mcp paperzilla primero. Si falta Paperzilla, añade Paperzilla desde Settings > Integrations & MCP o agrega el bloque mcp_servers.paperzilla anterior. Si Paperzilla aparece con Auth unsupported y Enabled, puede ser normal con una clave estática. Prueba una solicitud real de Paperzilla. Si falla, comprueba que la URL MCP personalizada para la clave de API incluye ?key=... o que ~/.codex/config.toml contiene http_headers para la autenticación. Si Paperzilla aparece pero falla la autenticación, regenera la Clave de API de MCP en el panel de Paperzilla y actualiza el mismo bloque. No lo resuelvas reinstalando la skill. Esta indica a Codex cómo usar Paperzilla cuando el servidor MCP está disponible; no autentica el servidor MCP por sí sola.

​
Contenido relacionado