# Conecta SocialCutter a Gemini CLI por MCP
> Registra el servidor MCP de SocialCutter en Gemini CLI con httpUrl, timeout y trust. Alta por CLI, verificacion sin gastar usos y errores tipicos.
- URL: https://socialcutter.theboomer.dev/guias/gemini-cli/
- Idioma: es
- Familia: ia
- Actualizado: 2026-09-24
- Palabras clave: Gemini CLI, MCP, SocialCutter, httpUrl, settings.json, X-API-Key, API key
## 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`.

```json
"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`:

```json
{
  "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:

```bash
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](/guias/mcp/)
- Camino con código: [Procesa imágenes con la API desde curl](/guias/curl/) y [desde Python](/guias/python/)
- Panorama: [Automatizar imágenes para redes sociales: los 4 caminos](/guias/automatizar-imagenes-redes-sociales/)
- Referencia de la API: https://docs.socialcutter.theboomer.dev