Conecta SocialCutter a Gemini CLI por MCP

Qué consigues conectando el MCP

Gemini CLI habla con servicios externos por MCP (Model Context Protocol). Con el servidor de SocialCutter registrado, no escribes peticiones HTTP ni montas scripts: describes lo que quieres en lenguaje natural y el modelo elige la herramienta y sus parametros. El servidor expone 28 herramientas sobre la misma API: procesar imagenes, consultar el historial, el monedero, cupones, claves y facturacion.

La frontera del producto no cambia por usar un agente. SocialCutter genera los archivos con la medida de cada plataforma y formato; no publica en redes sociales y no edita la imagen. El recorte es centrado, con los modos cover, contain, fill y stretch, y la salida se sirve en webp, jpg o png.

Dato	Valor
Endpoint	https://mcp.socialcutter.theboomer.dev/mcp
Transporte	HTTP con streaming (no SSE)
Autenticacion	cabecera X-API-Key: sc_... o Authorization: Bearer sc_...
Herramientas	28 (6 publicas sin credenciales)
Coste	1 uso por destino

La cabecera correcta

Antes de tocar el fichero, fija este punto: SocialCutter admite las dos cabeceras, X-API-Key: sc_... y Authorization: Bearer sc_..., y puedes usar la que documente tu cliente porque el resultado es el mismo. Lo que decide la via es el prefijo sc_: un Bearer cuyo valor no empieza por sc_ se interpreta como token de sesion y las herramientas privadas responden 401: Invalid or expired authentication token.

"headers": { "X-API-Key": "sc_tu_clave" }
// tambien vale: "headers": { "Authorization": "Bearer sc_tu_clave" }

Ninguna herramienta acepta la clave como argumento. La autenticacion viaja siempre en la cabecera, y por eso el cliente que configures tiene que permitir cabeceras personalizadas. Gemini CLI las admite.

La trampa del transporte: httpUrl, no url

Es la confusion mas habitual al registrar un servidor HTTP en Gemini CLI, y Google la tiene documentada: hay tres claves distintas para tres transportes distintos, y solo se pone una.

Clave	Transporte
httpUrl	HTTP con streaming, nuestro caso
url	SSE (transporte antiguo)
command	proceso local sobre stdio

Si escribes la direccion de un servidor HTTP en url, Gemini CLI intenta hablar SSE contra un endpoint que no lo sirve. El resultado tipico no es un error claro: el servidor aparece en la lista sin ninguna herramienta, como si estuviera vivo pero vacio. Cambia la clave a httpUrl, deja las otras dos fuera y reinicia.

Configuración en ~/.gemini/settings.json

El fichero de usuario esta en ~/.gemini/settings.json. Tambien se admite .gemini/settings.json dentro del proyecto para un ambito local. La entrada va bajo mcpServers:

{
  "mcpServers": {
    "socialcutter": {
      "httpUrl": "https://mcp.socialcutter.theboomer.dev/mcp",
      "headers": { "X-API-Key": "sc_tu_clave" },
      // si tu cliente solo ofrece Authorization: "headers": { "Authorization": "Bearer sc_tu_clave" },
      "timeout": 30000,
      "trust": true
    }
  }
}

Tres campos que conviene ajustar:

• timeout. Va en milisegundos. El valor por defecto es 600000 (diez minutos), pensado para procesos locales que arrancan despacio. Para un servidor remoto que responde al momento es un margen enorme: 30000 deja treinta segundos por llamada, suficiente para un lote y sin dejar la sesion colgada si la red falla.
• trust. Con trust: true las herramientas del servidor se ejecutan sin pedir confirmacion una por una. En un servidor de confianza como este evita una ristra de avisos por cada imagen; dejas de tener que aprobar process_image, get_credits y demas cada vez.
• Allowlist y denylist. Las claves mcp.allowed y mcp.excluded limitan en conjunto que servidores puede usar Gemini CLI. Son la via practica para dejar solo socialcutter en una maquina compartida, o para bloquearlo del todo en un entorno donde no quieres herramientas externas.

