MCP Server

Quick start

1. Create an API key in the console on the API Keys page. For an agent, give it a spend limit and a model allow-list.
2. Add the server to your client with one of the snippets below, reading the key from an environment variable rather than pasting it into a file.
3. Ask your agent, for example: “List the three cheapest models that support tools, then ask the fastest one to summarize this file, and tell me what it cost.”

Connect your client

All clients use the same endpoint and header. Set SYNTHORAI_API_KEY in your environment first.

Claude Code

Run /mcp inside Claude Code to check the connection. Add --scope user to make the server available in every project, or commit the .mcp.json form to share it with your team (the key stays in each developer's environment).

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

Put this in ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project).

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

VS Code (GitHub Copilot)

Put this in .vscode/mcp.json. VS Code asks for the key once and stores it securely.

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

Put this in ~/.codex/config.toml, or run 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's servers call the endpoint on your behalf, so leave the key's IP allow-list empty (or allow OpenAI's egress ranges). Use allowed_tools to expose only the tools the model needs.

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

Works the same with any framework built on the MCP client SDKs (LangChain, LlamaIndex, Pydantic AI, Vercel AI SDK, Mastra …): point its Streamable HTTP transport at the endpoint with the header.

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

Custom connectors in Claude Desktop and claude.ai sign in with OAuth, which this server does not offer yet (see the roadmap below). Until then, Claude Desktop can connect through the mcp-remote bridge, which adds the header for you:

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

curl

The server is plain JSON-RPC over HTTP, so no SDK is needed. No handshake is required: every request stands on its own.

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

Example response

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

tools/list returns only the tools your key can use: it is filtered by key kind and by the features enabled for your workspace (image and video generation are in limited preview). Tools that run a model cost exactly what the REST call costs; every other tool is free.

Inference key

Provisioning key

Billing key

list_models, get_model and get_pricing are offered to every key kind; for an inference key, list_models shows only the models that key can call.

What results look like

Every result carries a readable text block and the same data as JSON in structuredContent, so both chat clients and programs can use it. Images and audio come back as image and audio content, videos as links. Tools that run a model end with a receipt line (model, tokens, cost and request_id) which get_generation can look up later.

Permissions and safety

• Same rules as the REST API. Each tool call is carried out by the REST endpoint it names, with your key: authentication, key kind, IP allow-list, model allow-list, spend limit, rate limits and billing all apply unchanged. MCP adds no permission and skips no check.
• Least privilege by key kind. Inference keys cannot manage keys or read workspace billing; provisioning keys cannot call models; billing keys are read-only.
• Approval hints. Every tool carries MCP annotations. Read-only tools are marked readOnlyHint; tools that spend money are not read-only; update_api_key, delete_api_key and cancel_video are marked destructiveHint. Clients use these to decide what to ask you before running.
• Recommended agent key: a dedicated inference key with a spend limit that resets daily, an allowed_models list, and an IP allow-list when the agent runs on known hosts. Revoke it on its own without touching production keys.
• Secrets and untrusted content. create_api_key returns the new key once: tell your agent where to store it. Treat model output and tool results as untrusted input (prompt injection) before letting an agent act on them.

Protocol details

Troubleshooting

Coming next

• OAuth sign-in, so claude.ai, Claude Desktop and ChatGPT connectors can connect without a pasted key, with short-lived, spend-capped credentials.
• MCP gateway: the same endpoint also aggregating third-party MCP servers (GitHub, Slack, your own) under your key, with per-tool permissions, credentials kept server-side and one audit log.
• Progress for long calls, streamed while a tool runs.

Related: API Keys · Provisioning Keys · Billing API · Chat Completions