suprsonic-mcp

suprsonic-mcp

面向 Suprsonic 的 MCP 服务器。通过一个连接，为任意 AI 智能体提供数十种能力。

快速开始

连接到托管服务器，无需安装任何东西：

• URL：https://suprsonic.ai/v1/mcp（Streamable HTTP）
• 请求头：Authorization: Bearer omk_your_key（或 x-api-key: omk_your_key，适用于将 Authorization 保留用于自身登录的客户端或网关）

或者在你自己的机器上运行服务器：

SUPRSONIC_API_KEY=omk_your_key npx -y suprsonic-mcp

在 suprsonic.ai/app/api 获取你的 API 密钥。两种方式提供的工具和价格完全相同。列出工具无需密钥；使用无效密钥调用时，会返回 API 自身的错误信息，其中说明了在哪里获取密钥。

包名为 suprsonic-mcp。本 README 的早期版本写的是 @suprsonic/mcp：该 npm 作用域属于一家无关公司，因此切勿安装它。

托管服务器

Claude Code

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

Cursor

添加到 ~/.cursor/mcp.json（或在项目中添加到 .cursor/mcp.json）：

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

VS Code

添加到 .vscode/mcp.json（VS Code 会询问一次密钥，并将其存储为机密）：

{
  "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 连接器）

发送 beta 请求头 anthropic-beta: mcp-client-2025-11-20，并添加到你的 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

添加到请求的 tools 中：

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

Smithery

Suprsonic 已在 Smithery 上以 suprsonic 列出。将其添加到你的 Smithery 工具箱，并在 Smithery 询问时粘贴你的密钥；Smithery 会将其作为 x-api-key 传递给托管服务器。

本地服务器（npx）

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

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

同样的条目也适用于 Cursor 的 mcp.json。

你自己的 HTTP 端点

要从你自己的机器提供 HTTP 传输，而不是使用托管服务器：

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

然后连接到 http://localhost:3100/mcp。

可用工具

调用仅在成功时消耗积分。若显示范围，你选择的模式决定价格。

工具	功能	积分
search	使用 SERP、AI 综合或两者进行网络搜索	1-3
scrape	从任意 URL 提取内容为 Markdown 或 HTML	1-5
profiles	查找并丰富职业档案	3
emails	查找职业电子邮件地址	2
images	根据文本提示生成图像	3
tts	将文本转换为语音音频	2
stt	将音频转录为带时间戳的文本	2
sound-generate	根据文本提示生成音效和短音乐曲目（非语音：语音请使用 tts）	4
sms	发送 SMS 或 WhatsApp 消息。默认渠道为 SMS（可靠送达）。WhatsApp 需要收件人选择加入：他们必须在 24 小时内向你的 Business 号码发送过消息。	1
documents	从 URL 或内容中提取结构化数据	3
companies	按域名丰富公司数据	3
email-verify	检查电子邮件是否可送达、全接收或一次性	1
transcribe	转录音频，带说话人分离和时间戳	3
invoice-parse	从发票和收据中提取结构化数据	3
subtitle	从音频或视频生成 SRT/VTT 字幕	2
file-convert	在格式之间转换文档、网页、电子表格和图像	2
bg-remove	从任意图像中移除背景。返回透明 PNG。	2
screenshot	捕获任意网页的渲染截图	1
code-execute	在预配置环境的安全沙箱中执行代码	2
site-intel	获取全面的域名情报：WHOIS、DNS、SSL、技术栈、电子邮件安全、托管	1-2
research	多步骤深度研究：搜索、抓取、丰富实体，并综合为带引用的报告	10-35
video-info	从任意 URL 提取视频元数据、可用格式和缩略图	1
video-download	从任意 URL 下载视频并返回临时下载链接	2-3
domains	查找适合企业的域名和扩展名	1-5

响应格式

每个工具都返回统一的响应对象：

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

失败时，success 为 false，error 包含详细信息（见下文）。

错误处理

每个错误都是同一个对象。失败的能力会将其作为上述响应中的 error 返回，其中 success 设置为 false，且不扣除积分。被拒绝的调用（无效密钥、积分不足、速率限制）会以 HTTP 401、402 或 429 响应，并将该对象放在 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."
  }
}

错误类别：transient（可安全重试）、permanent（错误请求）、authentication（无效密钥）、billing（积分不足）、content_access（该 URL 无法提供：被阻止、受区域限制或私有）。

使用 MCP 时，AI 智能体会在工具响应中收到完整的错误对象，因此它可以根据 is_retriable 和 retry_after_seconds 决定是否重试，并告诉你 alternative_action 指示该做什么。

包含所有参数和示例响应的完整 API 参考：suprsonic.ai/apis