Suprsonic

suprsonic-mcp

MCP server for Suprsonic. 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:

SUPRSONIC_API_KEY=omk_your_key npx -y suprsonic-mcp

Get your API key at 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

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):

{

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

{

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

{

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

{

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

{

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

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.

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

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:

{

"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