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.

Clients that connect by signing in (claude.ai, Claude Desktop, ChatGPT) need no key. Add the endpoint above as a connector and sign in to Synthorai: you pick the workspace and what the connection may do. It gets a key of its own with an expiry, listed under API keys, where you can remove it.

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

Claude Desktop connects by signing in: add the endpoint as a custom connector and no key is needed. To use a key of your own instead, 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

Admin key: request log and usage

Admin key: prompt library

Admin key: workspace

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.

Control what a connection can do

• For the workspace. Under Settings > MCP, an admin turns MCP on or off, picks the groups of tools connections may use, and decides whether tools that change something may be used. On a dedicated instance MCP is off until an admin turns it on.
• For one connection. Send X-MCP-Readonly: true to drop every tool that changes something or spends money, and X-MCP-Toolsets: logs,prompts to keep only those groups (usage, logs, prompts, keys, workspace, inference). Clients that cannot set headers put ?readonly=true&toolsets=logs,prompts in the URL.
• These only take tools away. A tool is listed when the key’s scopes, the workspace’s settings and the connection’s own limits all allow it.
• Every change is recorded. Changes made through MCP appear in the audit log with the key and the client’s name.

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. An inference key cannot manage keys or read workspace billing; an admin key cannot call models, and can do only what its scopes allow.
• 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

• 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