SocialCutter como extensión MCP en Goose

Qué es Goose y cómo encaja el MCP de SocialCutter

Goose es un agente de código abierto de Block que se ejecuta en el terminal o en su aplicación de escritorio y trabaja con extensiones: cada extensión añade un conjunto de herramientas que el modelo puede llamar. El servidor MCP de SocialCutter entra por esa puerta, así que basta una entrada en la configuración para pedir en lenguaje natural los formatos de una imagen en lugar de escribir peticiones HTTP.

Conviene fijar la frontera desde el principio: SocialCutter genera los ficheros, no publica. Recibe una imagen, la recorta de forma centrada a la medida exacta de cada plataforma y formato, y devuelve una URL por salida. No analiza el contenido de la imagen ni edita el original: ajusta la zona central según el modo elegido. Publicar o mover esos ficheros es del llamante. El coste es 1 uso por destino, es decir, por cada combinación de plataforma y formato.

Datos del servidor que vas a necesitar:

Dato	Valor
Endpoint	https://mcp.socialcutter.theboomer.dev/mcp
Transporte	HTTP con streaming (streamable HTTP)
Herramientas	28
Cabecera de autenticación	X-API-Key: sc_... o Authorization: Bearer sc_...
Herramientas públicas	list_platforms, list_formats, list_fit_modes, get_health, get_pricing_plans, get_credit_packs

Si es la primera vez que conectas el servidor, empieza por la guía del servidor MCP de SocialCutter, donde están las 28 herramientas y los dos modos de conexión.

El fichero: config.yaml bajo la clave extensions

Goose guarda toda la configuración en un único YAML y los servidores se declaran bajo la clave raíz extensions:

Sistema	Ruta del fichero
Linux y macOS	~/.config/goose/config.yaml
Windows	%APPDATA%\Block\goose\config\config.yaml

La entrada de SocialCutter queda así:

extensions:
  socialcutter:
    type: streamable_http
    name: socialcutter
    enabled: true
    uri: "https://mcp.socialcutter.theboomer.dev/mcp"
    headers:
      X-API-Key: "sc_tu_clave"
      # autentica igual: Authorization: "Bearer sc_tu_clave"
    env_keys: []
    envs: {}
    timeout: 300

sc_tu_clave es un marcador: ahí va tu clave real, la que creaste en el dashboard. Goose reenvía tal cual lo que pongas en headers, y SocialCutter admite las dos cabeceras (X-API-Key: sc_... y Authorization: Bearer sc_...), así que 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. Esa forma, con el valor escrito, sirve para una primera prueba en local. Más abajo está el modo limpio, sin secretos dentro del fichero.

Campo por campo

Campo	Para qué sirve
type	Transporte de la extensión. Aquí streamable_http, que es lo que habla nuestro endpoint
name	Nombre con el que la extensión aparece en la sesión
enabled	Si está activa. Para desactivarla sin borrarla, ponlo en false
uri	URL del servidor MCP remoto
headers	Cabeceras que Goose reenvía en cada petición; aquí viaja X-API-Key o Authorization: Bearer
env_keys	Nombres de las variables cuyo valor se guarda en el llavero del sistema
envs	Variables sin secreto, escritas directamente en el fichero
timeout	Segundos de espera antes de dar una llamada por perdida

SSE está retirado: migra a streamable_http

Si arrastras una entrada antigua con type: sse, no va a funcionar: SSE está retirado en Goose y el transporte que se usa hoy es streamable_http. La migración es cambiar el tipo y conservar la misma uri:

 extensions:
   socialcutter:
-    type: sse
+    type: streamable_http
     uri: "https://mcp.socialcutter.theboomer.dev/mcp"

Nuestro endpoint publica el transporte HTTP con streaming, así que una extensión configurada en SSE se queda sin herramientas aunque la URL sea la correcta. Este es el primer sitio donde mirar si Goose contesta que no encuentra ninguna herramienta de SocialCutter.

Alta sin editar el fichero a mano

Hay dos caminos además de editar el YAML. Para una prueba puntual:

goose session --with-streamable-http-extension "https://mcp.socialcutter.theboomer.dev/mcp"

