MCP 伺服器

快速開始

1. 在控制台的 API 金鑰 頁面建立一把 API 金鑰。給 agent 用的金鑰，請設定消費上限與模型允許清單。
2. 用下方任一段設定把伺服器加進你的用戶端，並從環境變數讀取金鑰，不要把金鑰直接貼進檔案。
3. 向你的 agent 提問，例如：「列出支援工具的三個最便宜模型，再請其中最快的一個摘要這個檔案，並告訴我花了多少錢。」

連接你的用戶端

所有用戶端都使用同一個端點與標頭。請先在環境中設定 SYNTHORAI_API_KEY。

Claude Code

在 Claude Code 中執行 /mcp 檢查連線。加上 --scope user 可讓伺服器在所有專案中都可用；或把 .mcp.json 形式提交進版本庫與團隊共用（金鑰仍保留在每位開發者自己的環境中）。

claude mcp add --transport http synthorai https://synthorai.io/v1/mcp \
  --header "Authorization: Bearer $SYNTHORAI_API_KEY"

{
  "mcpServers": {
    "synthorai": {
      "type": "http",
      "url": "https://synthorai.io/v1/mcp",
      "headers": { "Authorization": "Bearer ${SYNTHORAI_API_KEY}" }
    }
  }
}

Cursor

放在 ~/.cursor/mcp.json（所有專案）或 .cursor/mcp.json（單一專案）。

{
  "mcpServers": {
    "synthorai": {
      "url": "https://synthorai.io/v1/mcp",
      "headers": { "Authorization": "Bearer ${env:SYNTHORAI_API_KEY}" }
    }
  }
}

VS Code (GitHub Copilot)

放在 .vscode/mcp.json。VS Code 只會詢問一次金鑰，並安全地儲存。

{
  "inputs": [
    { "type": "promptString", "id": "synthorai-key", "description": "Synthorai API key", "password": true }
  ],
  "servers": {
    "synthorai": {
      "type": "http",
      "url": "https://synthorai.io/v1/mcp",
      "headers": { "Authorization": "Bearer ${input:synthorai-key}" }
    }
  }
}

Codex CLI

放在 ~/.codex/config.toml，或執行 codex mcp add synthorai --url https://synthorai.io/v1/mcp --bearer-token-env-var SYNTHORAI_API_KEY。

[mcp_servers.synthorai]
url = "https://synthorai.io/v1/mcp"
bearer_token_env_var = "SYNTHORAI_API_KEY"

OpenAI Responses API

OpenAI 的伺服器會代你呼叫這個端點，因此請讓金鑰的 IP 允許清單保持空白（或放行 OpenAI 的出口 IP 範圍）。用 allowed_tools 只開放模型需要的工具。

import os
from openai import OpenAI

client = OpenAI()
resp = client.responses.create(
    model="gpt-4.1",
    tools=[{
        "type": "mcp",
        "server_label": "synthorai",
        "server_url": "https://synthorai.io/v1/mcp",
        "headers": {"Authorization": f"Bearer {os.environ['SYNTHORAI_API_KEY']}"},
        "allowed_tools": ["list_models", "chat_completion"],
        "require_approval": "never",
    }],
    input="Find the cheapest Synthorai chat model with tool support and ask it for a haiku about gateways.",
)
print(resp.output_text)

OpenAI Agents SDK

任何基於 MCP 用戶端 SDK 的框架（LangChain、LlamaIndex、Pydantic AI、Vercel AI SDK、Mastra……）用法都一樣：把它的 Streamable HTTP 傳輸指向該端點並帶上標頭即可。

import asyncio, os
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    async with MCPServerStreamableHttp(
        name="synthorai",
        params={
            "url": "https://synthorai.io/v1/mcp",
            "headers": {"Authorization": f"Bearer {os.environ['SYNTHORAI_API_KEY']}"},
            "timeout": 120,
        },
        cache_tools_list=True,
    ) as synthorai:
        agent = Agent(name="assistant", instructions="Use the Synthorai tools.", mcp_servers=[synthorai])
        result = await Runner.run(agent, "List three chat models under $1 per million input tokens.")
        print(result.final_output)

asyncio.run(main())

MCP Python SDK

import asyncio, os, httpx2
from mcp import Client
from mcp.client.streamable_http import streamable_http_client

