@suprsonic/mcp

MCP server for Suprsonic. Gives any AI agent dozens of capabilities through one connection.

Quick Start

SUPRSONIC_API_KEY=omk_your_key npx -y @suprsonic/mcp

Get your API key at suprsonic.ai/app/apis.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Cursor / VS Code

Add to .cursor/mcp.json or VS Code MCP config:

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

Remote HTTP (for Claude API, ChatGPT, programmatic agents)

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

Then connect to http://localhost:3100/mcp.

Available Tools

| Tool | What it does | |------|-------------| | search | Search the web (AI synthesis, SERP, or both) | | scrape | Extract content from any URL as Markdown | | profiles | Find professional profiles by name or LinkedIn URL | | emails | Find professional email addresses | | images | Generate images from text prompts | | tts | Convert text to speech | | stt | Transcribe audio to text | | sms | Send SMS or WhatsApp messages | | documents | Extract structured data from URLs | | companies | Look up company data by domain | | email-verify | Check if an email is deliverable | | transcribe | Transcribe audio with speaker labels | | invoice-parse | Extract data from invoices | | subtitle | Generate SRT/VTT subtitles | | file-convert | Convert files between 200+ formats | | bg-remove | Remove image backgrounds | | screenshot | Capture webpage screenshots |

Response Format

Every tool returns a unified response object:

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

On failure, success is false and error contains the details (see below).

Error Handling

Error object structure (returned when success is false):

{
  "type": "billing_error",
  "title": "Insufficient credits",
  "status": 402,
  "detail": "Your account has 0 credits remaining. Add credits at suprsonic.ai/app/billing.",
  "is_retriable": false,
  "retry_after_seconds": null,
  "error_category": "billing"
}

Error categories: transient (retry safe), permanent (bad request), authentication (invalid key), billing (out of credits).

When using MCP, the AI agent receives the error in the tool response and can decide whether to retry based on is_retriable and retry_after_seconds.

Full API reference with all parameters and example responses: suprsonic.ai/apis