# Conecta SocialCutter a Cursor y a su CLI agent
> Configura el servidor MCP de SocialCutter en .cursor/mcp.json con ${env:...}, entiende la aprobacion por proyecto y verifica con agent mcp list.
- URL: https://socialcutter.theboomer.dev/guias/cursor/
- Idioma: es
- Familia: ia
- Actualizado: 2026-09-24
- Palabras clave: Cursor, mcp.json, MCP, agent CLI, SocialCutter, X-API-Key, variables de entorno
## 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`:

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

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

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

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

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

```bash
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](/guias/mcp/)
- Camino con código: [Procesa imágenes con la API desde curl](/guias/curl/) y [desde Python](/guias/python/)
- Panorama: [Automatizar imágenes para redes sociales: los 4 caminos](/guias/automatizar-imagenes-redes-sociales/)
- Referencia de la API: https://docs.socialcutter.theboomer.dev