async def main():
    http = httpx2.AsyncClient(
        headers={"Authorization": f"Bearer {os.environ['SYNTHORAI_API_KEY']}"}, timeout=120)
    async with Client(streamable_http_client("https://synthorai.io/v1/mcp", http_client=http)) as mcp:
        tools = await mcp.list_tools()
        print([t.name for t in tools.tools])
        result = await mcp.call_tool("chat_completion",
                                     {"model": "deepseek-v4-flash", "prompt": "Say hi in five words"})
        print(result.content[0].text)

asyncio.run(main())

Claude Desktop

Claude Desktop 與 claude.ai 的自訂連接器使用 OAuth 登入，而本伺服器尚未提供 OAuth（見下方「即將推出」）。在此之前，Claude Desktop 可以透過 mcp-remote 橋接連線，由它替你加上標頭：

{
  "mcpServers": {
    "synthorai": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://synthorai.io/v1/mcp", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer sk-syn-..." }
    }
  }
}

curl

本伺服器就是透過 HTTP 傳輸的純 JSON-RPC，不需要任何 SDK，也不需要握手：每個請求都各自獨立。

curl https://synthorai.io/v1/mcp \
  -H "Authorization: Bearer $SYNTHORAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"chat_completion",
                 "arguments":{"model":"deepseek-v4-flash","prompt":"Say hi in five words"}}}'

回應範例

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "Hi there, great to meet!" },
      { "type": "text", "text": "[deepseek-v4-flash · finish_reason stop · 12 in / 7 out tokens · cost $0.0000031 · request_id 0199a7c2-…]" }
    ],
    "structuredContent": {
      "model": "deepseek-v4-flash",
      "content": "Hi there, great to meet!",
      "finish_reason": "stop",
      "usage": { "prompt_tokens": 12, "completion_tokens": 7, "total_tokens": 19 },
      "cost_usd": 0.0000031,
      "request_id": "0199a7c2-…"
    }
  }
}

工具

tools/list 只回傳你的金鑰可用的工具：依金鑰類型，以及你的工作區已開通的功能過濾（圖像與影片生成目前為受限預覽）。會執行模型的工具，費用與對應的 REST 呼叫完全相同；其他工具一律免費。

推論金鑰

Provisioning key

帳單金鑰

list_models、get_model 與 get_pricing 對所有類型的金鑰都開放；使用推論金鑰時，list_models 只會列出該金鑰能呼叫的模型。

結果長什麼樣子

每個結果都帶有一段易讀的文字，並在 structuredContent 中以 JSON 附上同一份資料，聊天用戶端與程式都能直接使用。圖像與音訊以圖像、音訊內容回傳，影片則以連結回傳。會執行模型的工具在結尾附一行收據——模型、token、費用與 request_id——之後可用 get_generation 查詢。

權限與安全

• 與 REST API 規則相同。每次工具呼叫都由其對應的 REST 端點以你的金鑰執行：驗證、金鑰類型、IP 允許清單、模型允許清單、消費上限、速率限制與計費全部照常套用。MCP 不會新增任何權限，也不會略過任何檢查。
• 依金鑰類型實行最小權限。推論金鑰無法管理金鑰或讀取工作區帳單；provisioning key 無法呼叫模型；帳單金鑰為唯讀。
• 核准提示。每個工具都帶有 MCP annotations。唯讀工具標記為 readOnlyHint；會花錢的工具不屬於唯讀；update_api_key、delete_api_key 與 cancel_video 標記為 destructiveHint。用戶端會據此決定執行前要先向你確認哪些操作。
• 建議的 agent 金鑰：一把專用的推論金鑰，設定每日重設的消費上限與 allowed_models 清單；若 agent 在已知主機上執行，再加上 IP 允許清單。需要時可單獨撤銷，不影響正式環境的金鑰。
• 機密與不可信內容。create_api_key 只會回傳一次新金鑰——請告訴你的 agent 要把它存在哪裡。在讓 agent 依模型輸出與工具結果採取行動之前，請先將它們視為不可信的輸入（提示詞注入）。

協定細節

疑難排解

即將推出

• OAuth 登入：讓 claude.ai、Claude Desktop 與 ChatGPT 的連接器無需貼上金鑰即可連線，改用短效且有消費上限的憑證。
• MCP 閘道：同一個端點也能以你的金鑰彙整第三方 MCP 伺服器（GitHub、Slack 或你自己的伺服器），支援逐工具權限、憑證保存在伺服器端，並統一記錄在同一份稽核日誌中。
• 長時間呼叫的進度回報：工具執行期間即時串流進度。

相關：API 金鑰 · Provisioning Keys · 帳單 API · Chat Completions