Construir
ES
Codex · Servidor MCP

Servidor MCP para Codex: mensajería y email en su producto

Tres líneas de config.toml conectan el Servidor MCP de Unipile. Después, Codex construye funciones de LinkedIn, WhatsApp y email en su producto.
Conectar Unipile a Codex Obtener una clave API
Prueba gratis de 7 días, sin tarjeta.
Codex · crm-app
Unipile MCP conectado
Sarah
Añade la búsqueda de personas de LinkedIn a mi CRM.
Leer endpointPOST /v2/{account_id}/linkedin/searchesquema cargado
Se han añadido la ruta de búsqueda y la lista de resultados. Cada fila conserva el ID de proveedor del perfil.
3 archivos modificados · probado en la app de Development
Describa la próxima función…
El objetivo

Lo que quiere conseguir

Añadir una conexión de LinkedIn, WhatsApp, email o calendario a su producto. Eso implica leer una referencia de API, elegir los endpoints adecuados, conectar Hosted Auth y sus callbacks, y conservar los IDs correctos desde la búsqueda hasta el mensaje. Con el servidor MCP de Unipile en Codex, el agente hace esa lectura por usted y escribe el código en su stack, desde la CLI, la extensión del IDE o la app de escritorio.
Conecte el servidor MCP de Unipile a CodexUnipile MCP conectado
Seleccione los canales que quiere conectardeveloper.unipile.com/mcp
Conectar todos los canales9 canales
LinkedInLinkedIn/v2/{account_id}/chats
WhatsAppWhatsApp/v2/{account_id}/chats
InstagramInstagram/v2/{account_id}/chats
TelegramTelegram/v2/{account_id}/chats
GmailGmail/v2/{account_id}/emails
OutlookOutlook/v2/{account_id}/emails
IMAPIMAP/v2/{account_id}/emails
Google CalendarGoogle Calendar/v2/{account_id}/calendars
Outlook CalendarOutlook Calendar/v2/{account_id}/calendars
↑↓navegar espacioseleccionar ↵conectaruna URL, una cabecera
Sin ello Pestañas, conjeturas y código pegamento
Codex adivina nombres de endpoints y payloads a partir de sus datos de entrenamiento, y se equivoca con los IDs.
Usted pega esquemas de la referencia en el chat, un endpoint cada vez.
La primera llamada real ocurre en producción, después de la revisión de código.
Con el servidor MCP de Unipile El resultado en su aplicación
Una ruta de conexión y un botón en Settings: cada usuario vincula su propia cuenta mediante Hosted Auth.
Un receptor de webhooks y una bandeja que muestra los mensajes y los emails según llegan.
Todas las peticiones ya ejecutadas una vez en su aplicación de Development antes de que revise el diff.
config.toml, CLI e IDE

Añada el servidor MCP de Unipile a Codex

