Conecta SocialCutter a Codex CLI por MCP

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:

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

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

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:

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

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
• Camino con código: Procesa imágenes con la API de SocialCutter con curl
• Objetivo de fondo: Automatizar imágenes para redes sociales: los 4 caminos
• Referencia de la API: https://docs.socialcutter.theboomer.dev