suprsonic-mcp

suprsonic-mcp

Servidor MCP para Suprsonic. Ofrece a cualquier agente de IA decenas de capacidades mediante una sola conexión.

Inicio rápido

Conéctate al servidor alojado, sin instalar nada:

• URL: https://suprsonic.ai/v1/mcp (HTTP transmisible)
• Encabezado: Authorization: Bearer omk_your_key (o x-api-key: omk_your_key, para un cliente o una pasarela que reserve Authorization para su propio inicio de sesión)

O ejecuta el servidor en tu propia máquina:

SUPRSONIC_API_KEY=omk_your_key npx -y suprsonic-mcp

Obtén tu clave de API en suprsonic.ai/app/api. Ambas opciones ofrecen las mismas herramientas a los mismos precios. No se necesita una clave para consultar las herramientas; una llamada sin una clave válida responde con el error propio de la API, que indica dónde obtener una.

El paquete es suprsonic-mcp. En versiones anteriores de este README se mencionaba @suprsonic/mcp: ese ámbito de npm pertenece a una empresa no relacionada, así que no lo instales nunca.

Servidor alojado

Claude Code

claude mcp add --transport http suprsonic https://suprsonic.ai/v1/mcp --header "Authorization: Bearer omk_your_key"

Cursor

Añádelo a ~/.cursor/mcp.json (o a .cursor/mcp.json en un proyecto):

{
  "mcpServers": {
    "suprsonic": {
      "url": "https://suprsonic.ai/v1/mcp",
      "headers": {
        "Authorization": "Bearer omk_your_key"
      }
    }
  }
}

VS Code

Añádelo a .vscode/mcp.json (VS Code te pedirá la clave una vez y la guardará como secreto):

{
  "inputs": [
    { "type": "promptString", "id": "suprsonic-key", "description": "Suprsonic API key (omk_...)", "password": true }
  ],
  "servers": {
    "suprsonic": {
      "type": "http",
      "url": "https://suprsonic.ai/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${input:suprsonic-key}"
      }
    }
  }
}

Claude API (conector MCP)

Envía el encabezado beta anthropic-beta: mcp-client-2025-11-20 y añádelo a tu solicitud Messages:

{
  "mcp_servers": [
    { "type": "url", "url": "https://suprsonic.ai/v1/mcp", "name": "suprsonic", "authorization_token": "omk_your_key" }
  ],
  "tools": [
    { "type": "mcp_toolset", "mcp_server_name": "suprsonic" }
  ]
}

API de OpenAI Responses

Añádelo a tools de la solicitud:

{
  "type": "mcp",
  "server_label": "suprsonic",
  "server_url": "https://suprsonic.ai/v1/mcp",
  "authorization": "omk_your_key",
  "require_approval": "never"
}

Smithery

Suprsonic está disponible en Smithery como suprsonic. Añádelo a tu caja de herramientas de Smithery y pega tu clave cuando Smithery te la solicite; Smithery se la pasa al servidor alojado como x-api-key.

Servidor local (npx)

Claude Desktop

Añádelo a ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "suprsonic": {
      "command": "npx",
      "args": ["-y", "suprsonic-mcp"],
      "env": {
        "SUPRSONIC_API_KEY": "omk_your_key"
      }
    }
  }
}

La misma entrada funciona en mcp.json de Cursor.

Tu propio endpoint HTTP

Para servir el transporte HTTP desde tu propia máquina en lugar de usar el servidor alojado:

SUPRSONIC_API_KEY=omk_your_key npx -y suprsonic-mcp --http --port 3100

Luego, conéctate a http://localhost:3100/mcp.

Herramientas disponibles

Una llamada solo cuesta créditos si se completa correctamente. Cuando se muestra un intervalo, el modo que elijas determina el precio.

