# Conecta SocialCutter a Codex CLI por MCP
> Registra el servidor MCP de SocialCutter en ~/.codex/config.toml con http_headers o env_http_headers, da de alta con codex mcp add y verifica con /mcp.
- URL: https://socialcutter.theboomer.dev/guias/codex-cli/
- Idioma: es
- Familia: ia
- Actualizado: 2026-09-24
- Palabras clave: Codex CLI, MCP, SocialCutter, config.toml, X-API-Key, http_headers, API key
## Qué aporta el MCP de SocialCutter en Codex CLI

Codex CLI es el agente de terminal de OpenAI. Trabaja sobre tu repositorio, ejecuta comandos y propone cambios; si le conectas el servidor MCP de SocialCutter obtiene **28 herramientas** para generar formatos de imagen desde la misma sesión.

El servidor está desplegado en transporte HTTP con streaming:

```
https://mcp.socialcutter.theboomer.dev/mcp
```

Se identifica como `@theboomerdev/socialcutter-mcp` versión **1.1.0**. SocialCutter admite las dos cabeceras: **`X-API-Key: sc_...`** y **`Authorization: Bearer sc_...`**. Usa la que documente tu cliente; el resultado es el mismo. Un `Bearer` sin el prefijo `sc_` se trata como token de sesión y dará 401. Ninguna herramienta acepta la clave como argumento, así que el cliente necesita mandar cabeceras personalizadas.

Las herramientas públicas (`list_platforms`, `list_formats`, `list_fit_modes`, `get_health`, `get_pricing_plans`, `get_credit_packs`) responden sin credenciales y sirven para comprobar la conexión antes de tener la clave. Las privadas (`process_image`, `process_batch`, `get_wallet`, `get_history` y el resto) devuelven `401` si la cabecera no llega.

## La tabla del servidor en ~/.codex/config.toml

Codex CLI lee los servidores MCP de TOML, no de JSON. La configuración global vive en `~/.codex/config.toml` y la de proyecto en `.codex/config.toml`. La entrada es una tabla:

```toml
[mcp_servers.socialcutter]
url = "https://mcp.socialcutter.theboomer.dev/mcp"
http_headers = { "X-API-Key" = "sc_tu_clave" }
# Mismo resultado con la otra cabecera: http_headers = { "Authorization" = "Bearer sc_tu_clave" }
```

La clave `url` apunta al endpoint HTTP. `http_headers` es el mapa de cabeceras que Codex añade a cada petición: ahí va la nuestra, `X-API-Key`, o bien `Authorization: Bearer sc_tu_clave`, que autentica exactamente igual.

### Sin el secreto en claro: env_http_headers

Escribir la clave en `config.toml` es cómodo pero deja el secreto en disco en texto plano. La alternativa es `env_http_headers`, que en lugar del valor pide el **nombre de una variable de entorno**:

```toml
[mcp_servers.socialcutter]
url = "https://mcp.socialcutter.theboomer.dev/mcp"
env_http_headers = { "X-API-Key" = "SOCIALCUTTER_API_KEY" }
```

Codex lee el valor de `SOCIALCUTTER_API_KEY` del propio proceso, así que la clave no queda escrita en el fichero. Exporta la variable en tu shell o en el gestor de secretos de tu sistema:

```bash
export SOCIALCUTTER_API_KEY="sc_tu_clave"
```

| Campo | Para qué sirve |
|---|---|
| `url` | Endpoint del servidor MCP |
| `http_headers` | Cabeceras con el valor literal, incluida la clave |
| `env_http_headers` | Cabeceras cuyo valor se toma de una variable de entorno |
| `startup_timeout_sec` | Segundos que Codex espera en el arranque (10 por defecto) |
| `tool_timeout_sec` | Segundos máximos por llamada a una herramienta (60 por defecto) |
| `enabled_tools` / `disabled_tools` | Listas para dejar fuera herramientas que no quieras exponer |

Usa `http_headers` en una máquina de confianza y `env_http_headers` siempre que el fichero pueda compartirse, versionarse o quedar en una imagen. Como la configuración se comparte con la extensión de IDE, una clave escrita aquí también queda disponible para el editor.

## Alta con codex mcp add --url

Si prefieres que Codex escriba la entrada base, usa el subcomando `mcp add`:

