Zed y SocialCutter: MCP con context servers

Zed no llama MCP a los MCP

Zed usa MCP internamente, pero no lo llama así en su configuración: los llama context servers. Es el detalle que rompe la mitad de las primeras configuraciones, porque el snippet que funciona en otras herramientas se copia tal cual y no hace nada.

Lo que esperas	Lo que Zed lee
mcpServers	Se ignora: no es una clave de Zed
context_servers	Clave raíz correcta para dar de alta un servidor
~/.config/zed/settings.json	Configuración global, para todos los proyectos
.zed/settings.json	Configuración del proyecto concreto

Si copias un bloque con mcpServers, Zed no da error: simplemente no aparece ningún servidor nuevo. Antes de tocar nada más, comprueba el nombre de la clave raíz.

Requisitos: Zed v0.214.5 o superior

El servidor MCP de SocialCutter es remoto y habla HTTP con streaming en https://mcp.socialcutter.theboomer.dev/mcp. No se lanza con npx, no hay proceso local y no hay nada que instalar en la máquina.

Zed admite servidores MCP remotos por HTTP de forma nativa desde la v0.214.5. En versiones anteriores solo sabe hablar con servidores locales por stdio, así que una entrada con url no conecta por mucho que el JSON sea correcto. Si el servidor no aparece o no muestra herramientas, lo primero es actualizar Zed y reabrirlo.

El transporte es HTTP, no SSE. Un endpoint SSE no es intercambiable: si apuntas a un transporte equivocado, el servidor puede registrarse sin herramientas.

Dos cabeceras de autenticación

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.

Hay cinco herramientas que responden sin clave: list_platforms, list_formats, list_fit_modes, get_health y get_pricing_plans. Sirven para comprobar que la conexión está viva antes de tener credenciales. Las privadas —process_image, process_batch, get_credits, get_wallet, get_history, auth_me y el resto hasta 28— exigen una clave válida. Sin cabecera devuelven 401: Invalid or expired authentication token; con una clave que no vale, 401: Invalid API key.

Crea la clave en el dashboard, en Perfil → API keys. Se muestra una sola vez y solo puede haber una activa por cuenta.

Configurar settings.json

Abre ~/.config/zed/settings.json (o .zed/settings.json si quieres que la configuración viaje con el repositorio) y añade:

{
  "context_servers": {
    "socialcutter": {
      "url": "https://mcp.socialcutter.theboomer.dev/mcp",
      "headers": {
        "X-API-Key": "sc_tu_clave"
        // misma autenticación: "Authorization": "Bearer sc_tu_clave"
      }
    }
  }
}

También puedes darlo de alta desde la interfaz: Settings → AI → MCP Servers → Add Server. La interfaz escribe la misma entrada en el mismo fichero, así que da igual el camino que uses.

Si no declaras ninguna cabecera, Zed abre su propio OAuth

Zed, cuando no encuentra una cabecera de autenticación configurada para un servidor, lanza su propio flujo OAuth contra él. Si dejas que Zed intente autorizar por OAuth, la petición acaba en 401 y lo único que ves es un error de autenticación en la interfaz.

Por eso el snippet de arriba declara la cabecera explícitamente: vale X-API-Key: sc_... o Authorization: Bearer sc_..., y con cualquiera de las dos Zed no abre el flujo OAuth.

Verificar la conexión

1. Guarda el fichero y reabre Zed para que relea la configuración.
2. Abre Settings → AI → MCP Servers y comprueba que socialcutter aparece en la lista.
3. Pide en el asistente algo que no necesita clave: «lista las plataformas y sus formatos». Si responde con las 6 plataformas y los 13 destinos, la conexión funciona incluso antes de copiar la clave.
4. Pide después «¿cuántos usos me quedan?», que ya usa get_credits y get_wallet y por tanto la cabecera. Si esa segunda respuesta falla con 401, el problema es la clave, no el transporte.

Qué puedes pedirle al modelo

Lo que pides	Herramienta que interviene	Qué devuelve
«Lista las plataformas y los formatos»	list_platforms y list_formats	El catálogo con medidas y relaciones de aspecto
«Procesa esta URL para Instagram post y TikTok cover»	process_image	Un image_id y una URL por destino
«Procesa estos cuatro ficheros»	process_upload_file o process_batch	Las salidas de cada imagen
«¿Cuántos usos me quedan?»	get_credits y get_wallet	Usos del día, bolsa extra y saldo comprado
«Enséñame las últimas diez imágenes»	get_history	El historial con el origen de cada trabajo

La unidad de coste es 1 uso por destino, entendiendo destino como cada combinación de plataforma y formato: una petición para Instagram post, TikTok cover y YouTube thumbnail son 3 usos. Los procesamientos fallidos se devuelven.

Recuerda también la frontera del producto: SocialCutter genera los ficheros y no publica. El recorte es centrado, con los modos cover, contain, fill y stretch, sin análisis de contenido. La salida es webp, jpg o png con calidad de 1 a 100 (85 por defecto) y el máximo por imagen es de 5 MB.

Errores típicos

Síntoma	Causa	Solución
401: Invalid or expired authentication token	La entrada no lleva cabecera de autenticación, o el valor del Bearer no empieza por sc_	Añade X-API-Key: sc_... o Authorization: Bearer sc_... en headers y reinicia Zed
401: Invalid API key	Clave mal copiada o revocada	Crea una nueva en Perfil → API keys y sustituye el valor
El servidor no aparece en Zed	Clave raíz equivocada (mcpServers)	Cambia el nombre a context_servers y guarda
Aparece el servidor pero sin herramientas	Zed anterior a la v0.214.5, o transporte equivocado	Actualiza Zed; confirma que la URL es la de HTTP, no una de SSE
Zed abre un flujo OAuth	No hay cabecera configurada para ese servidor	Declara X-API-Key o Authorization: Bearer sc_... en headers para que Zed no intente autorizar
413 al procesar un fichero	La imagen supera 5 MB	Reduce el fichero antes de subirlo
429 al procesar	Cuota del monedero agotada	Consulta get_credits y compra un pack o sube de plan

Siguientes pasos

• Panorama del protocolo: Usa SocialCutter desde tu LLM o editor con MCP
• Sin editor, desde la terminal: Procesa imágenes con la API desde la terminal (curl)
• Desde código: Procesa imágenes con la API de SocialCutter desde Python
• Si tu herramienta no tiene MCP: Aider no tiene MCP: usa la API de SocialCutter
• Los cuatro caminos de automatización: Automatizar imágenes para redes sociales
• Documentación de la API: https://docs.socialcutter.theboomer.dev
• Documentación de MCP en Zed: https://zed.dev/docs/ai/mcp