suprsonic-mcp

suprsonic-mcp

Servidor MCP para o Suprsonic. Oferece a qualquer agente de IA dezenas de capacidades por meio de uma única conexão.

Início Rápido

Conecte-se ao servidor hospedado, sem nada para instalar:

• URL: https://suprsonic.ai/v1/mcp (Streamable HTTP)
• Cabeçalho: Authorization: Bearer omk_your_key (ou x-api-key: omk_your_key, para um cliente ou gateway que mantém Authorization para seu próprio login)

Ou execute o servidor na sua própria máquina:

SUPRSONIC_API_KEY=omk_your_key npx -y suprsonic-mcp

Obtenha sua chave de API em suprsonic.ai/app/api. Ambos oferecem as mesmas ferramentas pelos mesmos preços. Listar as ferramentas não exige chave; uma chamada sem uma chave válida responde com o próprio erro da API, que indica onde obter uma.

O pacote é suprsonic-mcp. Cópias anteriores deste README mencionavam @suprsonic/mcp: esse escopo do npm pertence a uma empresa não relacionada, então nunca o instale.

Servidor hospedado

Claude Code

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

Cursor

Adicione a ~/.cursor/mcp.json (ou .cursor/mcp.json em um projeto):

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

VS Code

Adicione a .vscode/mcp.json (o VS Code solicita a chave uma vez e a armazena como segredo):

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

Envie o cabeçalho beta anthropic-beta: mcp-client-2025-11-20 e adicione à sua requisição de 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" }
  ]
}

OpenAI Responses API

Adicione ao tools da requisição:

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

Smithery

O Suprsonic está listado no Smithery como suprsonic. Adicione-o à sua caixa de ferramentas do Smithery e cole sua chave quando o Smithery solicitar; o Smithery a repassa ao servidor hospedado como x-api-key.

Servidor local (npx)

Claude Desktop

Adicione a ~/Library/Application Support/Claude/claude_desktop_config.json:

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

A mesma entrada funciona no mcp.json do Cursor.

Seu próprio endpoint HTTP

Para servir o transporte HTTP a partir da sua própria máquina em vez de usar o servidor hospedado:

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

Em seguida, conecte-se a http://localhost:3100/mcp.

Ferramentas Disponíveis

Uma chamada só consome créditos quando é bem-sucedida. Onde um intervalo é mostrado, o modo que você escolher define o preço.

Ferramenta	O que faz	Créditos
search	Pesquisa na web com SERP, síntese por IA ou ambos	1-3
scrape	Extrai conteúdo de qualquer URL como Markdown ou HTML	1-5
profiles	Encontra e enriquece perfis profissionais	3
emails	Encontra endereços de e-mail profissionais	2
images	Gera imagens a partir de prompts de texto	3
tts	Converte texto em áudio de fala	2
stt	Transcreve áudio em texto com carimbos de data/hora	2
sound-generate	Gera efeitos sonoros e faixas musicais curtas a partir de prompts de texto (NÃO é fala: use tts para voz falada)	4
sms	Envia mensagens SMS ou WhatsApp. O canal padrão é SMS (entrega confiável). O WhatsApp exige opt-in do destinatário: ele deve ter enviado mensagem ao seu número Business nas últimas 24 horas.	1
documents	Extrai dados estruturados de URLs ou conteúdo	3
companies	Enriquece dados de empresas por domínio	3
email-verify	Verifica se um e-mail é entregável, catch-all ou descartável	1
transcribe	Transcreve áudio com diarização de falantes e carimbos de data/hora	3
invoice-parse	Extrai dados estruturados de faturas e recibos	3
subtitle	Gera legendas SRT/VTT a partir de áudio ou vídeo	2
file-convert	Converte documentos, páginas web, planilhas e imagens entre formatos	2
bg-remove	Remove o fundo de qualquer imagem. Retorna PNG transparente.	2
screenshot	Captura uma captura de tela renderizada de qualquer página web	1
code-execute	Executa código em um sandbox seguro com ambientes pré-configurados	2
site-intel	Obtém inteligência abrangente de domínio: WHOIS, DNS, SSL, stack de tecnologia, segurança de e-mail, hospedagem	1-2
research	Pesquisa profunda em várias etapas: pesquisa, extração, enriquecimento de entidades e síntese em um relatório com citações	10-35
video-info	Extrai metadados de vídeo, formatos disponíveis e miniatura de qualquer URL	1
video-download	Baixa vídeo de qualquer URL e retorna um link de download temporário	2-3
domains	Encontra nomes de domínio e as extensões que se adequam a um negócio	1-5

Formato de Resposta

Toda ferramenta retorna um objeto de resposta 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
}

Em caso de falha, success é false e error contém os detalhes (veja abaixo).

Tratamento de Erros

Todo erro é o mesmo objeto. Uma capacidade que falha o retorna como error na resposta acima, com success definido como false e sem cobrança de créditos. Uma chamada recusada (uma chave inválida, créditos insuficientes, um limite de taxa) responde com HTTP 401, 402 ou 429 com o objeto em 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."
  }
}

Categorias de erro: transient (nova tentativa segura), permanent (requisição inválida), authentication (chave inválida), billing (sem créditos), content_access (essa URL não pode ser servida: bloqueada, com restrição regional ou privada).

Ao usar MCP, o agente de IA recebe o objeto de erro completo na resposta da ferramenta, para que possa decidir se deve tentar novamente a partir de is_retriable e retry_after_seconds, e informar o que alternative_action diz para fazer.

Referência completa da API com todos os parâmetros e exemplos de resposta: suprsonic.ai/apis