```bash
codex mcp add socialcutter --url https://mcp.socialcutter.theboomer.dev/mcp
```

El comando crea la tabla `[mcp_servers.socialcutter]` con la URL. Después abre `config.toml` y añade `http_headers` o `env_http_headers` con `X-API-Key`: el alta por CLI no conoce nuestra cabecera y hay que declararla a mano. Evita pegar la clave en el chat del agente o en el historial del shell.

## Verificar: codex mcp list y /mcp

```bash
codex mcp list
codex mcp get socialcutter
```

`codex mcp list` muestra los servidores registrados y su estado; `codex mcp get socialcutter` da el detalle de la entrada. Dentro de la interfaz interactiva de Codex, el comando `/mcp` lista los servidores activos y las herramientas que exponen: ahí confirmas que aparece `socialcutter` con su catálogo.

Para una prueba real, pide una herramienta pública:

> Lista las plataformas y sus formatos.

Si vuelve el catálogo con las medidas, el transporte y la URL están bien. Luego pide el monedero para confirmar que `X-API-Key` llega de verdad.

## Tres usos en lenguaje natural

| Lo que escribes | Herramienta | Qué devuelve |
|---|---|---|
| «Coge https://ejemplo.com/maestra.jpg y genera los 13 destinos» | `process_image` | Un `image_id` y una URL por destino |
| «Procesa esta lista de imágenes en lote» | `process_batch` | Un resultado por imagen con sus salidas |
| «Enséñame el monedero y los usos que me quedan» | `get_credits` y `get_wallet` | Usos del día, bolsa extra y saldo comprado |

El catálogo público son **6 plataformas** y **13 destinos**, donde un destino es la combinación de plataforma y formato. Convertir una maestra a los 13 destinos consume 13 usos y se resuelve en una sola llamada a `process_image`, cuyos argumentos obligatorios son `source_url` y `destinations`.

`process_batch` recibe el argumento `images` y resuelve varias imágenes de una vez, con el mismo coste de 1 uso por destino. `get_history` no exige argumentos (tiene dos opcionales) y `get_image` necesita `image_id` para recuperar un trabajo anterior.

La frontera del producto es la misma que en la API: SocialCutter **genera los archivos**, no publica en redes ni edita la imagen. El recorte es **centrado**, con modos `cover`, `contain`, `fill` y `stretch`, y sin análisis del contenido. La salida es `webp`, `jpg` o `png` con calidad de 1 a 100 (85 por defecto), y cada imagen admite hasta 5 MB.

## Errores típicos

| Síntoma | Causa | Solución |
|---|---|---|
| `401: Invalid or expired authentication token` | La entrada no declara ninguna cabecera | Añade `http_headers` o `env_http_headers` con `X-API-Key` |
| `401: Invalid API key` | La clave no vale: mal copiada, con espacios o revocada | Confirma que empieza por `sc_` y que solo hay una activa por cuenta |
| `401` solo con `env_http_headers` | La variable de entorno no está exportada en el proceso de Codex | Exporta `SOCIALCUTTER_API_KEY` en el mismo shell donde lanzas Codex |
| `401` con `Authorization: Bearer` | El valor del Bearer no empieza por `sc_`, así que se toma como token de sesión | Escribe `Authorization: Bearer sc_...` con tu clave, o usa `X-API-Key` |
| Las herramientas no aparecen | URL mal escrita o transporte equivocado | El endpoint termina en `/mcp` y es HTTP, no SSE; revisa la tabla con `codex mcp get socialcutter` |
| La entrada se ignora | Editado el fichero equivocado | Global es `~/.codex/config.toml`; de proyecto, `.codex/config.toml` |
| La herramienta tarda y se corta | Supera `tool_timeout_sec` | Súbelo en la tabla si tus lotes son grandes |

## Siguientes pasos

- Panorama de servidores MCP: [Conecta SocialCutter a tu LLM o editor con MCP](/guias/mcp/)
- Camino con código: [Procesa imágenes con la API de SocialCutter con curl](/guias/curl/)
- Objetivo de fondo: [Automatizar imágenes para redes sociales: los 4 caminos](/guias/automatizar-imagenes-redes-sociales/)
- Referencia de la API: https://docs.socialcutter.theboomer.dev