Server MCP

Collega Claude Code, Cursor, Codex, VS Code e altri client MCP ai modelli di immagine e video di SeedRouter con la tua chiave API.

SeedRouter mette a disposizione un server remoto Model Context Protocol. Un agente IA può usarlo per elencare i modelli di immagine e video, consultarne gli schemi di richiesta e i prezzi, inviare attività di generazione e recuperarne i risultati, senza che tu debba scrivere codice di integrazione.

https://api.seedrouter.ai/v1/mcp

Trasporto: Streamable HTTP, senza stato. Il server supporta la versione 2026-07-28 del protocollo e le versioni precedenti che iniziano con un handshake initialize, fino alla 2024-11-05.
Autenticazione: la tua chiave API SeedRouter come token Bearer, Authorization: Bearer YOUR_API_KEY. Creane una nella pagina Chiavi API; vedi Autenticazione.
Fatturazione: identica a quella dell'API HTTP. Ogni chiamata a submit_task corrisponde a una richiesta all'endpoint delle attività pertinente e viene addebitata allo stesso modo.

I client che consentono l'accesso solo tramite OAuth, senza un campo per un header personalizzato, non possono ancora connettersi.

Connettere un client

La pagina Chiavi API ha un pulsante Connetti tramite MCP che inserisce una delle tue chiavi per ciascun client qui sotto.

Claude Code

claude mcp add --transport http seedrouter https://api.seedrouter.ai/v1/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Cursor

Aggiungi quanto segue a ~/.cursor/mcp.json, oppure a .cursor/mcp.json in un progetto:

{
  "mcpServers": {
    "seedrouter": {
      "url": "https://api.seedrouter.ai/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Codex CLI

Codex legge la chiave da una variabile d'ambiente:

export SEEDROUTER_API_KEY=YOUR_API_KEY
codex mcp add seedrouter --url https://api.seedrouter.ai/v1/mcp \
  --bearer-token-env-var SEEDROUTER_API_KEY

Codex salva il nome della variabile, non la chiave. Avvia Codex da una shell in cui SEEDROUTER_API_KEY è impostata, ad esempio esportandola nel file di profilo della shell.

VS Code

Aggiungi quanto segue a .vscode/mcp.json:

{
  "servers": {
    "seedrouter": {
      "type": "http",
      "url": "https://api.seedrouter.ai/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Qualsiasi altro client che supporta server remoti Streamable HTTP con un header Authorization personalizzato si configura allo stesso modo.

Strumenti

Strumento	Funzione	Addebito sul saldo
`list_models`	Elenca gli ID modello accettati da `submit_task`, ciascuno con il link alla relativa documentazione. `endpoint` facoltativo: `images` o `videos`.	No
`get_model_schema`	Restituisce il JSON Schema del corpo della richiesta di un modello. Le regole che JSON Schema non può esprimere, come i requisiti condizionali e i limiti tra campi, vengono applicate dall'API e descritte nella pagina di documentazione del modello.	No
`get_pricing`	Restituisce i prezzi di listino correnti di un modello in USD, ricavati dalle stesse tariffe aggiornate usate per la fatturazione, incluse le eventuali fasce tariffarie dei modelli.	No
`submit_task`	Invia un'attività: `model` più `input`, il corpo della richiesta descritto da `get_model_schema`. Restituisce un ID attività.	Sì, per ogni chiamata che crea un'attività
`get_task`	Restituisce lo stato e il risultato di un'attività. Il parametro facoltativo `wait_seconds` (0–50) attende sul server mentre l'attività è ancora in esecuzione.	No
`get_balance`	Restituisce il saldo residuo, in USD, dell'account a cui appartiene la chiave.	No

submit_task non è idempotente. Ripetere una chiamata crea e addebita una seconda attività, quindi controlla get_task, get_balance o lo storico delle attività prima di ripetere una chiamata di cui non hai ricevuto il risultato.

Flusso tipico

Chiama list_models con endpoint: "images".
Chiama get_model_schema per il modello scelto.
Se vuoi, chiama get_pricing per conoscere prima la tariffa.
Chiama submit_task con model e un input conforme allo schema.
Chiama get_task con wait_seconds: 50, ripetendo la chiamata finché status è processing, poi leggi output. Le attività Seedance indicano queued e running prima di succeeded.

La generazione è asincrona, esattamente come nell'API HTTP: submit_task restituisce una risposta non appena l'attività viene accettata. wait_seconds evita all'agente di eseguire il polling in un ciclo, ma un video lungo può comunque richiedere più chiamate a get_task. Se un controllo dello stato fallisce per un motivo temporaneo durante l'attesa, ad esempio una limitazione della frequenza delle richieste o un errore del server, get_task restituisce l'ultimo risultato processing anziché l'errore; chiamalo di nuovo.

Regole riprese dall'API HTTP

Immagini, video e audio di riferimento devono essere URL http(s) pubblici. Gli input in Base64 vengono rifiutati.
Quando l'API HTTP risponde, il corpo della risposta diventa il risultato dello strumento senza modifiche, con gli stessi codici di errore. Gli errori che si verificano prima che una richiesta raggiunga l'API, come un modello sconosciuto o argomenti dello strumento non validi, vengono restituiti come un semplice messaggio di errore. Una chiave rifiutata sull'endpoint MCP stesso produce uno stato HTTP 401.
Le attività fallite non vengono addebitate.
Per impostazione predefinita, un account può avere fino a 50 attività di immagine e video in esecuzione contemporaneamente. Gli invii aggiuntivi restituiscono HTTP 429 con il codice 30002 finché non terminano attività in corso; vedi Usare SeedRouter dagli agenti IA.
Gli ID modello e i parametri sono quelli nella documentazione di ciascun modello. Un modello compare in list_models quando è disponibile tramite l'API.
I modelli di testo non sono disponibili tramite MCP. Chiamali sugli endpoint di testo, oppure usali per eseguire un agente di programmazione come descritto in Agenti di programmazione su SeedRouter.

On this page