El servidor es remoto: una URL sobre streamable HTTP y una cabecera. Sin npx, sin proceso local. Una sola entrada en config.toml la leen la CLI de Codex, la extensión del IDE de Codex y la app de escritorio de ChatGPT, así que se configura una única vez.
La CLI de Codex instalada (npm i -g @openai/codex) o la extensión del IDE de Codex, con sesión iniciada.
Una aplicación de Development en el dashboard de Unipile, con un Scope y una clave Account API con scope.
Al menos una cuenta de prueba conectada a ese Scope mediante Hosted Auth, para que el agente pueda ejecutar peticiones reales.
1
codex mcp add y después la cabeceraregistra la URL en ~/.codex/config.toml
G
Configuración global~/.codex/config.toml
P
Configuración de proyecto.codex/config.toml (proyecto de confianza)
E
Clave desde una variable de entornoenv_http_headers
?
¿Por qué dos pasos en la CLI?codex mcp add acepta --url y una variable de token bearer, pero ningún flag para cabeceras personalizadas. El servidor de Unipile se autentica con X-API-KEY, así que el comando registra la URL y la cabecera va en config.toml, a mano o con env_http_headers.
terminal
# 1. Registre el servidor MCP alojado de Unipile (config global) codex mcp add unipile --url "https://developer.unipile.com/mcp?branch=v2.0" # Added global MCP server 'unipile'. # 2. Añada la cabecera X-API-KEY a la entrada de ~/.codex/config.toml [mcp_servers.unipile] url = "https://developer.unipile.com/mcp?branch=v2.0" http_headers = { "X-API-KEY" = "your-scoped-api-key" } # 3. Verifique codex mcp get unipile
[mcp_servers.unipile] url = "https://developer.unipile.com/mcp?branch=v2.0" http_headers = { "X-API-KEY" = "your-scoped-api-key" }
[mcp_servers.unipile] url = "https://developer.unipile.com/mcp?branch=v2.0" http_headers = { "X-API-KEY" = "your-scoped-api-key" } # Solo se lee dentro de un proyecto de confianza. Mantenga la clave fuera de git: prefiera env_http_headers.
[mcp_servers.unipile] url = "https://developer.unipile.com/mcp?branch=v2.0" env_http_headers = { "X-API-KEY" = "UNIPILE_API_KEY" } # export UNIPILE_API_KEY=your-scoped-api-key antes de lanzar codex
Guarde el archivo y reinicie Codex. codex mcp list muestra unipile como activado, y /mcp dentro de una sesión lista el servidor. Verificado en codex-cli 0.154.0.
Qué hace cada línea, verificado en codex-cli 0.154.0
codex mcp add unipileCrea la tabla [mcp_servers.unipile] en el config.toml global. El nombre lo elige usted; manténgalo corto, porque se convierte en el prefijo de las herramientas.
--url "https://developer.unipile.com/mcp?branch=v2.0"Transporte streamable HTTP. Entrecomille la URL: el signo de interrogación es un carácter glob en zsh.
http_headers = { "X-API-KEY" = "…" }Cabecera estática enviada en cada petición. Use su clave Account API con scope, nunca una clave Service ni una Account global.
env_http_headers = { "X-API-KEY" = "UNIPILE_API_KEY" }La misma cabecera, con el valor leído del entorno al arrancar. La forma correcta para un config.toml de proyecto versionado en git.
startup_timeout_sec = 30Opcional. El valor por defecto es 10 s; súbalo si el primer handshake caduca en una red lenta.
enabled = falseOpcional. Desactiva el servidor sin borrar la entrada, útil para alternar entre claves de Development y de Production.
La parte específica de Codex

Mantenga su clave de API fuera de config.toml

http_headers escribe la clave en claro en un archivo que acaba en copias de seguridad y, si es un config de proyecto, en git. Codex tiene tres maneras de enviar la cabecera X-API-KEY; elija la que corresponda al lugar donde vive el archivo.
1http_headers, valor estáticoLa forma que aparece en la documentación de Unipile. Vale para un config de usuario en su propia máquina, nunca para un archivo compartido en un repositorio.http_headers = { "X-API-KEY" = "your-scoped-api-key" }
2env_http_headers, leído al arrancarAsocia el nombre de la cabecera al nombre de una variable de entorno. El archivo no lleva ningún secreto y cada desarrollador exporta su propia clave con scope. Es la forma correcta para un config.toml de proyecto.env_http_headers = { "X-API-KEY" = "UNIPILE_API_KEY" } export UNIPILE_API_KEY=your-scoped-api-key
3http_headers_helper, desde un comandoUn comando local que imprime las cabeceras en JSON, para equipos que obtienen las claves de un vault. Y no olvide CODEX_HOME: cambia todo el directorio de configuración, así que un servidor guardado en un terminal puede faltar en otro.http_headers_helper = "./scripts/unipile-headers.sh"
Verificación

Verifique la conexión

Tres comprobaciones: en la CLI, dentro de una sesión y luego con un prompt que solo lee la especificación. Ninguna toca una cuenta conectada.
1En la CLI de Codexlist imprime una fila por servidor con su URL y su estado. get muestra el transporte, las cabeceras y el comando para eliminarlo.codex mcp list codex mcp get unipile
2Dentro de una sesiónEn la TUI de Codex, en la extensión del IDE (menú del engranaje, MCP servers) y en la app de escritorio de ChatGPT (Settings, MCP servers) aparece la misma entrada: una configuración, tres superficies./mcp # Status enabled, Auth Unsupported es lo esperado: el servidor usa una cabecera, no OAuth
3En un chat, sin tocar ninguna cuentaPida algo que solo lea la especificación de la API. Si el agente responde con rutas y parámetros reales, el servidor está conectado.Con el MCP de Unipile, lista los endpoints de búsqueda de personas en LinkedIn y sus parámetros obligatorios.
Prompts, no código de pegamento