Herramienta	Qué hace	Créditos
search	Busca en la web con SERP, síntesis de IA o ambas	1-3
scrape	Extrae contenido de cualquier URL como Markdown o HTML	1-5
profiles	Encuentra y enriquece perfiles profesionales	3
emails	Encuentra direcciones de correo electrónico profesionales	2
images	Genera imágenes a partir de indicaciones de texto	3
tts	Convierte texto en audio de voz	2
stt	Transcribe audio a texto con marcas de tiempo	2
sound-generate	Genera efectos de sonido y pistas musicales cortas a partir de indicaciones de texto (NO es voz: usa tts para voz hablada)	4
sms	Envía mensajes SMS o de WhatsApp. El canal predeterminado es SMS (entrega fiable). WhatsApp requiere que el destinatario haya dado su consentimiento: debe haber enviado un mensaje a tu número de empresa en las últimas 24 horas.	1
documents	Extrae datos estructurados de URL o contenido	3
companies	Enriquece datos de empresas por dominio	3
email-verify	Comprueba si una dirección de correo electrónico admite entregas, acepta todos los mensajes o es desechable	1
transcribe	Transcribe audio con diarización de hablantes y marcas de tiempo	3
invoice-parse	Extrae datos estructurados de facturas y recibos	3
subtitle	Genera subtítulos SRT/VTT a partir de audio o vídeo	2
file-convert	Convierte documentos, páginas web, hojas de cálculo e imágenes entre formatos	2
bg-remove	Elimina el fondo de cualquier imagen. Devuelve un PNG transparente.	2
screenshot	Captura una imagen renderizada de cualquier página web	1
code-execute	Ejecuta código en un entorno aislado seguro con entornos preconfigurados	2
site-intel	Obtiene información completa de un dominio: WHOIS, DNS, SSL, pila tecnológica, seguridad del correo electrónico y alojamiento	1-2
research	Investigación profunda en varios pasos: busca, extrae contenido, enriquece entidades y sintetiza un informe con citas	10-35
video-info	Extrae metadatos del vídeo, formatos disponibles y miniatura de cualquier URL	1
video-download	Descarga vídeos de cualquier URL y devuelve un enlace de descarga temporal	2-3
domains	Encuentra nombres de dominio y extensiones adecuadas para una empresa	1-5

Formato de respuesta

Todas las herramientas devuelven un objeto de respuesta unificado:

{
  "success": true,
  "data": {
    "results": [
      { "title": "OpenAI raises $6.6B", "url": "https://...", "snippet": "..." }
    ]
  },
  "error": null,
  "metadata": {
    "provider_used": "serperdev",
    "providers_tried": ["serperdev"],
    "response_time_ms": 1200,
    "request_id": "req_abc123"
  },
  "credits_used": 1
}

Si se produce un error, success es false y error contiene los detalles (consulta más abajo).

Gestión de errores

Todos los errores tienen el mismo formato de objeto. Una capacidad que falla lo devuelve como error en la respuesta anterior, con success establecido en false y sin cobrar créditos. Una llamada rechazada (por una clave no válida, créditos insuficientes o un límite de solicitudes) responde con HTTP 401, 402 o 429 y devuelve el objeto bajo detail:

{
  "detail": {
    "type": "https://api.o-mega.ai/errors/insufficient-credits",
    "title": "Insufficient Suprsonic API credits",
    "status": 402,
    "detail": "This call needs 2 credits and your Suprsonic account has 0 left of its 200 free credits a month, which refill on November 12. This is your Suprsonic credit balance, not a provider's.",
    "is_retriable": false,
    "error_category": "billing",
    "alternative_action": "Pro gives 2,000 credits a month, 10 times the free plan: choose it at https://suprsonic.ai/app/subscription, or wait until November 12."
  }
}

Categorías de error: transient (se puede reintentar sin riesgo), permanent (solicitud incorrecta), authentication (clave no válida), billing (créditos agotados), content_access (no se puede acceder a esa URL: está bloqueada, restringida por región o es privada).

Al usar MCP, el agente de IA recibe el objeto de error completo en la respuesta de la herramienta, por lo que puede decidir si reintenta según is_retriable y retry_after_seconds, y decirte qué indica alternative_action que debes hacer.

Referencia completa de la API con todos los parámetros y ejemplos de respuestas: suprsonic.ai/apis