# Conecta SocialCutter a Claude Code por MCP
> Añade el servidor MCP de SocialCutter a Claude Code con .mcp.json o la CLI, la cabecera X-API-Key, la aprobación de proyecto y la trampa del ámbito de usuario.
- URL: https://socialcutter.theboomer.dev/guias/claude-code/
- Idioma: es
- Familia: ia
- Actualizado: 2026-09-24
- Palabras clave: Claude Code, MCP, SocialCutter, X-API-Key, mcp.json, servidor MCP, API key
## Qué aporta el MCP de SocialCutter dentro de Claude Code

Claude Code es el agente de terminal de Anthropic: lee tu repositorio, ejecuta comandos y edita ficheros. Si le conectas el servidor MCP de SocialCutter gana **28 herramientas** con las que generar los formatos de tus imágenes sin salir de la sesión.

El servidor ya está desplegado y usa transporte HTTP con streaming:

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

Su identificador es `@theboomerdev/socialcutter-mcp` versión **1.1.0**. 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. Ninguna herramienta acepta la clave como argumento, así que el cliente tiene que saber enviar cabeceras personalizadas.

Antes de tener clave puedes comprobar la conexión con las herramientas públicas: `list_platforms`, `list_formats`, `list_fit_modes`, `get_health`, `get_pricing_plans` y `get_credit_packs` responden sin credenciales. Las demás —`process_image`, `process_batch`, `get_wallet`, `get_history` y el resto— exigen la clave.

## Dónde se declara el servidor en Claude Code

Claude Code lee la lista de servidores MCP de dos sitios:

| Ámbito | Fichero | Comportamiento |
|---|---|---|
| Proyecto | `.mcp.json` en la raíz del repositorio | Se puede versionar y compartir con el equipo |
| Usuario | `~/.claude.json` | Disponible en todos tus proyectos |

### Fichero de proyecto: .mcp.json

```json
{
  "mcpServers": {
    "socialcutter": {
      "type": "http",
      "url": "https://mcp.socialcutter.theboomer.dev/mcp",
      "headers": { "X-API-Key": "sc_tu_clave" }
      // Si tu cliente solo ofrece el campo Authorization: { "Authorization": "Bearer sc_tu_clave" }
    }
  }
}
```

La clave `type` no es decorativa. Una entrada con `url` y **sin `type`** se interpreta como servidor **stdio** y no conecta: Claude Code responde con un error pidiendo `"type": "http"`. Si copias un ejemplo sin ese campo, ese es el primer sitio donde mirar.

### Ámbito de usuario: ~/.claude.json

El mismo bloque `mcpServers` sirve en `~/.claude.json` para tener SocialCutter disponible en todos tus proyectos. Aun así, hay una salvedad importante con las cabeceras en este ámbito, que explico más abajo.

### Alta por CLI

Si prefieres no editar el JSON a mano, deja que el propio Claude Code escriba la entrada:

```bash
claude mcp add --transport http socialcutter https://mcp.socialcutter.theboomer.dev/mcp \
  --header "X-API-Key: sc_tu_clave"
# Mismo resultado con la otra cabecera: --header "Authorization: Bearer sc_tu_clave"
```

El comando registra el servidor con el transporte HTTP y la cabecera personalizada. Guarda la clave en un gestor de secretos y no la dejes en el historial del shell si la máquina se comparte.

## La aprobación de los servidores de proyecto

Los servidores declarados en `.mcp.json` pertenecen al proyecto y **piden aprobación interactiva la primera vez**. La sesión te muestra la lista y tú decides si confías en ellos; hasta que apruebes, `claude mcp list` los marca como pendientes y las herramientas no están disponibles.

Dos matices que conviene tener claros:

- En modo no interactivo (`claude -p`) y en el SDK los servidores de proyecto se cargan sin preguntar. Es cómodo para automatizaciones, pero significa que la aprobación no actúa como barrera cuando el agente lo lanza un script.
- Un fichero de proyecto versionado lleva la clave a un fichero compartido. Si el repositorio es público o se comparte fuera del equipo, usa el ámbito de usuario o registra el servidor por CLI en lugar de dejarla escrita.

## El issue de cabeceras personalizadas en ámbito de usuario

