# suprsonic-mcp MCP server for [Suprsonic](https://suprsonic.ai). Gives any AI agent dozens of capabilities through one connection. ## Quick Start Connect to the hosted server, nothing to install: - URL: `https://suprsonic.ai/v1/mcp` (Streamable HTTP) - Header: `Authorization: Bearer omk_your_key` (or `x-api-key: omk_your_key`, for a client or gateway that keeps `Authorization` for its own sign-in) Or run the server on your own machine: ```bash SUPRSONIC_API_KEY=omk_your_key npx -y suprsonic-mcp ``` Get your API key at [suprsonic.ai/app/api](https://suprsonic.ai/app/api). Both offer the same tools at the same prices. Listing the tools needs no key; a call without a valid key answers with the API's own error, which says where to get one. The package is `suprsonic-mcp`. Earlier copies of this README named `@suprsonic/mcp`: that npm scope belongs to an unrelated company, so never install it. ## Hosted server ### Claude Code ```bash claude mcp add --transport http suprsonic https://suprsonic.ai/v1/mcp --header "Authorization: Bearer omk_your_key" ``` ### Cursor Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project): ```json { "mcpServers": { "suprsonic": { "url": "https://suprsonic.ai/v1/mcp", "headers": { "Authorization": "Bearer omk_your_key" } } } } ``` ### VS Code Add to `.vscode/mcp.json` (VS Code asks for the key once and stores it as a secret): ```json { "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 (MCP connector) Send the beta header `anthropic-beta: mcp-client-2025-11-20` and add to your Messages request: ```json { "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 Add to the request's `tools`: ```json { "type": "mcp", "server_label": "suprsonic", "server_url": "https://suprsonic.ai/v1/mcp", "authorization": "omk_your_key", "require_approval": "never" } ``` ### Smithery Suprsonic is listed on Smithery as [suprsonic](https://smithery.ai/servers/suprsonic). Add it to your Smithery toolbox and paste your key when Smithery asks for it; Smithery passes it to the hosted server as `x-api-key`. ## Local server (npx) ### Claude Desktop Add to `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "suprsonic": { "command": "npx", "args": ["-y", "suprsonic-mcp"], "env": { "SUPRSONIC_API_KEY": "omk_your_key" } } } } ``` The same entry works in Cursor's `mcp.json`. ### Your own HTTP endpoint To serve the HTTP transport from your own machine instead of using the hosted server: ```bash SUPRSONIC_API_KEY=omk_your_key npx -y suprsonic-mcp --http --port 3100 ``` Then connect to `http://localhost:3100/mcp`. ## Available Tools A call costs credits only when it succeeds. Where a range is shown, the mode you pick sets the price. | Tool | What it does | Credits | |------|-------------|---------| | search | Search the web with SERP, AI synthesis, or both | 1-3 | | scrape | Extract content from any URL as Markdown or HTML | 1-5 | | profiles | Find and enrich professional profiles | 3 | | emails | Find professional email addresses | 2 | | images | Generate images from text prompts | 3 | | tts | Convert text to speech audio | 2 | | stt | Transcribe audio to text with timestamps | 2 | | sound-generate | Generate sound effects and short music tracks from text prompts (NOT speech: use tts for spoken voice) | 4 | | sms | Send SMS or WhatsApp messages. Default channel is SMS (reliable delivery). WhatsApp requires recipient opt-in: they must have messaged your Business number within 24 hours. | 1 | | documents | Extract structured data from URLs or content | 3 | | companies | Enrich company data by domain | 3 | | email-verify | Check if an email is deliverable, catch-all, or disposable | 1 | | transcribe | Transcribe audio with speaker diarization and timestamps | 3 | | invoice-parse | Extract structured data from invoices and receipts | 3 | | subtitle | Generate SRT/VTT subtitles from audio or video | 2 | | file-convert | Convert documents, web pages, spreadsheets and images between formats | 2 | | bg-remove | Remove background from any image. Returns transparent PNG. | 2 | | screenshot | Capture a rendered screenshot of any webpage | 1 | | code-execute | Execute code in a secure sandbox with pre-configured environments | 2 | | site-intel | Get comprehensive domain intelligence: WHOIS, DNS, SSL, tech stack, email security, hosting | 1-2 | | research | Multi-step deep research: search, scrape, enrich entities, and synthesize into a cited report | 10-35 | | video-info | Extract video metadata, available formats, and thumbnail from any URL | 1 | | video-download | Download video from any URL and return a temporary download link | 2-3 | | domains | Find domain names and the extensions that fit a business | 1-5 | ## Response Format Every tool returns a unified response object: ```json { "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 Every error is the same object. A capability that fails returns it as `error` in the response above, with `success` set to `false` and no credits charged. A refused call (an invalid key, too few credits, a rate limit) answers HTTP 401, 402 or 429 with the object under `detail`: ```json { "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." } } ``` Error categories: `transient` (retry safe), `permanent` (bad request), `authentication` (invalid key), `billing` (out of credits), `content_access` (that URL cannot be served: blocked, region-locked or private). When using MCP, the AI agent receives the whole error object in the tool response, so it can decide whether to retry from `is_retriable` and `retry_after_seconds`, and tell you what `alternative_action` says to do. Full API reference with all parameters and example responses: [suprsonic.ai/apis](https://suprsonic.ai/apis)