Dé el prompt a su agente

Tres tareas de integración, cada una con el prompt exacto para pegar en Codex, los endpoints de Unipile que el agente lee y ejecuta y lo que llega a su proyecto. Las rutas están completas, sobre la URL base de la API https://api.unipile.com, con su clave con scope en la cabecera X-API-KEY .
Codex · crm-appApp de Development
Añade la búsqueda de personas de LinkedIn a mi CRM y permite al usuario abrir el perfil seleccionado e iniciar una conversación desde él.
Buscar endpoints"linkedin search people profile"3 resultados
Ejecutar peticiónPOST /v2/{account_id}/linkedin/search10 resultados
Se han añadido GET /api/linkedin/search (palabras clave, cursor de paginación) y GET /api/linkedin/profiles/:identifier. La lista de resultados conserva el ID de proveedor devuelto por la búsqueda, la ruta del perfil lo reutiliza y el botón "Mensaje" lo pasa a la creación del chat. Ambas ejecutadas en la app de Development.4 archivos modificados · probado en la app de Development

Un mismo identificador desde el resultado de búsqueda hasta la conversación

Lo difícil de una función de LinkedIn no son las llamadas, sino conservar el mismo identificador desde la fila de búsqueda hasta el perfil y luego hasta el mensaje. Codex lee los tres contratos a través del servidor, ve qué campo lleva ese identificador en cada respuesta y escribe las rutas sin adivinar nada.
Endpoints que usa el agente
POST/v2/{account_id}/linkedin/searchGET/v2/{account_id}/users/{identifier}POST/v2/{account_id}/chats
Error frecuente: Buscar con una cuenta y enviar mensajes con otra. El perfil y el chat deben abrirse con el account_id que ejecutó la búsqueda.
Construya una integración de LinkedIn
Codex · messaging-sdkApp de Development
Genera un cliente tipado en Node.js y Python para las rutas de chats y emails de Unipile que usamos, a partir de los esquemas de la API, con reintentos en caso de 429.
Leer endpointGET /v2/{account_id}/emailsesquema cargado
Ejecutar peticiónGET /v2/{account_id}/chats200 OK
Se han escrito unipile-client.ts y unipile_client.py a partir de los esquemas de petición y respuesta: métodos tipados de listado y envío para chats y emails, helper de paginación por cursor y backoff exponencial en caso de 429 con la cabecera Retry-After. Ambos clientes ejecutaron las llamadas de listado en la app de Development.2 clientes generados · esquemas leídos a través del servidor

Clientes tipados a partir de los esquemas reales, no de memoria

Codex no adivina los payloads. Lee el body de la petición y el esquema de respuesta de cada ruta a través del servidor, genera los tipos y ejecuta una llamada por método en su aplicación de Development antes de que usted revise el diff. Los SDK oficiales de Node.js y Python siguen siendo la referencia; el cliente generado es suyo y puede mantenerlo ligero.
Endpoints que usa el agente
GET/v2/{account_id}/chatsPOST/v2/{account_id}/chats/{chat_id}/messages/sendGET/v2/{account_id}/emailsPOST/v2/{account_id}/emails/send
Error frecuente: Reintentar un envío tras un timeout sin comprobación de idempotencia. Un mensaje puede salir una sola vez: reintente las lecturas, no las escrituras.
Ver los SDK oficiales
Codex · saas-backendApp de Development
Admite varias cuentas conectadas por usuario de mi SaaS: pueden vincular varias cuentas de LinkedIn y email y elegir cuál envía.
Leer endpointGET /v2/accountsesquema cargado
Ejecutar peticiónGET /v2/accounts3 cuentas
Se ha añadido una tabla accounts indexada por usuario y account_id, un selector en el editor de mensajes y POST /api/messages que envía desde la cuenta seleccionada. Los estados de reconexión de la ruta de cuentas se muestran como etiqueta. Verificado con tres cuentas en la app de Development.5 archivos modificados · 3 cuentas, un solo editor

