Server MCP

Guida rapida

1. Crea una chiave API nella console, dalla pagina Chiavi API. Per un agente, assegnale un limite di spesa e un'allowlist dei modelli.
2. Aggiungi il server al tuo client con uno degli snippet qui sotto, leggendo la chiave da una variabile d'ambiente invece di incollarla in un file.
3. Chiedi al tuo agente, ad esempio: “Elenca i tre modelli più economici che supportano gli strumenti, poi chiedi al più veloce di riassumere questo file e dimmi quanto è costato.”

Collega il tuo client

Tutti i client usano lo stesso endpoint e lo stesso header. Imposta prima SYNTHORAI_API_KEY nel tuo ambiente.

Claude Code

Esegui /mcp in Claude Code per verificare la connessione. Aggiungi --scope user per rendere il server disponibile in tutti i progetti, oppure esegui il commit della forma .mcp.json per condividerlo con il tuo team (la chiave resta nell'ambiente di ogni sviluppatore).

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

Inseriscilo in ~/.cursor/mcp.json (tutti i progetti) o in .cursor/mcp.json (un singolo progetto).

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

VS Code (GitHub Copilot)

Inseriscilo in .vscode/mcp.json. VS Code chiede la chiave una sola volta e la conserva in modo sicuro.

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

Inseriscilo in ~/.codex/config.toml, oppure esegui 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

Sono i server di OpenAI a chiamare l'endpoint per tuo conto, quindi lascia vuota l'allowlist IP della chiave (oppure consenti gli intervalli di IP in uscita di OpenAI). Usa allowed_tools per esporre solo gli strumenti di cui il modello ha bisogno.

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

Funziona allo stesso modo con qualsiasi framework basato sugli SDK client MCP (LangChain, LlamaIndex, Pydantic AI, Vercel AI SDK, Mastra …): punta il suo trasporto Streamable HTTP all'endpoint con l'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

I connettori personalizzati di Claude Desktop e claude.ai accedono tramite OAuth, che questo server non offre ancora (vedi la roadmap più sotto). Nel frattempo, Claude Desktop può connettersi tramite il bridge mcp-remote, che aggiunge l'header per te:

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

curl

Il server usa semplice JSON-RPC su HTTP, quindi non serve alcun SDK. Non è richiesto alcun handshake: ogni richiesta è indipendente.

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

Esempio di risposta

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

Strumenti

tools/list restituisce solo gli strumenti che la tua chiave può usare: l'elenco è filtrato per tipo di chiave e per le funzionalità abilitate nel tuo workspace (la generazione di immagini e video è in anteprima limitata). Gli strumenti che eseguono un modello costano esattamente quanto la chiamata REST; tutti gli altri sono gratuiti.

Chiave di inferenza

Chiave di provisioning

Chiave di fatturazione

list_models, get_model e get_pricing sono disponibili per ogni tipo di chiave; per una chiave di inferenza, list_models mostra solo i modelli che quella chiave può chiamare.

Come sono fatti i risultati

Ogni risultato contiene un blocco di testo leggibile e gli stessi dati in JSON in structuredContent, così possono usarlo sia i client di chat sia i programmi. Immagini e audio vengono restituiti come contenuto immagine e audio, i video come link. Gli strumenti che eseguono un modello terminano con una riga di ricevuta (modello, token, costo e request_id) che get_generation può consultare in seguito.

Permessi e sicurezza

• Le stesse regole dell'API REST. Ogni chiamata a uno strumento viene eseguita dall'endpoint REST indicato, con la tua chiave: autenticazione, tipo di chiave, allowlist IP, allowlist dei modelli, limite di spesa, limiti di frequenza e fatturazione si applicano invariati. MCP non aggiunge alcun permesso e non salta alcun controllo.
• Privilegio minimo per tipo di chiave. Le chiavi di inferenza non possono gestire chiavi né leggere la fatturazione del workspace; le chiavi di provisioning non possono chiamare modelli; le chiavi di fatturazione sono di sola lettura.
• Indicazioni per l'approvazione. Ogni strumento include annotazioni MCP. Gli strumenti di sola lettura sono contrassegnati con readOnlyHint; gli strumenti che spendono denaro non sono di sola lettura; update_api_key, delete_api_key e cancel_video sono contrassegnati con destructiveHint. I client le usano per decidere cosa chiederti prima dell'esecuzione.
• Chiave consigliata per gli agenti: una chiave di inferenza dedicata con un limite di spesa che si azzera ogni giorno, un elenco allowed_models e un'allowlist IP quando l'agente gira su host noti. Puoi revocarla singolarmente senza toccare le chiavi di produzione.
• Segreti e contenuti non attendibili. create_api_key restituisce la nuova chiave una sola volta: indica al tuo agente dove conservarla. Tratta l'output dei modelli e i risultati degli strumenti come input non attendibile (prompt injection) prima di lasciare che un agente agisca in base a essi.

Dettagli del protocollo

Risoluzione dei problemi

Prossimamente

• Accesso OAuth, così i connettori di claude.ai, Claude Desktop e ChatGPT potranno connettersi senza incollare una chiave, con credenziali a breve durata e con tetto di spesa.
• Gateway MCP: lo stesso endpoint aggregherà anche server MCP di terze parti (GitHub, Slack, i tuoi) sotto la tua chiave, con permessi per singolo strumento, credenziali conservate lato server e un unico log di audit.
• Avanzamento delle chiamate lunghe, trasmesso in streaming mentre uno strumento è in esecuzione.

Vedi anche: Chiavi API · Chiavi di provisioning · API di fatturazione · Chat Completions