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.

Les clients qui se connectent par identification (claude.ai, Claude Desktop, ChatGPT) n'ont pas besoin de clé. Ajoutez l'endpoint ci-dessus comme connecteur, puis connectez-vous à Synthorai : vous choisissez l'espace de travail et ce que la connexion peut faire. Elle reçoit sa propre clé, avec une date d'expiration, visible dans Clés API, où vous pouvez la supprimer.

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

Claude Desktop se connecte par identification : ajoutez l'endpoint comme connecteur personnalisé, sans clé. Pour utiliser votre propre clé, passez par 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

Clé d’administration : journal des requêtes et usage

Clé d’administration : bibliothèque de prompts

Clé d’administration : espace de travail

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.

Contrôler ce qu’une connexion peut faire

• Pour l’espace de travail. Dans Paramètres > MCP, un admin active ou désactive MCP, choisit les groupes d’outils que les connexions peuvent utiliser et décide si les outils qui modifient quelque chose sont autorisés. Sur une instance dédiée, MCP reste désactivé tant qu’un admin ne l’a pas activé.
• Pour une connexion. Envoyez X-MCP-Readonly: true pour retirer tous les outils qui modifient quelque chose ou engagent une dépense, et X-MCP-Toolsets: logs,prompts pour ne garder que ces groupes (usage, logs, prompts, keys, workspace, inference). Les clients qui ne peuvent pas définir d’en-têtes ajoutent ?readonly=true&toolsets=logs,prompts à l’URL.
• Ces réglages ne font que retirer des outils. Un outil apparaît dans la liste lorsque les portées de la clé, les paramètres de l’espace de travail et les limites propres à la connexion l’autorisent tous.
• Chaque modification est consignée. Une modification faite via MCP figure dans le journal d’audit, avec la clé et le nom du client.

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 par clé. Une clé d’inférence ne peut ni gérer les clés ni lire la facturation de l’espace de travail ; une clé d’administration ne peut pas appeler de modèles et se limite à ce que ses portées autorisent.
• 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

• 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