Un usuario, varias cuentas, un Scope por workspace

Cada cuenta que sus usuarios conectan mediante Hosted Auth recibe su propio account_id. El agente diseña la correspondencia entre sus usuarios y esos ID, lee la ruta de estado de la cuenta para mostrar los estados de reconexión y de checkpoint, y dirige cada envío a la cuenta que eligió el usuario.
Endpoints que usa el agente
GET/v2/accountsGET/v2/accounts/{account_id}POST/v2/auth/linkPOST/v2/{account_id}/chats
Error frecuente: Guardar el ID de cuenta en el workspace en lugar de en el usuario. Las cuentas pertenecen a la persona que las conectó; el workspace solo agrupa Scopes y claves.
Implemente Hosted Auth con un agente
De Development a producción

Pruebe primero en una aplicación de Development

El dashboard de Unipile separa una aplicación de Development de otra de Production. Dé a Codex una clave con scope de la aplicación de Development, con una o dos cuentas de prueba conectadas mediante Hosted Auth. El agente ejecuta peticiones reales sobre esas cuentas, en nombre del usuario autenticado que las vinculó, dentro de los límites de cada proveedor, y nada toca las cuentas de sus usuarios hasta que publique. Mantenga default_tools_approval_mode en prompt mientras construye si quiere confirmar cada escritura.
Valide el flujo de conexión de extremo a extremo: enlace de autenticación creado en el servidor, ID de cuenta guardado en el usuario.
Valide una lectura y una escritura por funcionalidad: listar chats, enviar un mensaje desde la cuenta de prueba.
Valide una entrega de webhook y un estado de reconexión o de checkpoint antes de cambiar la clave a Production.
crm-app · DevelopmentUsada por Codex
Scopedev-tests · 2 cuentas
Clavescoped Account API key
CuentasCuenta de prueba LinkedIn, buzón de prueba Gmail
Webhooks1 endpoint · eventos de mensaje
crm-app · ProductionSin tocar
Scopeuno por workspace
Clavescoped keys, in your backend only
Cuentaslas cuentas propias de sus usuarios, vía Hosted Auth
Resolución de problemas

Errores habituales y qué significan

Lo que ve cuando una entrada MCP de Codex no está bien, y cómo se corrige cada caso. Casi siempre se reduce al archivo, al TOML, al nivel de confianza o a la clave.
El servidor no aparece tras editar config.toml
codex mcp list no imprime nada, o la entrada falta dentro de una sesión. SoluciónReinicie el cliente: el archivo se lee al arrancar. Compruebe después CODEX_HOME: cambia todo el directorio de configuración, así que un servidor guardado en un terminal puede ser invisible en otro. Ejecute codex mcp list en el mismo shell desde el que lanza Codex.
La configuración de proyecto se ignora
.codex/config.toml está en la raíz del repositorio y Codex sigue usando la entrada global, o ninguna. SoluciónCodex carga la capa de proyecto solo para un proyecto de confianza. Márquelo con trust_level = "trusted" bajo [projects."/path/to/repo"] en el config de usuario, o mueva la entrada a ~/.codex/config.toml.
TOML inválido
El archivo no se puede analizar y todos los servidores desaparecen de golpe. SoluciónUna tabla llamada exactamente [mcp_servers.unipile] , comillas alrededor de "X-API-KEY" en la tabla de cabeceras, y una tabla, no una cadena, para http_headers. Una llave sin cerrar tumba todo el archivo.
401 Unauthorized en las peticiones
El servidor aparece listado y lee la especificación, pero ejecutar una petición falla. SoluciónFalta la cabecera, la variable indicada en env_http_headers no está exportada en el shell que lanzó Codex, o la clave es una Service o una Account global en lugar de una clave Account API con scope de su aplicación de Development.
Los ajustes dicen que el servidor no está disponible
La extensión del IDE o la app de escritorio marcan el servidor, pero las acciones funcionan. SoluciónEsa comprobación busca recursos, y el servidor de Unipile expone acciones, no recursos. Confírmelo con /mcp dentro de una sesión y ejecutando una llamada de lectura. No hay nada que cambiar por su parte.
Timed out
El arranque o una llamada superan el límite. SoluciónLos valores por defecto son startup_timeout_sec = 10 y tool_timeout_sec = 60. El servidor es remoto y no hay ningún proceso que arrancar: compruebe la URL (?branch=v2.0 incluido), la red y cualquier proxy corporativo antes de subir los timeouts.
6000+ Empresas que innovan con Unipile
La confianza de los líderes del sector
1 API
Racionalizar las operaciones de los principales canales de comunicación
2 días
Rápida integración en directo con una configuración mínima
30%
Reducción de los esfuerzos y recursos de mantenimiento

