MCP-Server

Schnellstart

1. Erstellen Sie in der Konsole auf der Seite API-Schlüssel einen API-Schlüssel. Geben Sie ihm für einen Agenten ein Ausgabenlimit und eine Modell-Allowlist.
2. Fügen Sie den Server mit einem der folgenden Snippets zu Ihrem Client hinzu und lesen Sie den Schlüssel dabei aus einer Umgebungsvariablen, statt ihn in eine Datei einzufügen.
3. Fragen Sie Ihren Agenten zum Beispiel: „Liste die drei günstigsten Modelle auf, die Tools unterstützen, lass dann das schnellste diese Datei zusammenfassen und sag mir, was es gekostet hat.“

Client verbinden

Alle Clients verwenden denselben Endpunkt und denselben Header. Setzen Sie zuerst SYNTHORAI_API_KEY in Ihrer Umgebung.

Claude Code

Führen Sie in Claude Code /mcp aus, um die Verbindung zu prüfen. Mit --scope user steht der Server in jedem Projekt zur Verfügung; alternativ committen Sie die .mcp.json-Variante, um ihn mit Ihrem Team zu teilen (der Schlüssel bleibt in der Umgebung jedes Entwicklers).

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

Legen Sie dies in ~/.cursor/mcp.json (alle Projekte) oder .cursor/mcp.json (ein Projekt) ab.

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

VS Code (GitHub Copilot)

Legen Sie dies in .vscode/mcp.json ab. VS Code fragt den Schlüssel einmal ab und speichert ihn sicher.

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

Legen Sie dies in ~/.codex/config.toml ab, oder führen Sie codex mcp add synthorai --url https://synthorai.io/v1/mcp --bearer-token-env-var SYNTHORAI_API_KEY aus.

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

OpenAI Responses API

Die Server von OpenAI rufen den Endpunkt in Ihrem Namen auf. Lassen Sie die IP-Allowlist des Schlüssels daher leer (oder lassen Sie die Egress-Bereiche von OpenAI zu). Mit allowed_tools geben Sie nur die Tools frei, die das Modell braucht.

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

Funktioniert genauso mit jedem Framework, das auf den MCP-Client-SDKs aufbaut (LangChain, LlamaIndex, Pydantic AI, Vercel AI SDK, Mastra …): Richten Sie seinen Transport für Streamable HTTP mit dem Header auf den Endpunkt aus.

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

Benutzerdefinierte Connectors in Claude Desktop und claude.ai melden sich per OAuth an, was dieser Server noch nicht anbietet (siehe Roadmap unten). Bis dahin kann sich Claude Desktop über die Bridge mcp-remote verbinden, die den Header für Sie ergänzt:

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

curl

Der Server spricht einfaches JSON-RPC über HTTP, ein SDK ist also nicht nötig. Ein Handshake ist nicht erforderlich: Jede Anfrage steht für sich.

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

Beispielantwort

{
  "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 liefert nur die Tools, die Ihr Schlüssel nutzen kann: Die Liste wird nach Schlüsselart und nach den für Ihren Workspace freigeschalteten Funktionen gefiltert (Bild- und Videogenerierung befinden sich in einer eingeschränkten Vorschau). Tools, die ein Modell ausführen, kosten genau so viel wie der REST-Aufruf; alle anderen Tools sind kostenlos.

Inferenzschlüssel

Provisioning-Schlüssel

Billing-Schlüssel

list_models, get_model und get_pricing stehen jeder Schlüsselart zur Verfügung; bei einem Inferenzschlüssel zeigt list_models nur die Modelle, die dieser Schlüssel aufrufen kann.

So sehen Ergebnisse aus

Jedes Ergebnis enthält einen lesbaren Textblock und dieselben Daten als JSON in structuredContent, sodass Chat-Clients wie Programme damit arbeiten können. Bilder und Audio kommen als Bild- und Audioinhalt zurück, Videos als Links. Tools, die ein Modell ausführen, enden mit einer Belegzeile (Modell, Tokens, Kosten und request_id) , die get_generation später nachschlagen kann.

Berechtigungen und Sicherheit

• Dieselben Regeln wie bei der REST-API. Jeder Tool-Aufruf wird von dem jeweils genannten REST-Endpunkt mit Ihrem Schlüssel ausgeführt: Authentifizierung, Schlüsselart, IP-Allowlist, Modell-Allowlist, Ausgabenlimit, Rate-Limits und Abrechnung gelten unverändert. MCP fügt keine Berechtigung hinzu und überspringt keine Prüfung.
• Minimale Rechte je Schlüsselart. Inferenzschlüssel können keine Schlüssel verwalten und keine Workspace-Abrechnung lesen; Provisioning-Schlüssel können keine Modelle aufrufen; Billing-Schlüssel sind nur lesend.
• Hinweise zur Freigabe. Jedes Tool trägt MCP-Annotationen. Nur lesende Tools sind mit readOnlyHint markiert; Tools, die Geld ausgeben, gelten nicht als nur lesend; update_api_key, delete_api_key und cancel_video sind mit destructiveHint markiert. Clients entscheiden anhand dieser Angaben, wann sie vor der Ausführung bei Ihnen nachfragen.
• Empfohlener Schlüssel für Agenten: ein eigener Inferenzschlüssel mit täglich zurückgesetztem Ausgabenlimit, einer allowed_models-Liste und einer IP-Allowlist, wenn der Agent auf bekannten Hosts läuft. Sie können ihn einzeln widerrufen, ohne Produktionsschlüssel anzutasten.
• Secrets und nicht vertrauenswürdige Inhalte. create_api_key gibt den neuen Schlüssel nur einmal zurück: sagen Sie Ihrem Agenten, wo er ihn speichern soll. Behandeln Sie Modellausgaben und Tool-Ergebnisse als nicht vertrauenswürdige Eingaben (Prompt Injection), bevor ein Agent darauf reagiert.

Protokolldetails

Fehlerbehebung

Demnächst

• OAuth-Anmeldung, damit sich Connectors von claude.ai, Claude Desktop und ChatGPT ohne eingefügten Schlüssel verbinden können: mit kurzlebigen Anmeldedaten und Ausgabenobergrenze.
• MCP-Gateway: Derselbe Endpunkt bündelt zusätzlich MCP-Server von Drittanbietern (GitHub, Slack, Ihre eigenen) unter Ihrem Schlüssel, mit Berechtigungen pro Tool, serverseitig verwahrten Anmeldedaten und einem gemeinsamen Audit-Log.
• Fortschritt bei langen Aufrufen, gestreamt, während ein Tool läuft.

Siehe auch: API-Schlüssel · Provisioning-Schlüssel · Billing-API · Chat Completions