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 scope 屬於另一家不相關的公司，因此切勿安裝它。

託管伺服器

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	以 Markdown 或 HTML 擷取任何 URL 的內容	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	檢查電子郵件是否可送達、為 catch-all 或為一次性	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