# Conecta SocialCutter a Windsurf (Cascade) por MCP
> Añade el servidor MCP de SocialCutter a Windsurf: las dos rutas de mcp_config.json, serverUrl, la cabecera X-API-Key y los errores típicos.
- URL: https://socialcutter.theboomer.dev/guias/windsurf/
- Idioma: es
- Familia: ia
- Actualizado: 2026-09-24
- Palabras clave: Windsurf, Cascade, MCP, mcp_config.json, serverUrl, X-API-Key, SocialCutter
## Qué aporta conectar SocialCutter a Windsurf

Windsurf es el editor con agente de Codeium, y Cascade es el agente que trabaja dentro de él. Cuando le enchufas un servidor MCP, Cascade deja de necesitar que le pegues peticiones HTTP: le describes en lenguaje natural lo que quieres y él elige la herramienta y rellena los parámetros.

El servidor MCP de SocialCutter expone la API como **28 herramientas**: procesar una imagen, consultar el historial, el monedero, los cupones, las claves de API y la facturación. Todo el detalle del protocolo, las herramientas y los modos de conexión está en la [guía del servidor MCP de SocialCutter](/guias/mcp/); esta página se centra en lo que es específico de Windsurf: dónde va el fichero, cómo se llama cada campo y qué hace Cascade de forma distinta.

Hay un detalle de autenticación que conviene fijar antes de nada. SocialCutter admite las dos cabeceras: **`X-API-Key: sc_...`** y **`Authorization: Bearer sc_...`**. 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. Windsurf soporta cabeceras personalizadas, así que te vale cualquiera de las dos: si copias el ejemplo genérico del fabricante con `Bearer` y le pones tu clave `sc_...`, conecta igual.

## Las dos rutas de mcp_config.json

Aquí hay un detalle que descoloca y que conviene decir tal cual: la **documentación del fabricante publica dos rutas distintas** para el mismo fichero.

- La página de Cascade muestra `~/.codeium/windsurf/mcp_config.json`.
- La página de plugins muestra `~/.codeium/mcp_config.json`, que parece la más reciente.

Las dos son plausibles y el nombre del fichero es idéntico (`mcp_config.json`); lo que cambia es el directorio. Si tu editor es una versión reciente seguramente lea la segunda, y si llevas tiempo con la instalación quizá siga leyendo la primera.

| Ruta | Dónde aparece | Cuándo suele ser la correcta |
|---|---|---|
| `~/.codeium/windsurf/mcp_config.json` | Página de Cascade | Instalaciones que ya tenían un fichero creado |
| `~/.codeium/mcp_config.json` | Página de plugins | Versiones recientes |

**Cómo comprobar cuál usa tu versión.** No hay un comando que lo diga, así que se comprueba a mano en tres pasos:

1. Abre el directorio `~/.codeium/` y mira si existe `mcp_config.json` en la raíz o dentro de `windsurf/`. Si ya hay uno, es el que usa tu instalación: edita ese y no crees otro.
2. Si no existe ninguno, créalo en la ruta que documente tu versión (en la duda, empieza por `~/.codeium/mcp_config.json`) y arranca Windsurf.
3. Comprueba en el panel de MCP del editor si `socialcutter` aparece y si sus herramientas cargan. Si no aparece, prueba el bloque idéntico en la otra ruta: como el contenido es el mismo, copiar y pegar el fichero completo de un sitio a otro no tiene coste.

En Windows el `~` es tu carpeta de usuario, así que `~/.codeium/mcp_config.json` es `C:\Users\tu_usuario\.codeium\mcp_config.json`.

## El bloque JSON del servidor

Para MCP remoto la documentación exige el campo `serverUrl` (o `url`, si tu versión admite el alias). Un servidor local usaría `command`; no es nuestro caso, porque el endpoint es remoto y habla HTTP.

```json
{
  "mcpServers": {
    "socialcutter": {
      "serverUrl": "https://mcp.socialcutter.theboomer.dev/mcp",
      "headers": { "X-API-Key": "sc_tu_clave" }
      // Autentica igual: "headers": { "Authorization": "Bearer sc_tu_clave" }
    }
  }
}
```

Tres cosas de este bloque conviene no tocar:

- **`serverUrl`** con el endpoint exacto, incluido el `/mcp` final.
- **`headers`** con `X-API-Key`. Ninguna herramienta acepta la clave como argumento: la autenticación va siempre por cabecera, y por eso el cliente tiene que soportar cabeceras personalizadas. Windsurf las soporta.
- **`mcpServers`** como clave raíz, con los nombres de servidor en minúsculas como prefieras; `socialcutter` es el que usamos en toda la documentación para que coincidan los ejemplos.

