Conecta SocialCutter a Windsurf (Cascade) por MCP

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; 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.

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

{
  "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
• Camino con código: Procesa imágenes con la API desde la terminal (curl) y desde Python
• Estrategia: Automatizar imágenes para redes sociales: los 4 caminos
• Referencia de la API: https://docs.socialcutter.theboomer.dev
• Dashboard: https://dash.socialcutter.theboomer.dev