Conecta SocialCutter a Cursor y a su CLI agent

Dos rutas de fichero y una sola configuración

Cursor lee los servidores MCP de dos sitios segun el alcance que quieras:

Ambito	Fichero	Se versiona
Proyecto	.cursor/mcp.json en la raiz del repositorio	Si, es lo habitual
Global	~/.cursor/mcp.json	No, es tuyo

Lo importante es que el CLI agent lee la misma configuracion que el editor. No hay un fichero aparte para la terminal: lo que registres en .cursor/mcp.json lo ve el agente cuando lo lanzas dentro del proyecto, y lo que pongas en ~/.cursor/mcp.json lo ve en cualquier directorio. Si algo funciona en el editor y no en el CLI, el problema no es un fichero distinto: es el ambito de aprobacion, y lo vemos mas abajo.

La entrada del servidor

Para un servidor remoto, la entrada usa url y una cabecera de autenticacion, X-API-Key o Authorization: Bearer:

{
  "mcpServers": {
    "socialcutter": {
      "url": "https://mcp.socialcutter.theboomer.dev/mcp",
      "headers": { "X-API-Key": "sc_tu_clave" }
      // autentica igual: "headers": { "Authorization": "Bearer sc_tu_clave" }
    }
  }
}

Fijate en la cabecera: SocialCutter admite las dos, X-API-Key: sc_... y Authorization: Bearer sc_..., y el resultado es el mismo; usa la que documente tu cliente. Lo que decide la via es el prefijo sc_: si el valor de un Bearer no empieza por sc_ se interpreta como token de sesion y las herramientas privadas responden 401: Invalid or expired authentication token; con una clave equivocada, 401: Invalid API key. La clave empieza por sc_ y se crea en el dashboard, en Perfil → API keys; se muestra una sola vez y solo hay una activa por cuenta.

Ninguna herramienta acepta la clave como argumento, asi que el cliente tiene que soportar cabeceras personalizadas. Cursor lo hace.

Variables: ${env:...} y ${file:...}

Dejar el secreto escrito en un fichero que se versiona es mala idea. Cursor interpola variables en la configuracion, tanto en url como en headers:

{
  "mcpServers": {
    "socialcutter": {
      "url": "${env:SOCIALCUTTER_MCP_URL}",
      "headers": { "X-API-Key": "${env:SOCIALCUTTER_API_KEY}" }
    }
  }
}

export SOCIALCUTTER_MCP_URL="https://mcp.socialcutter.theboomer.dev/mcp"
export SOCIALCUTTER_API_KEY="sc_tu_clave"

Dos formas de resolver el valor:

• ${env:NOMBRE} toma la variable del entorno del proceso de Cursor. Es la via recomendada: la clave vive en tu shell o en tu gestor de secretos y el JSON solo lleva el nombre.
• ${file:ruta} lee el valor de un fichero. Util cuando el secreto lo deposita otra herramienta, pero ojo con los permisos: lo que haya en ese fichero se envia tal cual.

La interpolacion se aplica igual en la URL y en las cabeceras. Resolver la cabecera desde el entorno es lo que permite versionar .cursor/mcp.json sin filtrar nada.

envFile no vale para servidores remotos

envFile existe en la configuracion de Cursor, pero pertenece a los servidores locales: son los unicos que se lanzan como proceso y a los que se les puede entregar un fichero de variables al arrancar. Nuestro servidor es remoto; no hay proceso local al que pasarle nada, asi que envFile se ignora.

Si vienes de una configuracion de proceso local, el cambio es este: en un servidor remoto las variables se resuelven en la propia configuracion, con ${env:...} en url y headers, no con un fichero aparte. Si escribes envFile junto a url, no da error, simplemente no hace nada y la cabecera se queda sin valor, que se manifiesta como un 401.

Aprobación: global contra proyecto

Aquí está la diferencia que mas problemas da en automatizacion:

• Servidores globales (~/.cursor/mcp.json) no piden aprobacion. Son tuyos y de tu maquina.
• Servidores de proyecto (.cursor/mcp.json) necesitan aprobacion por espacio de trabajo. El repositorio lo puede clonar cualquiera; Cursor no se fia de las herramientas que trae hasta que las apruebas en ese espacio.
• Ademas, Cursor pide confirmacion antes de usar una herramienta MCP por defecto, con independencia del ambito.

En el editor eso son un par de clics. En una tuberia de integracion no hay clics. Si el agente se queda esperando o dice que no tiene herramientas, casi siempre es esto: el repo trae el .cursor/mcp.json, pero la aprobacion de ese espacio de trabajo no se ha dado. La solucion es registrar el servidor en el ambito global de la maquina, o bien lanzar el agente aprobando los servidores de forma explicita:

agent --approve-mcps "procesa esta imagen para Instagram post y TikTok cover"

Para comprobar que la configuracion se lee y las herramientas llegan:

agent mcp list
agent mcp list-tools socialcutter

agent mcp list confirma que el servidor esta registrado y si esta aprobado. agent mcp list-tools socialcutter muestra las herramientas que expone: si el servidor aparece pero la lista de herramientas sale vacia, el problema esta en la conexion o en la cabecera, no en la aprobacion.

Verificar sin gastar usos

Las herramientas publicas responden sin credenciales, asi que sirven para validar la conexion y separar un fallo de transporte de un fallo de clave:

Lo que pides	Herramienta	Qué confirma
«Lista las plataformas y formatos»	list_platforms	Conexion y lectura de herramientas
«¿Está el servicio activo?»	get_health	Llegada al servidor
«¿Cuántos usos me quedan?»	get_credits y get_wallet	Cabecera X-API-Key valida

Si list_platforms devuelve el catalogo, la conexion esta bien y el 401 viene de la cabecera. Si no devuelve nada, el problema es anterior: la URL, el ambito o la aprobacion.

Errores típicos

Síntoma	Causa	Solución
401: Invalid or expired authentication token	Cabecera ausente, o un Authorization: Bearer cuyo valor no empieza por sc_ (se toma como token de sesion)	Manda tu clave sc_... en X-API-Key o en Authorization: Bearer sc_...
401: Invalid API key	La clave esta mal, caducada o revocada	Crea una nueva en Perfil → API keys
Las herramientas no aparecen y el servidor si	Fallo de conexion al endpoint, no de aprobacion	Comprueba la URL y la cabecera con agent mcp list-tools socialcutter
El servidor de proyecto no se activa	Falta la aprobacion del espacio de trabajo	Aprueba en el editor o registra el servidor en ~/.cursor/mcp.json
El agente espera a que apruebes cada herramienta	Aprobacion por herramienta activa	Usa agent --approve-mcps en el entorno sin interfaz
envFile no tiene efecto	Se ha puesto en un servidor remoto	Pasa los valores con ${env:...} en url y headers
El JSON no se lee	Coma de mas o fichero en una ruta que Cursor no mira	Valida el JSON y confirma .cursor/mcp.json o ~/.cursor/mcp.json
El servidor responde pero no conoce el destino	Plataforma o formato inventados en el prompt	Consulta list_platforms para los 13 destinos reales

Límites y coste

• 28 herramientas en total; 6 responden sin credenciales.
• 5 MB por imagen. Por encima de ese tamaño la API responde 413.
• 1 uso por destino (plataforma y formato). Antes de un lote grande, consulta get_credits y get_wallet.
• 13 destinos entre 6 plataformas, con recorte centrado y salida en webp, jpg o png.
• El servidor genera los archivos: no publica en redes sociales ni edita la imagen. Subir o publicar es del llamante.

Siguientes pasos

• Hub de agentes: Usa SocialCutter desde tu LLM o editor con MCP
• Camino con código: Procesa imágenes con la API desde curl y desde Python
• Panorama: Automatizar imágenes para redes sociales: los 4 caminos
• Referencia de la API: https://docs.socialcutter.theboomer.dev