También puedes añadirlo desde la interfaz: **Settings → Tools → Windsurf Settings → Add Server**, o abriendo el fichero con **View Raw Config**. La interfaz escribe exactamente la misma estructura, así que si prefieres el editor visual no pierdes nada.

## Interpolación de variables en la cabecera

Escribir la clave en claro en un fichero de configuración no es lo ideal, sobre todo si el fichero acaba en un repositorio. Windsurf admite interpolación con dos sintaxis:

| Sintaxis | Qué resuelve |
|---|---|
| `${env:VARIABLE}` | El valor de una variable de entorno del proceso del editor |
| `${file:ruta}` | El contenido de un fichero de texto, por ejemplo un secreto montado |

La versión con variable de entorno evita el secreto en claro:

```json
{
  "mcpServers": {
    "socialcutter": {
      "serverUrl": "https://mcp.socialcutter.theboomer.dev/mcp",
      "headers": { "X-API-Key": "${env:SOCIALCUTTER_API_KEY}" }
    }
  }
}
```

Exporta `SOCIALCUTTER_API_KEY` en el entorno desde el que arrancas Windsurf y guarda la clave en tu gestor de secretos, no en el fichero. Ojo con la diferencia entre "lo que ves en tu shell" y "lo que hereda el editor": si lanzas Windsurf desde una terminal, hereda las variables de esa terminal; si lo abres desde el menú del sistema, puede que no.

## El límite de 100 herramientas activas

Cascade tiene un tope: **100 herramientas activas a la vez**. En la práctica significa que todos los servidores MCP configurados suman herramientas contra el mismo contador. Nuestro servidor publica 28, así que por sí solo no se acerca al límite, pero si tienes otros tres o cuatro servidores cargados de herramientas, es fácil pasarse y descubrir que algunas dejan de aparecer.

Si detectas que faltan herramientas, la primera comprobación es contar cuántas hay activas entre todos los servidores y desactivar las que no uses. Es más rápido que reinstalar cosas.

## Enterprise y el botón de refrescar

Dos detalles operativos que generan soporte cada semana:

- **En planes Enterprise**, MCP es una capacidad que hay que **activar en los ajustes**, y los administradores pueden bloquearlo con allowlists de servidores. Si eres usuario de una organización y el servidor no aparece por ningún lado, comprueba con tu administrador si MCP está habilitado antes de tocar el fichero.
- **Hay que pulsar refrescar.** Añadir el bloque y guardar el fichero no recarga la lista de herramientas. Hay que pulsar el botón de refresco del panel MCP —o reiniciar el editor— para que Cascade vea el servidor nuevo y sus 28 herramientas.

## Errores típicos

| Síntoma | Causa probable | Solución |
|---|---|---|
| `401: Invalid or expired authentication token` | No llega ninguna cabecera, o un `Bearer` sin el prefijo `sc_` (se toma como token de sesión) | Manda tu clave `sc_...` en `X-API-Key`, o en `Authorization: Bearer sc_...` |
| `401: Invalid API key` | La clave existe pero no vale: copiada mal, revocada o de otra cuenta | Vuelve a Perfil → API keys, crea una nueva y sustituye el valor |
| El servidor no aparece en la lista | Has editado la ruta que tu versión no lee | Prueba el mismo bloque en la otra ruta de `mcp_config.json` |
| Aparece el servidor pero sin herramientas | Guardaste y no refrescaste | Pulsa el botón de refrescar o reinicia Windsurf |
| Faltan herramientas y el servidor está bien | Has pasado el límite de 100 herramientas activas | Quita servidores o desactiva herramientas que no uses |
| En la organización no aparece nada | MCP está desactivado o bloqueado por allowlist | Pide a tu administrador que active MCP en los ajustes Enterprise |
| La clave no se resuelve desde `${env:...}` | La variable no existe en el entorno del editor | Arranca Windsurf desde la terminal donde exportaste la variable, o vuelve a la clave en claro |

## Siguientes pasos

- Panorama del protocolo: [Usa SocialCutter desde tu LLM o editor con MCP](/guias/mcp/)
- Camino con código: [Procesa imágenes con la API desde la terminal (curl)](/guias/curl/) y [desde Python](/guias/python/)
- Estrategia: [Automatizar imágenes para redes sociales: los 4 caminos](/guias/automatizar-imagenes-redes-sociales/)
- Referencia de la API: https://docs.socialcutter.theboomer.dev
- Dashboard: https://dash.socialcutter.theboomer.dev