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

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 requires 2 Suprsonic API credits but you have 0. This is your Suprsonic subscription balance, not a provider balance.",
    "is_retriable": false,
    "error_category": "billing",
    "alternative_action": "Upgrade your plan or enable credit overage at https://suprsonic.ai/app/subscription"
  }
}

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