Ese comando arranca una sesión con la extensión cargada solo para esa ejecución, sin tocar nada. Y para dejarla guardada de forma permanente:

goose configure

Dentro del asistente se elige Remote Extension (Streamable HTTP) y se pega la URL. Goose escribe la entrada por ti, así que es también la forma más segura de ver el formato exacto que espera tu versión.

Los secretos van al llavero, no al fichero

config.yaml es un fichero que acaba en un repositorio más veces de las que debería. La forma limpia en Goose es no escribir la clave dentro: se declara su nombre en env_keys y el valor vive en el llavero del sistema (Keychain en macOS, el gestor de secretos del escritorio en Linux, Credential Manager en Windows). env_keys es la lista de variables que la extensión tiene que leer de ahí:

    headers:
      X-API-Key: "sc_tu_clave"
      # o bien Authorization: "Bearer sc_tu_clave"
    env_keys:
      - SOCIALCUTTER_API_KEY

El valor de SOCIALCUTTER_API_KEY queda fuera del fichero, así que puedes versionar la configuración sin filtrar nada. El nombre exacto de la variable y el formato que espera tu versión los confirma el propio asistente al configurar la extensión remota: si al guardar no ves la entrada que esperabas, vuelve a goose configure antes de editar el YAML a mano.

Comprobar que la conexión funciona

Las herramientas públicas responden sin clave, así que sirven para verificar la instalación antes de crear credenciales:

• «Lista las plataformas y sus formatos» → list_platforms
• «¿Está el servicio en pie?» → get_health
• «¿Qué modos de ajuste hay y cuánto cuestan los planes?» → list_fit_modes, get_pricing_plans

Con la clave puesta, una pregunta de negocio confirma la autenticación: «¿cuántos usos me quedan?» pasa por get_credits y get_wallet. Si responde con tu saldo, la extensión está bien montada.

Lo que suele pedirse desde la sesión

Lo que pides	Herramienta	Qué devuelve
«Procesa esta imagen para Instagram post y TikTok cover»	process_image (URL) o process_upload_file (fichero)	Un image_id y una URL por destino
«Manda estas tres a todos los formatos de feed cuadrados»	process_batch	Un resultado por imagen del lote
«¿Cuántos usos me quedan?»	get_credits y get_wallet	Usos del día, bolsa extra y saldo comprado
«Enséñame las diez últimas»	get_history	Las diez imágenes más recientes con su origen
«¿Qué formatos tiene LinkedIn?»	list_platforms	Plataformas, formatos y medidas

Límites y coste

• 1 uso por destino (plataforma y formato). Recuerda que 13 destinos de una misma imagen son 13 usos.
• 5 MB por imagen, tanto en la variante por URL como en la subida de fichero.
• Salida en webp, jpg o png, con calidad de 1 a 100 y 85 por defecto.
• Modos de ajuste cover, contain, fill y stretch, todos con recorte centrado.
• 6 plataformas y 13 destinos en el catálogo público; no existe 4:5.

Errores típicos

Síntoma	Causa	Solución
401: Invalid or expired authentication token	La cabecera X-API-Key no llega al servidor	Revisa el bloque headers de la entrada y guarda el fichero antes de reiniciar Goose
401: Invalid API key	La clave está mal copiada, caducada o revocada	Vuelve a copiarla desde Perfil → API keys; solo hay una clave activa por cuenta
Goose no muestra ninguna herramienta de SocialCutter	Transporte equivocado: queda una entrada con type: sse	Cambia type a streamable_http y vuelve a arrancar la sesión
La extensión existe pero está desactivada	enabled en false, o el fichero editado no es el que Goose lee	Pon enabled: true y confirma la ruta según tu sistema
Sigue sin verla tras editar el YAML	Goose lee la configuración al arrancar	Cierra la sesión y ábrela de nuevo
La llamada se corta con un lote grande	El procesamiento dura más que timeout	Sube timeout (en segundos) o divide el lote en partes menores

Siguientes pasos

• Visión de conjunto: Usa SocialCutter desde tu LLM o editor con MCP
• El mismo flujo con código, sin agente: la API desde la terminal con curl y desde Python
• El mapa de caminos: Automatizar imágenes para redes sociales: los 4 caminos