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.

Clients, die sich per Anmeldung verbinden (claude.ai, Claude Desktop, ChatGPT), brauchen keinen Schlüssel. Fügen Sie den Endpunkt oben als Connector hinzu und melden Sie sich bei Synthorai an. Dabei wählen Sie den Workspace und legen fest, was die Verbindung darf. Die Verbindung erhält einen eigenen Schlüssel mit Ablaufdatum. Er steht unter API-Schlüssel und lässt sich dort entfernen.

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

Claude Desktop verbindet sich per Anmeldung: Fügen Sie den Endpunkt als benutzerdefinierten Connector hinzu, ein Schlüssel ist nicht nötig. Wenn Sie stattdessen einen eigenen Schlüssel verwenden möchten, verbinden Sie sich über die Bridge mcp-remote, 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

Admin-Schlüssel: Anfrageprotokoll und Nutzung

Admin-Schlüssel: Prompt-Bibliothek

Admin-Schlüssel: Workspace

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.

Festlegen, was eine Verbindung darf

• Für den Workspace. Unter Einstellungen > MCP schaltet ein Admin MCP ein oder aus, wählt die Tool-Gruppen, die Verbindungen nutzen dürfen, und legt fest, ob Tools verwendet werden dürfen, die etwas ändern. Auf einer dedizierten Instanz ist MCP aus, bis ein Admin es einschaltet.
• Für eine einzelne Verbindung. Senden Sie X-MCP-Readonly: true, um alle Tools zu entfernen, die etwas ändern oder Geld ausgeben, und X-MCP-Toolsets: logs,prompts, um nur diese Gruppen zu behalten (usage, logs, prompts, keys, workspace, inference). Clients, die keine Header setzen können, hängen ?readonly=true&toolsets=logs,prompts an die URL an.
• Das alles schränkt die Tools nur ein. Ein Tool wird aufgelistet, wenn es die Scopes des Schlüssels, die Einstellungen des Workspace und die Einschränkungen der Verbindung zulassen.
• Jede Änderung wird protokolliert. Was über MCP geändert wird, steht mit dem Schlüssel und dem Namen des Clients im Audit-Log.

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.
• Geringste Rechte je Schlüssel. Ein Inferenzschlüssel kann weder Schlüssel verwalten noch die Abrechnung des Workspace lesen; ein Admin-Schlüssel kann keine Modelle aufrufen und darf nur, was seine Scopes erlauben.
• 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

• 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