# SocialCutter como servidor MCP en OpenCode
> Configura SocialCutter en OpenCode con opencode.json: la clave mcp, oauth en false, la sustitución {env:VAR} para el secreto y el alta por la CLI con mcp add.
- URL: https://socialcutter.theboomer.dev/guias/opencode/
- Idioma: es
- Familia: ia
- Actualizado: 2026-09-24
- Palabras clave: OpenCode, MCP, opencode.json, X-API-Key, oauth, mcp.servers, SocialCutter
## 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](/guias/mcp/).

## 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`**:

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

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

```bash
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:

```bash
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](/guias/mcp/)
- Sin agente, con código: [la API desde la terminal con curl](/guias/curl/) y [desde Python](/guias/python/)
- El mapa de caminos: [Automatizar imágenes para redes sociales: los 4 caminos](/guias/automatizar-imagenes-redes-sociales/)