Alta desde la línea de comandos

Si prefieres no editar el JSON a mano, Gemini CLI trae su propio comando:

gemini mcp add --transport http socialcutter \
  https://mcp.socialcutter.theboomer.dev/mcp \
  --header "X-API-Key: sc_tu_clave"

El flag --transport http es el que marca el transporte correcto y evita de raiz la trampa de httpUrl. El comando escribe la entrada en la configuracion por ti. Y sirve como segunda via cuando algo no cuadra: si editar el fichero a mano no da resultado, dar de alta con gemini mcp add suele dejar el JSON en la forma que la herramienta espera.

Por qué no usamos el flujo OAuth interactivo

Gemini CLI puede autenticar servidores MCP remotos por OAuth con /mcp auth. Ese flujo abre un navegador y levanta un servidor local para recibir la respuesta en http://localhost:<puerto>/oauth/callback. En un portatil con entorno grafico funciona; en un servidor sin escritorio, en un contenedor o en una tuberia de integracion no hay donde abrir el navegador ni forma de completar el retorno, y el flujo se queda esperando.

Nuestro servidor no lo necesita. La autenticacion es una cabecera estatica que se escribe una vez en el fichero de configuracion. Eso hace la conexion reproducible, versionable en una plantilla y valida para un entorno automatizado, sin sesion interactiva ni navegador.

Verificar que está conectado

Reinicia Gemini CLI despues de tocar el fichero. Para comprobar la conexion sin gastar usos, pide una de las herramientas publicas:

Lo que pides	Herramienta	Qué confirma
«Lista las plataformas y formatos»	list_platforms	Transporte y lectura de herramientas
«¿Está el servicio activo?»	get_health	Llegada al servidor
«¿Cuántos usos me quedan?»	get_credits y get_wallet	Cabecera X-API-Key valida

Las tres primeras filas responden sin credenciales: si list_platforms devuelve el catalogo, el transporte esta bien aunque la clave todavia no sea valida. La cuarta es la que confirma la cabecera. Si el catalogo llega pero los usos no, el problema es la clave, no el transporte.

Errores típicos

Síntoma	Causa	Solución
401: Invalid or expired authentication token	No llega ninguna cabecera, o un Authorization: Bearer cuyo valor no empieza por sc_ (se toma como token de sesion)	Manda tu clave sc_... en X-API-Key o en Authorization: Bearer sc_...
401: Invalid API key	La clave esta mal copiada, caducada o revocada	Crea una nueva en Perfil → API keys y sustituyela
El servidor aparece sin herramientas	El endpoint HTTP esta en url (SSE) en vez de en httpUrl	Mueve la direccion a httpUrl y quita url o command
El servidor no aparece en la lista	JSON mal formado, coma de mas o fichero en otra ruta	Valida el JSON y confirma ~/.gemini/settings.json
El servidor esta excluido aunque este en el fichero	mcp.allowed no lo incluye o mcp.excluded lo bloquea	Revisa ambas listas
La peticion se corta en un lote grande	timeout demasiado bajo para el lote	Sube el timeout en milisegundos
El servidor no responde en un servidor sin escritorio	Se ha intentado el flujo OAuth interactivo	Usa la cabecera X-API-Key estatica

Límites que conviene recordar

• 5 MB por imagen. Por encima de ese tamaño la API responde 413.
• 1 uso por destino (plataforma y formato). Comprueba el monedero con get_credits antes de un lote.
• 13 destinos entre 6 plataformas. El catalogo publico de list_platforms es la fuente, no una lista copiada en el prompt.
• Para lotes, process_batch en una sola llamada rinde mejor que muchas llamadas sueltas.

Siguientes pasos

• Hub de agentes: Usa SocialCutter desde tu LLM o editor con MCP
• Camino con código: Procesa imágenes con la API desde curl y desde Python
• Panorama: Automatizar imágenes para redes sociales: los 4 caminos
• Referencia de la API: https://docs.socialcutter.theboomer.dev