Shager en OpenAI Codex: config.toml, bearer_token_env_var y una lista de herramientas que deja los borradores como borradores
Configura el servidor MCP de Shager en Codex CLI con config.toml o codex mcp add, lee la clave de una variable, limita las herramientas y crea un borrador.
Para conectar Shager a Codex CLI de OpenAI, agrega una tabla [mcp_servers.shager] en ~/.codex/config.toml con url = "https://app.shager.ai/api/mcp" y bearer_token_env_var = "SHAGER_API_KEY", y luego exporta tu clave shgr_live_ en esa variable. Codex habla HTTP con streaming de forma nativa y envía la clave como token bearer, así que no hace falta ningún puente ni proceso local. También puedes hacerlo en una sola línea con codex mcp add shager --url ... --bearer-token-env-var SHAGER_API_KEY.
El resto de esta guía trata de hacerlo de una forma de la que no te vas a arrepentir: mantener la clave fuera del archivo, limitar qué herramientas de Shager puede llamar Codex y elegir una primera tarea que demuestre que todo está bien conectado.
¿Qué admite Codex para servidores MCP remotos?
La documentación de MCP de Codex de OpenAI describe servidores HTTP con streaming configurados con una url, más tres formas de autenticarse con encabezados. La referencia de configuración las define así:
| Clave | Qué hace |
|---|---|
bearer_token_env_var |
Nombre de una variable de entorno cuyo valor se envía como token bearer |
http_headers |
Encabezados fijos que se incluyen en cada solicitud |
env_http_headers |
Encabezados cuyos valores se leen de variables de entorno |
Shager espera Authorization: Bearer shgr_live_..., que es exactamente lo que produce bearer_token_env_var. Esa es la opción que hay que usar.
Opción A: editar config.toml
Abre ~/.codex/config.toml y agrega:
[mcp_servers.shager]
url = "https://app.shager.ai/api/mcp"
bearer_token_env_var = "SHAGER_API_KEY"
Después pon la clave en el perfil de tu shell, no en el TOML:
export SHAGER_API_KEY="shgr_live_your_key_here"
Fíjate en que la configuración guarda el nombre de la variable, no la clave. Eso significa que puedes subir o compartir el fragmento sin problema, y cada compañero aporta su propia clave. Tener una clave por persona rinde frutos más adelante, porque el registro de auditoría de Shager en https://app.shager.ai/dashboard/agents asocia cada llamada a la clave que la hizo.
Opción B: codex mcp add
La CLI escribe la misma tabla por ti. El código fuente de Codex para codex mcp add define --url para servidores HTTP con streaming y un parámetro --bearer-token-env-var que lo requiere (mcp_cmd.rs en GitHub):
codex mcp add shager \
--url https://app.shager.ai/api/mcp \
--bearer-token-env-var SHAGER_API_KEY
Si tu versión instalada es distinta, codex mcp add --help es la referencia definitiva.
Revisa el resultado:
codex mcp list
Dentro de la interfaz de terminal de Codex, /mcp muestra los servidores activos y sus herramientas.
¿Conviene usar http_headers en su lugar?
Se puede, pero no conviene. http_headers = { "Authorization" = "Bearer shgr_live_..." } funciona, pero deja una credencial activa en un archivo de texto plano que suele terminar copiado en repositorios de dotfiles. Si necesitas un encabezado distinto del token bearer, env_http_headers asocia el nombre de un encabezado con el nombre de una variable de entorno:
[mcp_servers.shager]
url = "https://app.shager.ai/api/mcp"
env_http_headers = { "Authorization" = "SHAGER_AUTH_HEADER" }
Con esa forma, la variable debe contener el valor completo, incluido el esquema: export SHAGER_AUTH_HEADER="Bearer shgr_live_...". Para Shager, bearer_token_env_var es más simple y hace lo mismo.
¿Cómo limitas lo que Codex puede hacer en Shager?
Esta es la parte que la mayoría de las guías de configuración se saltan. Codex te permite filtrar las herramientas de un servidor con enabled_tools (una lista de permitidos) y disabled_tools (una lista de bloqueados que se aplica después), ambas documentadas en la referencia de configuración. Si lo combinas con los permisos de la clave de Shager, obtienes dos capas que, ante la duda, bloquean.
Un perfil de redacción que puede leer todo y crear borradores, pero no puede programar, cancelar ni crear enlaces de conexión:
[mcp_servers.shager]
url = "https://app.shager.ai/api/mcp"
bearer_token_env_var = "SHAGER_API_KEY"
enabled_tools = [
"whoami",
"list_workspaces",
"list_channels",
"list_groups",
"upload_media_from_url",
"create_post",
"get_post",
"list_posts",
"get_analytics",
]
tool_timeout_sec = 120
create_post sigue en la lista porque, sin schedule_at, solo guarda un borrador. Si además la clave no tiene el permiso publish, Shager rechaza con un 403 cualquier create_post que incluya schedule_at, así que ni el modelo más creativo puede colar una publicación programada.
El aumento de tool_timeout_sec está ahí porque upload_media_from_url descarga el archivo en el servidor, y un video vertical pesado puede tardar más que los 60 segundos predeterminados que indica la referencia.
Una primera tarea que vale la pena ejecutar
Empieza con un prompt que toque varias herramientas y deje solo un borrador:
Use the shager MCP server.
1. whoami, then list_workspaces.
2. In workspace "Lakeside Realty", list_channels and list_groups.
3. upload_media_from_url https://example.com/media/open-house.jpg
4. create_post as a draft to group "All agents" with a different caption per
channel (per_channel), mentioning each agent's neighborhood from the channel
name. cta_url https://lakesiderealty.example/open-house, campaign
"open-house-oct", first_comment "Details and RSVP: " followed by the link.
5. get_post and print a table of channel, network, format and state.
Lo que deberías ver: una publicación en estado DRAFT con un destino por cuenta, cada uno con su formato resuelto para esa red. En Shager, cada cuenta recibe su propio enlace corto y sus etiquetas UTM para el cta_url, con utm_content indicando la cuenta, que es lo que después permite atribuir resultados por cuenta. Los detalles están en atribución de leads por cuenta.
¿Codex puede ejecutar esto sin una persona frente al teclado?
Codex tiene un modo no interactivo, codex exec, para scripts y CI. La forma en que se comportan las aprobaciones de herramientas MCP en una ejecución sin interfaz ha cambiado entre versiones, así que haz una prueba en seco con tu versión instalada antes de ponerlo a correr con un temporizador. Para una tarea que tiene que ejecutarse sola cada semana, muchos equipos se saltan la capa de chat y llaman a la API REST de Shager desde un script corto, que no tiene confirmaciones en las que quedarse trabado. Elijas lo que elijas, dale a la tarea su propia clave, mantén ajustada la lista de herramientas permitidas y decide a conciencia si esa clave lleva publish. En la rutina semanal de distribución se describe una rutina construida en torno a esas decisiones.
Resolución de problemas
| Lo que ves | Causa | Solución |
|---|---|---|
401 unauthorized |
La variable no está exportada en la shell desde la que abriste Codex | echo $SHAGER_API_KEY en esa misma terminal y luego reinicia Codex |
Faltan herramientas en /mcp |
El nombre no está en enabled_tools, o está en disabled_tools |
Compara cómo está escrito con la lista de herramientas de /en/agents |
403 sandbox_unclaimed |
La clave salió del registro autónomo de un agente y ninguna persona la reclamó | Envíale el claim_url a una persona |
403 forbidden al programar |
La clave no tiene publish |
Es lo esperado en una clave de redacción |
429 rate_limited |
Más de 120 solicitudes por minuto por clave | Usa grupos y un solo create_post en lugar de una llamada por cuenta |
Preguntas frecuentes
¿Codex necesita OAuth para comunicarse con Shager?
No. Codex admite tokens bearer tomados de una variable de entorno, y Shager acepta una clave de API de esa forma. El servidor MCP de Shager también admite inicio de sesión con OAuth, y Codex admite servidores con OAuth, así que puedes iniciar sesión si prefieres no gestionar una clave.
¿La configuración de Shager cambia en la extensión de Codex para el IDE?
La documentación de MCP de OpenAI dice que la app de escritorio de ChatGPT, Codex CLI y la extensión para el IDE comparten esta configuración, así que la misma tabla en ~/.codex/config.toml sirve para todos. Asegúrate de que el proceso del editor vea la variable de entorno; en macOS, eso puede implicar abrir el editor desde una terminal.
¿Puedo apuntar Codex a la API REST en lugar de a MCP?
Sí, si estás escribiendo código y no chateando. El documento OpenAPI describe las mismas operaciones que las herramientas MCP, con los mismos permisos y límites.
Siguiente paso
Con Codex conectado, familiarízate con las operaciones antes de automatizar nada. La guía rápida de la API REST recorre la secuencia completa, desde el espacio de trabajo hasta la publicación con seguimiento, con curl y Python, y eso también te ayuda a entender lo que hace Codex cuando llama a las herramientas MCP.
