MCP 服务器

快速开始

1. 在控制台的 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 的出口网段）。用 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 登录，本服务器暂未提供（见下方路线图）。在此之前，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 调用完全相同；其余工具全部免费。

推理 API 密钥

Provisioning key

账单密钥

list_models、get_model 和 get_pricing 对所有密钥类型开放；使用推理 API 密钥时，list_models 只显示这把密钥能调用的模型。

返回结果的形态

每个结果都带一段可读文本，同时在 structuredContent 里给出同样数据的 JSON，对话客户端和程序都能直接使用。图片和音频以图片、音频内容返回，视频以链接返回。运行模型的工具结尾附一行回执 —— 模型、token 数、费用和 request_id —— 之后可用 get_generation 查询。

权限与安全

• 规则与 REST API 完全一致。每次工具调用都由它对应的 REST 端点、用你的密钥执行：鉴权、密钥类型、IP 白名单、模型白名单、额度上限、限流和计费全部照常生效。MCP 不增加任何权限，也不绕过任何检查。
• 按密钥类型最小授权。推理 API 密钥不能管理密钥，也不能读取工作区账单；provisioning key 不能调用模型；账单密钥只读。
• 审批提示。每个工具都带 MCP 注解：只读工具标记 readOnlyHint；会花钱的工具不标为只读；update_api_key、delete_api_key 和 cancel_video 标记 destructiveHint。客户端据此决定执行前要不要先征求你的确认。
• 推荐给 agent 的密钥：一把专用的推理 API 密钥，设置按天重置的额度上限、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