# Usa SocialCutter desde tu LLM o editor con MCP
> Conecta el servidor MCP de SocialCutter a Claude, Cursor, VS Code o Windsurf. 28 herramientas para procesar imagenes, ver historial, monedero y facturas.
- URL: https://socialcutter.theboomer.dev/guias/mcp/
- Idioma: es
- Familia: ia
- Actualizado: 2026-09-24
- Palabras clave: MCP, Model Context Protocol, SocialCutter, Claude Desktop, Cursor, VS Code, Windsurf, API key
## Qué es el servidor MCP de SocialCutter

MCP (Model Context Protocol) es un protocolo abierto que permite a un modelo de lenguaje llamar herramientas de un servicio externo. El servidor MCP de SocialCutter expone la API como **28 herramientas**: procesar imágenes, consultar el historial, el monedero, cupones, claves de API y facturas.

Con el servidor conectado no escribes peticiones HTTP: describes lo que quieres en lenguaje natural y el modelo elige la herramienta y los parámetros. La API sigue siendo la misma; el MCP es una capa de acceso sobre ella.

- Paquete npm: `@theboomerdev/socialcutter-mcp`, versión **1.1.0**.
- Herramientas: **28**.
- Velocidad medida: unos **0,2 s por imagen y formato**.
- Coste: **1 uso por destino** (combinación de plataforma y formato).

## Dos modos de conexión

### Modo remoto (recomendado)

El servidor ya está desplegado en:

```
https://mcp.socialcutter.theboomer.dev/mcp
```

No instalas ni actualizas nada. La clave viaja en cada petición desde tu cliente: **no hay ninguna clave global guardada en el servidor**. El transporte es HTTP con streaming.

### Modo local (stdio)

Si tu cliente no admite servidores remotos, ejecuta el paquete por `npx`:

```bash
npx @theboomerdev/socialcutter-mcp
```

El proceso lee dos variables de entorno al arrancar:

| Variable | Valor |
|---|---|
| `SOCIALCUTTER_API_URL` | `https://api.socialcutter.theboomer.dev` |
| `SOCIALCUTTER_API_KEY` | tu clave `sc_...` |

En este modo el cliente lanza el proceso y este habla con la API usando tu clave.

## Crear la API key y enviarla

1. Entra en el dashboard: https://dash.socialcutter.theboomer.dev
2. Abre **Perfil → API keys**.
3. Crea una clave. El secreto empieza por `sc_` y **se muestra una sola vez**.
4. Guárdala en un gestor de secretos.

En cada petición la clave se envía en una cabecera:

- `X-API-Key: sc_...` (preferida)
- `Authorization: Bearer sc_...` (alternativa)

SocialCutter admite las dos cabeceras. 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.

Solo puede haber **una clave activa por cuenta**. Si intentas crear otra, la API responde con el error 400: revoca la anterior primero.

## Ejemplos de configuración

Aviso: las rutas de los ficheros, los nombres de las claves JSON y el soporte de servidores remotos cambian entre versiones de cada cliente. Confirma el formato en la documentación del cliente que uses. Los ejemplos siguientes son la forma habitual.

### Modo local con npx (clientes stdio)

En el fichero de configuración del cliente:

```json
{
  "mcpServers": {
    "socialcutter": {
      "command": "npx",
      "args": ["-y", "@theboomerdev/socialcutter-mcp"],
      "env": {
        "SOCIALCUTTER_API_URL": "https://api.socialcutter.theboomer.dev",
        "SOCIALCUTTER_API_KEY": "sc_tu_clave"
      }
    }
  }
}
```

### Modo remoto (clientes con soporte HTTP)

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

Rutas habituales del fichero de configuración:

| Cliente | Ruta habitual |
|---|---|
| Claude Desktop | `claude_desktop_config.json` |
| Cursor | `.cursor/mcp.json` (proyecto) o `~/.cursor/mcp.json` |
| VS Code | `.vscode/mcp.json` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |

## Ejemplos de uso en lenguaje natural

