Conecta SocialCutter a Claude Code por MCP

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

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

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

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
• Camino con código: Procesa imágenes con la API de SocialCutter con curl
• Objetivo de fondo: Automatizar imágenes para redes sociales: los 4 caminos
• Referencia de la API: https://docs.socialcutter.theboomer.dev