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.

I client che si connettono effettuando l'accesso (claude.ai, Claude Desktop, ChatGPT) non hanno bisogno di una chiave. Aggiungi l'endpoint qui sopra come connettore e accedi a Synthorai: scegli tu il workspace e che cosa può fare la connessione. La connessione riceve una chiave propria, con una scadenza: la trovi in Chiavi API, dove puoi anche rimuoverla.

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

Claude Desktop si connette effettuando l'accesso: aggiungi l'endpoint come connettore personalizzato e non serve alcuna chiave. Per usare una tua chiave, connettiti 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

Chiave di amministrazione: registro delle richieste e utilizzo

Chiave di amministrazione: libreria dei prompt

Chiave di amministrazione: workspace

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.

Controlla cosa può fare una connessione

• Per il workspace. In Impostazioni > MCP un amministratore attiva o disattiva MCP, sceglie i gruppi di strumenti che le connessioni possono usare e decide se consentire gli strumenti che modificano qualcosa. Su un’istanza dedicata MCP resta disattivato finché un amministratore non lo attiva.
• Per una singola connessione. Invia X-MCP-Readonly: true per escludere tutti gli strumenti che modificano qualcosa o spendono denaro, e X-MCP-Toolsets: logs,prompts per tenere solo quei gruppi (usage, logs, prompts, keys, workspace, inference). I client che non possono impostare header aggiungono ?readonly=true&toolsets=logs,prompts all’URL.
• Tutto questo può solo togliere strumenti. Uno strumento compare nell’elenco quando lo consentono tutti e tre: gli ambiti della chiave, le impostazioni del workspace e i limiti della connessione stessa.
• Ogni modifica viene registrata. Una modifica fatta tramite MCP compare nel registro di audit con la chiave e il nome del client.

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 chiave. Una chiave di inferenza non può gestire le chiavi né leggere la fatturazione del workspace; una chiave di amministrazione non può chiamare i modelli e fa solo ciò che prevedono i suoi ambiti.
• 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

• 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