| Lo que pides | Herramienta que interviene | Qué devuelve |
|---|---|---|
| «Procesa esta imagen para Instagram post y TikTok cover» | `process_image` (por URL) o `process_upload_file` (fichero) | Un `image_id` y una URL por destino |
| «¿Cuántos usos me quedan?» | `get_credits` y `get_wallet` | Usos del día, bolsa extra y saldo comprado |
| «Lista el historial de las últimas 10» | `get_history` | Las 10 últimas imágenes con su origen |

## Herramientas más útiles

| Herramienta | Para qué sirve | Endpoint |
|---|---|---|
| `process_image` | Procesa una imagen por URL | `POST /api/v1/images/process` |
| `process_upload_file` | Procesa un fichero local (multipart) | `POST /api/v1/images/process/upload` |
| `process_batch` | Procesa varias imágenes en una llamada | `POST /api/v1/images/batch` |
| `get_image` | Recupera un trabajo anterior | `GET /api/v1/images/{image_id}` |
| `list_platforms` | Plataformas y formatos con medidas | `GET /api/v1/platforms` |
| `list_formats` | Formatos de salida admitidos | `GET /api/v1/formats` |
| `list_fit_modes` | Modos de ajuste disponibles | `GET /api/v1/fit-modes` |
| `get_history` | Historial de imágenes procesadas | `GET /api/v1/history` |
| `get_credits` / `get_wallet` | Usos y monedero | `GET /api/v1/credits`, `GET /api/v1/wallet` |
| `get_health` | Estado del servicio | `GET /api/v1/health` |
| `auth_me` | Identidad de la cuenta autenticada | `GET /api/v1/auth/me` |

Las demás herramientas cubren cupones, claves de API y facturación.

## Buenas prácticas

- **No pegues la clave en el chat.** El modelo no necesita verla: va en la configuración del cliente o en la variable de entorno.
- **Vigila el monedero** antes de lotes grandes con `get_credits` y `get_wallet`.
- **Recuerda la unidad de coste:** 1 uso por destino (plataforma y formato). Dos destinos en una petición son 2 usos.
- **Límite de subida: 5 MB** por fichero.
- Usa `process_batch` para lotes en lugar de muchas llamadas sueltas.

## Problemas comunes

| Síntoma | Causa | Solución |
|---|---|---|
| Error **401** | Clave ausente, mal formada o revocada | Comprueba que empieza por `sc_` y que la cabecera es `X-API-Key` o `Authorization: Bearer sc_...` (un `Bearer` sin `sc_` se toma como token de sesión) |
| Error **429** | Cuota del monedero agotada | Consulta `get_credits` y compra un pack o sube de plan |
| Error **413** | El fichero supera 5 MB | Reduce la imagen antes de subirla |
| El cliente no ve las herramientas | Configuración no leída o ruta equivocada | Reinicia el cliente y confirma el formato en su documentación |

## Guías por cliente

El servidor es el mismo para todos: cambia dónde se declara. Estas son las guías con la ruta exacta
del fichero de configuración, el fragmento listo para copiar y las trampas de cada cliente:

- [Claude Code](/guias/claude-code/): el fichero `.mcp.json` y el alta por CLI
- [Codex CLI](/guias/codex-cli/): la tabla en `~/.codex/config.toml`
- [Gemini CLI](/guias/gemini-cli/): `httpUrl` en `settings.json` (no `url`, que es SSE)
- [Cursor](/guias/cursor/): `.cursor/mcp.json`, compartido con su CLI
- [Windsurf](/guias/windsurf/): `mcp_config.json` de Cascade
- [Cline](/guias/cline/): `streamableHttp` obligatorio, o asume SSE
- [Goose](/guias/goose/): la extensión `streamable_http` en `config.yaml`
- [OpenCode](/guias/opencode/): `opencode.json` con `oauth: false`
- [Zed](/guias/zed/): la clave `context_servers`
- [Aider](/guias/aider/): no tiene MCP; usa la API REST desde sus comandos

## Siguientes pasos

- Guía de terminal: [Procesa imágenes con la API desde la terminal (curl)](/guias/curl/)
- Documentación de la API: https://docs.socialcutter.theboomer.dev
- Dashboard: https://dash.socialcutter.theboomer.dev