Serveur MCP

Démarrage rapide

1. Créez une clé API dans la console, sur la page Clés API. Pour un agent, attribuez-lui un plafond de dépense et une liste blanche de modèles.
2. Ajoutez le serveur à votre client avec l'un des extraits ci-dessous, en lisant la clé depuis une variable d'environnement plutôt qu'en la collant dans un fichier.
3. Demandez à votre agent, par exemple : « Liste les trois modèles les moins chers qui prennent en charge les outils, puis demande au plus rapide de résumer ce fichier, et dis-moi combien ça a coûté. »

Connecter votre client

Tous les clients utilisent le même endpoint et le même en-tête. Définissez d'abord SYNTHORAI_API_KEY dans votre environnement.

Claude Code

Exécutez /mcp dans Claude Code pour vérifier la connexion. Ajoutez --scope user pour rendre le serveur disponible dans tous les projets, ou committez la forme .mcp.json pour le partager avec votre équipe (la clé reste dans l'environnement de chaque développeur).

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

Placez ceci dans ~/.cursor/mcp.json (tous les projets) ou .cursor/mcp.json (un seul projet).

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

VS Code (GitHub Copilot)

Placez ceci dans .vscode/mcp.json. VS Code demande la clé une seule fois et la stocke de manière sécurisée.

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

Placez ceci dans ~/.codex/config.toml, ou exécutez 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

Les serveurs d'OpenAI appellent l'endpoint en votre nom : laissez donc vide la liste blanche d'IP de la clé (ou autorisez les plages d'IP sortantes d'OpenAI). Utilisez allowed_tools pour n'exposer que les outils dont le modèle a besoin.

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

Fonctionne de la même manière avec tout framework basé sur les SDK clients MCP (LangChain, LlamaIndex, Pydantic AI, Vercel AI SDK, Mastra…) : pointez son transport Streamable HTTP vers l'endpoint, avec l'en-tête.

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

Les connecteurs personnalisés de Claude Desktop et claude.ai s'authentifient via OAuth, que ce serveur ne propose pas encore (voir la feuille de route ci-dessous). En attendant, Claude Desktop peut se connecter via le pont mcp-remote, qui ajoute l'en-tête pour vous :

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

curl

Le serveur parle du JSON-RPC simple sur HTTP : aucun SDK n'est nécessaire. Aucune poignée de main n'est requise : chaque requête est autonome.

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

Exemple de réponse

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

Outils

tools/list ne renvoie que les outils utilisables par votre clé : la liste est filtrée selon le type de clé et selon les fonctionnalités activées pour votre workspace (la génération d'images et de vidéos est en preview limitée). Les outils qui exécutent un modèle coûtent exactement le prix de l'appel REST ; tous les autres outils sont gratuits.

Clé d'inférence

Clé de provisioning

Clé de facturation

list_models, get_model et get_pricing sont proposés à tous les types de clés ; pour une clé d'inférence, list_models n'affiche que les modèles que cette clé peut appeler.

Format des résultats

Chaque résultat contient un bloc de texte lisible et les mêmes données en JSON dans structuredContent, exploitables aussi bien par les clients de chat que par les programmes. Les images et l'audio sont renvoyés comme contenu image et audio, les vidéos sous forme de liens. Les outils qui exécutent un modèle se terminent par une ligne de reçu - modèle, tokens, coût et request_id - que get_generation permet de consulter plus tard.

Permissions et sécurité

• Mêmes règles que l'API REST. Chaque appel d'outil est exécuté par l'endpoint REST qu'il nomme, avec votre clé : authentification, type de clé, liste blanche d'IP, liste blanche de modèles, plafond de dépense, limites de débit et facturation s'appliquent sans changement. MCP n'ajoute aucune permission et ne contourne aucun contrôle.
• Moindre privilège selon le type de clé. Les clés d'inférence ne peuvent ni gérer les clés ni lire la facturation du workspace ; les clés de provisioning ne peuvent pas appeler de modèles ; les clés de facturation sont en lecture seule.
• Indications d'approbation. Chaque outil porte des annotations MCP. Les outils en lecture seule sont marqués readOnlyHint ; les outils qui dépensent de l'argent ne sont pas en lecture seule ; update_api_key, delete_api_key et cancel_video sont marqués destructiveHint. Les clients s'en servent pour décider quoi vous demander avant l'exécution.
• Clé recommandée pour un agent : une clé d'inférence dédiée, avec un plafond de dépense réinitialisé chaque jour, une liste allowed_models et une liste blanche d'IP lorsque l'agent tourne sur des hôtes connus. Révoquez-la isolément, sans toucher aux clés de production.
• Secrets et contenu non fiable. create_api_key renvoie la nouvelle clé une seule fois - indiquez à votre agent où la stocker. Traitez la sortie des modèles et les résultats d'outils comme des entrées non fiables (injection de prompt) avant de laisser un agent agir en conséquence.

Détails du protocole

Dépannage

Prochainement

• Connexion OAuth, pour que les connecteurs claude.ai, Claude Desktop et ChatGPT puissent se connecter sans coller de clé, avec des identifiants à courte durée de vie et à dépense plafonnée.
• Passerelle MCP : le même endpoint agrégera aussi des serveurs MCP tiers (GitHub, Slack, les vôtres) sous votre clé, avec des permissions par outil, des identifiants conservés côté serveur et un journal d'audit unique.
• Progression des appels longs, diffusée pendant l'exécution d'un outil.

Voir aussi : Clés API · Clés de provisioning · API de facturation · Chat Completions