# Shager en OpenAI Codex: config.toml, bearer_token_env_var y una lista de herramientas que deja los borradores como borradores

_2026-08-20 · 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](https://developers.openai.com/codex/mcp) de OpenAI describe servidores HTTP con streaming configurados con una `url`, más tres formas de autenticarse con encabezados. La [referencia de configuración](https://developers.openai.com/codex/config-reference) 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:

```toml
[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:

```bash
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](https://github.com/openai/codex/blob/main/codex-rs/cli/src/mcp_cmd.rs)):

```bash
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:

```bash
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:

```toml
[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:

```toml
[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:

```text
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](/en/blog/utm-per-account-lead-attribution).

## ¿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](/en/blog/skill-weekly-distribution-routine) 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](/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](https://app.shager.ai/api/v1/openapi.json) 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](/en/blog/shager-rest-api-quickstart) 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.

---
Source: https://shager.ai/es/blog/connect-shager-to-codex