SocialCutter como servidor MCP en OpenCode

Qué añade OpenCode con un servidor MCP

OpenCode es un agente de código que se maneja desde el terminal y también desde su interfaz dentro de la aplicación. Con un servidor MCP conectado no escribes peticiones HTTP: describes lo que quieres y el agente decide qué herramienta llamar y con qué argumentos. El servidor MCP de SocialCutter expone la API como 28 herramientas, así que desde la sesión puedes pedir los formatos de una imagen, consultar el historial o mirar tus usos.

La frontera del producto no cambia por usar un agente: 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. Cada destino consumido es 1 uso.

Dato	Valor
Endpoint	https://mcp.socialcutter.theboomer.dev/mcp
Transporte	HTTP con streaming (tipo remote en el cliente)
Cabecera de autenticación	X-API-Key: sc_... o Authorization: Bearer sc_...
Herramientas	28, con seis públicas que no piden credenciales

El panorama completo del servidor está en la guía del servidor MCP de SocialCutter.

El fichero opencode.json

OpenCode lee la configuración de dos sitios: el global ~/.config/opencode/opencode.json y el del proyecto, opencode.json u opencode.jsonc en la raíz del repositorio. La entrada del servidor va bajo la clave mcp:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "socialcutter": {
      "type": "remote",
      "url": "https://mcp.socialcutter.theboomer.dev/mcp",
      "enabled": true,
      "oauth": false,
      "headers": { "X-API-Key": "sc_tu_clave" }
      // autentica igual: "headers": { "Authorization": "Bearer sc_tu_clave" }
    }
  }
}

Campo por campo

Campo	Para qué sirve
type	remote para un servidor por HTTP; local lanza un proceso en tu equipo
url	Endpoint del servidor MCP
enabled	Si el servidor se carga al arrancar la sesión
oauth	Si el cliente intenta el flujo OAuth. Aquí va en false
headers	Cabeceras extra; es donde viaja X-API-Key o Authorization: Bearer

Por qué oauth: false es la clave

La documentación de OpenCode lo dice con todas las letras para este caso: cuando el servidor se autentica con una clave por cabecera, se configura oauth en false. Sin ese campo, OpenCode ve un servidor remoto sin credenciales declaradas e intenta su propio flujo OAuth, que no es lo que ofrece SocialCutter. El resultado suele ser una conexión que no completa el registro de herramientas o un error de autorización que no tiene nada que ver con tu clave.

Con oauth: false y la cabecera puesta, cada petición lleva la clave (X-API-Key: sc_... o Authorization: Bearer sc_...) y el cliente no abre ningún flujo de autorización.

La clave fuera del fichero: {env:VAR}

opencode.json de proyecto se versiona con el repositorio, así que el secreto no debería ir dentro. OpenCode admite sustitución de variables de entorno en la configuración con la forma {env:NOMBRE}:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "socialcutter": {
      "type": "remote",
      "url": "https://mcp.socialcutter.theboomer.dev/mcp",
      "enabled": true,
      "oauth": false,
      "headers": { "X-API-Key": "{env:SOCIALCUTTER_API_KEY}" }
    }
  }
}

La variable se resuelve desde el entorno del proceso, así que exporta SOCIALCUTTER_API_KEY en tu shell o en el gestor de secretos que uses antes de arrancar OpenCode. La clave se crea en el dashboard, en Perfil → API keys, empieza por sc_ y solo se muestra una vez; únicamente puede haber una activa por cuenta.

Dos formatos según la versión

Aquí está la trampa que más tiempo hace perder: no todas las versiones de la documentación describen el mismo esquema. Las docs actuales colocan los servidores directamente bajo mcp, mientras que las V2 los agrupan bajo mcp.servers, y el interruptor cambia de nombre: unas páginas usan enabled y otras disabled.

Formato	Clave raíz	Interruptor
Docs actuales	mcp	enabled: true
Docs V2	mcp.servers	disabled: false

Si después de configurar el servidor no aparece ninguna herramienta, mira qué formato espera tu versión antes de dar por hecho que la conexión está rota. Cambiar de un esquema al otro es cuestión de mover la entrada un nivel y cambiar el interruptor; el resto de los campos (type, url, oauth, headers) se mantienen.

Alta con la CLI

No hace falta editar el JSON a mano. La CLI trae su propio comando de alta:

opencode mcp add socialcutter --url https://mcp.socialcutter.theboomer.dev/mcp

Con --global la entrada se guarda en la configuración de usuario y vale para todos los proyectos; sin el flag, queda en el ámbito del proyecto actual. Para revisar lo que hay dado de alta:

opencode mcp list

Y dentro de la aplicación, el comando /mcps muestra los servidores conectados y sus herramientas.

Comprobar que funciona

Empieza por las herramientas públicas, que responden sin clave. Pedir el catálogo o el estado del servicio confirma que el transporte y la URL son correctos:

• «Lista las plataformas con sus formatos y medidas» → list_platforms
• «¿Está el servicio disponible?» → get_health
• «¿Qué modos de ajuste hay?» → list_fit_modes

Cuando la clave esté en su sitio, la comprobación de autenticación es una pregunta de negocio: «¿cuántos usos me quedan?» pasa por get_credits y get_wallet.

Límites y coste

• 1 uso por destino (plataforma y formato); los destinos repetidos no se cobran dos veces.
• 5 MB por imagen.
• Salida en webp, jpg o png, calidad de 1 a 100 (85 por defecto).
• Modos de ajuste cover, contain, fill y stretch, siempre con recorte centrado.
• 6 plataformas y 13 destinos; no existe 4:5.

Errores típicos

Síntoma	Causa	Solución
401: Invalid or expired authentication token	La cabecera X-API-Key no se está enviando	Revisa el bloque headers y que la variable de {env:...} esté exportada en el entorno que arranca OpenCode
401: Invalid API key	La clave está mal copiada, caducada o revocada	Vuelve a copiarla desde Perfil → API keys
El servidor aparece pero sin herramientas	El esquema no es el que espera tu versión	Prueba mcp.servers y cambia enabled por disabled según corresponda
OpenCode intenta autorizar en vez de usar la cabecera	Falta oauth: false en la entrada	Añádelo y reinicia la sesión
No responde nada tras editar el JSON	Configuración leída al arrancar, o JSON inválido	Valida el fichero y vuelve a arrancar; con opencode mcp list compruebas lo que ha cargado
Transporte equivocado	Se ha configurado como servidor local	El nuestro es remoto: type en remote con la url del endpoint

Siguientes pasos

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