Seguridad y conformidad integradas

Protección de nivel empresarial para sus datos y flujos de trabajo Más información sobre nuestra seguridad
SOC 2 Tipo II
SOC 2 Tipo II
Certificado
Controles de seguridad auditados de forma independiente que garantizan la protección de datos y la integridad operativa.
GDPR
GDPR
Conforme
Pleno cumplimiento de la normativa europea de protección de datos para la privacidad de los usuarios.
99.9%
Tiempo de actividad de la plataforma en los últimos 24 meses
24/7
Asistencia global con API de alto rendimiento

FAQ del servidor MCP en Codex

Las preguntas que la gente escribe de verdad: config.toml en lugar de mcp.json, dónde vive, codex mcp add, cómo mantener la clave fuera del archivo, las tres superficies, qué comprobar cuando no aparece nada, timeouts y claves.
No. Codex guarda su configuración MCP en ~/.codex/config.toml, en TOML, con una tabla por servidor llamada [mcp_servers.<name>]. En Codex no hay ningún mcp.json, y el archivo no se crea al instalar: lo crea usted, o lo crea codex mcp add por usted. Un proyecto de confianza también puede llevar un .codex/config.toml en su raíz.
~/.codex/config.toml para la configuración de usuario, .codex/config.toml en la raíz del repositorio para la configuración de proyecto. La variable de entorno CODEX_HOME cambia todo el directorio de configuración: cuando un servidor aparece en un terminal y no en otro, compruébela primero. La CLI de Codex, la extensión del IDE y la app de escritorio leen el mismo archivo.
En parte. codex mcp add unipile --url "https://developer.unipile.com/mcp?branch=v2.0" escribe la tabla para un servidor streamable HTTP, y --bearer-token-env-var cubre los servidores que aceptan un token Bearer. El servidor de Unipile se autentica con una cabecera X-API-KEY , que el comando no puede definir, así que añada http_headers o env_http_headers a la entrada que ha creado. Verificado en codex-cli 0.154.0.
Use env_http_headers = { "X-API-KEY" = "UNIPILE_API_KEY" }: asocia el nombre de la cabecera al nombre de una variable de entorno en lugar de a un valor, de modo que el archivo se puede versionar sin ningún secreto y cada desarrollador exporta su propia clave Account API con scope. http_headers sirve para valores estáticos, y http_headers_helper permite que un comando local produzca las cabeceras en JSON.
Sí. Las tres superficies de un mismo host de Codex leen la misma configuración, así que un servidor añadido una vez está disponible en todas partes. En la app de escritorio y en la extensión también puede añadirlo desde Settings, MCP servers, Add server, eligiendo Streamable HTTP. Reinicie el cliente después de guardar el archivo.
Cuatro causas, por orden: no se ha reiniciado el cliente; el archivo está bajo un CODEX_HOME distinto del de su shell actual; la tabla está en un .codex/config.toml de proyecto y el proyecto no está marcado como trust_level = "trusted", en cuyo caso Codex omite por completo la capa de proyecto; o el TOML no es válido. Ejecute codex mcp list, y después /mcp dentro de una sesión.
startup_timeout_sec sustituye el timeout de arranque de 10 segundos por defecto y tool_timeout_sec el de 60 segundos por herramienta, ambos dentro de la tabla del servidor. El servidor de Unipile es remoto por HTTP y no hay ningún proceso local que arrancar, así que un timeout de arranque casi siempre apunta a la URL, a la red o a un proxy corporativo, no al servidor.
El servidor responde sin clave cuando el agente solo lee la especificación de la API. Para ejecutar peticiones reales, cree un Scope en su aplicación de Development, asigne las cuentas de prueba y genere una clave Account API con scope para ese Scope. Nunca dé a un cliente MCP una clave Service ni una clave Account global.