MCP サーバー

クイックスタート

1. コンソールの API キー ページで API キーを作成します。エージェント用には、利用上限とモデル許可リストを設定してください。
2. 以下のスニペットのいずれかを使ってクライアントにサーバーを追加します。キーはファイルに貼り付けず、環境変数から読み込んでください。
3. エージェントに、たとえば次のように頼んでみてください：「ツールに対応したモデルのうち最も安い 3 つを挙げて、その中で最も速いモデルにこのファイルを要約させ、かかった費用を教えて。」

クライアントを接続する

すべてのクライアントで同じエンドポイントとヘッダーを使います。先に環境変数 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 にはそのキーで呼び出せるモデルだけが表示されます。

結果の形式

すべての結果には、読みやすいテキストブロックと、同じデータを JSON で表した structuredContent が含まれるため、チャットクライアントとプログラムのどちらでも扱えます。画像と音声は画像・音声コンテンツとして、動画はリンクとして返されます。モデルを実行するツールの結果は、モデル、トークン数、コスト、request_id を記した明細行で終わり、後から get_generation で照会できます。

権限と安全性

• REST API と同じルール。各ツール呼び出しは、記載された REST エンドポイントがあなたのキーで実行します。認証、キーの種類、IP 許可リスト、モデル許可リスト、利用上限、レート制限、課金はすべてそのまま適用されます。MCP が権限を追加することも、チェックを省略することもありません。
• キーの種類による最小権限。推論キーはキーの管理やワークスペースの課金データの読み取りができず、provisioning key はモデルを呼び出せず、課金キーは読み取り専用です。
• 承認のヒント。すべてのツールに MCP アノテーションが付いています。読み取り専用のツールには readOnlyHint が付き、費用が発生するツールは読み取り専用扱いになりません。update_api_key、delete_api_key、cancel_video には destructiveHint が付いています。クライアントはこれらをもとに、実行前にユーザーへ確認する内容を判断します。
• エージェント用の推奨キー：毎日リセットされる利用上限と allowed_models リストを設定し、エージェントが既知のホストで動く場合は IP 許可リストも設定した専用の推論キー。本番用のキーに触れずに、そのキーだけを失効できます。
• シークレットと信頼できないコンテンツ。create_api_key は新しいキーを一度だけ返すため、保存先をエージェントに指示してください。エージェントに操作させる前に、モデルの出力とツールの結果は信頼できない入力（プロンプトインジェクション）として扱ってください。

プロトコルの詳細

トラブルシューティング

今後の予定

• OAuth サインイン：claude.ai、Claude Desktop、ChatGPT のコネクタが、キーを貼り付けずに、短期間有効で利用上限付きの認証情報で接続できるようになります。
• MCP ゲートウェイ：同じエンドポイントでサードパーティの MCP サーバー（GitHub、Slack、独自のサーバー）もあなたのキーの下に集約し、ツールごとの権限、サーバー側での認証情報の保管、単一の監査ログを提供します。
• 長時間の呼び出しの進捗を、ツールの実行中にストリーミングで通知します。

関連：API キー · Provisioning Keys · 課金 API · Chat Completions