Limiti ed errori dell'MCP

Limiti

I limiti sono per account e condivisi da tutte le sue connessioni MCP. Ogni livello si aggiunge al precedente:

Le richieste al server MCP. Fino a 60 al minuto per account, oppure il rate limit dell’API del tuo piano se è più basso. Vengono contate a parte rispetto alle tue chiamate all’API, quindi un agente molto attivo non blocca mai le tue altre integrazioni. Oltre questo limite, le richieste rispondono 429 RATE_LIMITED per 60 secondi.
Un account bloccato sull’API è bloccato anche qui. Finché l’account supera il suo rate limit dell’API, anche il server MCP risponde 429 RATE_LIMITED.
Il budget dei tool: chiamate ai tool al minuto, pari alla metà del rate dell’API del tuo piano e al massimo 60, perché una chiamata a un tool fa molto più lavoro di una richiesta.
Limiti per singolo tool per i tool che leggono o scrivono dentro la tua applicazione o interrogano la rete edge.
I limiti per tool di Cubic, l’assistente AI di Square Cloud. L’MCP e Cubic li condividono, per account.

I livelli 3, 4 e 5 rispondono con un risultato del tool TOOL_RATE_LIMITED, descritto qui sotto.

Tool	Chiamate al minuto	Pausa una volta raggiunto
Tutti i tool, `HOBBY-1`	15	60 s
Tutti i tool, `HOBBY-2`	30	60 s
Tutti i tool, `STANDARD-4` e superiori	60	60 s
`list_files`, `read_file`	20 ciascuno	60 s
`search_files`	3	120 s
`list_env_vars`	10	60 s
`create_file`, `edit_file`, `patch_file`, `rename_file`	10 ciascuno	120 s
`edit_config_file`	5	120 s
`delete_file`	5	180 s
`get_application_logs`	10	60 s
`get_application_status`	20	60 s
`get_metrics_history`	10	60 s
`get_network_analytics`, `get_network_errors`, `get_network_performance`, `get_network_logs`	5 ciascuno	60 s
`search_help_center`	4	60 s
`list_help_center`	2	60 s
`start_application`, `stop_application`, `restart_application`	10 ciascuno	120 s

Ogni chiamata a un tool conta, incluse le chiamate rifiutate per una risorsa o per uno scope che dipende dagli argomenti (come restart su set_env_vars).
Su HOBBY-1, ad esempio, l’MCP non supera mai 15 chiamate ai tool al minuto, e la tua CLI, i tuoi SDK e i tuoi bot mantengono tutto il rate dell’API del piano.

TOOL_RATE_LIMITED

Un tool oltre un limite non viene eseguito. La risposta è un normale risultato del tool contrassegnato con isError: true, non un errore HTTP, quindi la connessione continua a funzionare:

{
  "ok": false,
  "code": "TOOL_RATE_LIMITED",
  "summary": "read_file did NOT run: this action is on a short safety cooldown. Continue with what you already have, and tell the user it can run again in about 60 seconds."
}

Quando il limite raggiunto è il budget dei tool, il riepilogo dice too many AI actions in a short time e tutti i tool restano in attesa; altrimenti attende solo quel tool. Se il client chiama di nuovo lo stesso tool mentre è ancora limitato, quel secondo rifiuto consecutivo risponde invece TOOL_EXECUTION_FAILED, che dice al client di fermarsi e a te di attendere qualche minuto o di usare la dashboard.

Errori

Errori HTTP

Questi errori arrivano come stato HTTP della richiesta, con un corpo JSON che contiene code.

Stato	Codice	Quando	Cosa fare
`401`	`ACCESS_DENIED`	Nessuna chiave, oppure la chiave è errata, revocata o scaduta. La risposta contiene la challenge OAuth, quindi Claude e ChatGPT ti chiedono di accedere di nuovo.	Ricollega il client, oppure crea una nuova chiave API.
`403`	`ACCESS_DENIED`	È stato inviato un token di sessione della dashboard invece di una chiave API.	Connettiti con OAuth o con una chiave API.
`403`	`MISSING_SCOPE`	La chiave non ha lo scope `mcp`. Restituito anche quando una chiave di Claude o ChatGPT viene usata sulla REST API.	Crea una chiave con `mcp`.
`403`	`UPGRADE_REQUIRED`	L’account non ha un piano attivo.	Sottoscrivi o rinnova un piano.
`421`	`WRONG_HOST`	La richiesta è andata a un altro indirizzo di Square Cloud, come `api.squarecloud.app`.	Usa `https://mcp.squarecloud.app/mcp`.
`429`	`RATE_LIMITED`	Superato il limite di richieste al server MCP, oppure l’account è bloccato dal suo rate limit dell’API.	Attendi un minuto e rallenta il client.
`400`	Errore JSON-RPC	Una versione del protocollo non supportata (`-32022`, con l’elenco di quelle supportate) o una richiesta malformata.	Aggiorna il client.

Durante la connessione

Cosa vedi	Perché	Cosa fare
`UNKNOWN_CLIENT` o `INVALID_REDIRECT_URI` su una pagina di `mcp.squarecloud.app`	Solo Claude, con la sua identità pubblicata, e ChatGPT accedono con OAuth.	In Claude, scegli Use Claude’s published identity. Negli altri client, connettiti con una chiave API.
`The account is at its API key limit`	L’account ha già 10 chiavi.	Revoca una chiave nelle impostazioni di sicurezza del tuo account e connettiti di nuovo.
La pagina di consenso dice che la richiesta è scaduta	La richiesta dura 10 minuti.	Avvia di nuovo la connessione dal client.

Risultati dei tool

Questi codici arrivano dentro un risultato del tool, come code, accanto a un summary che il client legge.

Codice	Significato	Cosa fare
`SNAPSHOT_NOT_READY`	Lo snapshot di sicurezza fatto prima di un’eliminazione o di un ripristino è ancora in fase di generazione. Non è stato eseguito nulla.	Il client riprova con gli stessi argomenti tra circa 2 minuti.
`MISSING_SCOPE`	Questa chiamata richiede uno scope che la chiave non ha, come `databases:read` per le metriche di un database.	Usa una chiave con quello scope.
`RESOURCE_NOT_ALLOWED`	La chiave è limitata ad altre applicazioni e database, oppure nessuna delle risorse che copre ha quel nome.	Usa una chiave che copra la risorsa.
`TOOL_RATE_LIMITED`	È stato raggiunto un limite.	Attendi il tempo indicato nel riepilogo.
`TOOL_EXECUTION_FAILED`	Lo stesso tool ha raggiunto un limite due volte di fila, oppure ha fallito.	Attendi qualche minuto o usa la dashboard.
`APP_NOT_FOUND`, `DATABASE_NOT_FOUND`	Nessuna applicazione o database corrisponde al nome o all’ID.	Chiedi al client di elencarli prima.

Un tool che la tua chiave non può usare, o che non esiste, risponde con l’errore JSON-RPC -32602 Unknown tool. Controlla gli scope della chiave. Gli altri codici vengono dal tool stesso, e il summary li spiega.

CLI

VS Code

MCP

SDKs

Limiti ed errori dell'MCP

Limiti

TOOL_RATE_LIMITED

Errori

Errori HTTP

Durante la connessione

Risultati dei tool

​Limiti

​TOOL_RATE_LIMITED

​Errori

​Errori HTTP

​Durante la connessione

​Risultati dei tool

Limiti

TOOL_RATE_LIMITED

Errori

Errori HTTP

Durante la connessione

Risultati dei tool