Hay un issue abierto en el repositorio de Claude Code (anthropics/claude-code#28293) sobre **cabeceras personalizadas que no se reenvían en el ámbito de usuario**. El síntoma es reconocible: el servidor aparece en la lista, las herramientas públicas pueden responder, pero las privadas devuelven `401` porque `X-API-Key` no llega al servidor.

El workaround es dar de alta el servidor con `claude mcp add --transport http` en lugar de editar `~/.claude.json` a mano, y comprobar el resultado con `claude mcp list`. Si aun así sigue fallando en ese ámbito, declara el servidor en el `.mcp.json` del proyecto y pasa por la aprobación interactiva mientras se resuelve.

## Verificar con claude mcp list

```bash
claude mcp list
```

El listado muestra cada servidor con su transporte y su estado. Lo que buscas es `socialcutter` conectado, no pendiente ni con error. Dentro de una sesión interactiva tienes el comando `/mcp` con el mismo detalle.

Para una prueba funcional, pide algo que dispare una herramienta pública:

> Lista las plataformas y sus formatos con list_platforms.

Si la respuesta trae el catálogo con sus medidas, el transporte y la conexión están bien. Después pide el monedero (`get_wallet`) para confirmar que la clave se está enviando de verdad y no solo que el proceso arranca.

## Tres usos en lenguaje natural

| Lo que escribes en la sesión | Herramienta | Qué devuelve |
|---|---|---|
| «Toma la maestra https://ejemplo.com/maestra.jpg y genera los 13 destinos» | `process_image` | Un `image_id` y una URL por destino |
| «Procesa en lote estas diez URLs» | `process_batch` | Un resultado por imagen con sus salidas |
| «¿Cuántos usos me quedan?» | `get_credits` y `get_wallet` | Usos del día, bolsa extra y saldo |

El catálogo público tiene **6 plataformas** y **13 destinos**, donde un destino es la combinación de plataforma y formato. Convertir una maestra a los 13 destinos son 13 usos, y Claude Code los pide en una sola llamada a `process_image` con el array `destinations` relleno: los argumentos obligatorios de esa herramienta son `source_url` y `destinations`.

Para lotes, `process_batch` recibe el argumento `images` y resuelve varias imágenes de una vez; sigue consumiendo 1 uso por destino. Antes de lanzar un lote grande, pide el monedero: `get_credits` da los usos del plan y `get_wallet` el detalle del saldo.

Recuerda la frontera del producto: SocialCutter **genera los archivos**, no publica en redes ni edita la imagen. El recorte es **centrado**, con modos `cover`, `contain`, `fill` y `stretch`, y sin análisis del contenido. La salida puede ser `webp`, `jpg` o `png` con calidad de 1 a 100 (85 por defecto), y cada imagen admite hasta 5 MB.

## Errores típicos

| Síntoma | Causa | Solución |
|---|---|---|
| `401: Invalid or expired authentication token` | El servidor no recibe ninguna cabecera | Revisa que la entrada tenga `headers` con `X-API-Key`; si estás en ámbito de usuario, repite el alta con `claude mcp add` |
| `401: Invalid API key` | La clave está mal copiada o revocada | Confirma que empieza por `sc_`, que no tiene espacios ni saltos de línea y que solo hay una activa por cuenta |
| Las herramientas no aparecen | La entrada tiene `url` sin `type`, así que se trata como stdio | Añade `"type": "http"` o registra el servidor con `--transport http` |
| El servidor sale como pendiente | Es un servidor de proyecto sin aprobar | Aprueba la aprobación interactiva y vuelve a listar |
| Funciona en la sesión pero falla en un script | El proceso no interactivo no pasó la aprobación de proyecto | Registra el servidor en el ámbito de usuario o ábrelo por CLI |
| Error de conexión o de transporte | Endpoint mal escrito o transporte distinto de HTTP | El endpoint termina en `/mcp` y no es SSE |

## Siguientes pasos

- Panorama de servidores MCP: [Conecta SocialCutter a tu LLM o editor con MCP](/guias/mcp/)
- Camino con código: [Procesa imágenes con la API de SocialCutter con curl](/guias/curl/)
- Objetivo de fondo: [Automatizar imágenes para redes sociales: los 4 caminos](/guias/automatizar-imagenes-redes-sociales/)
- Referencia de la API: https://docs.socialcutter.theboomer.dev