> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Limiti ed errori dell'MCP

> I limiti di richieste e di tool del server MCP di Square Cloud per piano, com'è fatto TOOL_RATE_LIMITED e cosa fare per ogni errore che un client può ricevere.

## Limiti

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

1. **Le richieste al server MCP.** Fino a 60 al minuto per account, oppure il [rate limit dell'API](https://docs.squarecloud.app/it/api-reference/limitations-and-restrictions.md#limiti-dellapi) 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.
2. **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`.
3. **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.
4. **Limiti per singolo tool** per i tool che leggono o scrivono dentro la tua applicazione o interrogano la rete edge.
5. **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 |
| `commit_application` | 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.
* **I commit condividono uno stesso ritmo** con l'API, la CLI e la dashboard: uno ogni 2 secondi per account e uno ogni 5 secondi per applicazione. Prima di allora, `commit_application` risponde `RATE_LIMITED`.

### Zip e file

* **Zip:** `upload_application` e `commit_application` accettano uno zip fino a 1 MB, inviato in base64, e fino a 100 MB una volta decompresso. La dashboard e la [CLI](https://docs.squarecloud.app/it/cli-reference/deploy.md) accettano zip fino a 100 MB: usale per un progetto più grande.
* **File:** `commit_application` accetta fino a 50 file di testo, fino a 128 KB ciascuno e 512 KB in totale. Non possono essere file nascosti, file `.env`, chiavi private né il file di configurazione, che si modifica con `edit_config_file`.

### 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:

```json theme={"system"}
{
  "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](https://docs.squarecloud.app/it/mcp/connect.md#crea-una-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](https://docs.squarecloud.app/it/platform/plans.md). |
| `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](https://docs.squarecloud.app/it/mcp/connect.md#crea-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](https://squarecloud.app/it/account/security) 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](https://docs.squarecloud.app/it/mcp/permissions-and-safety.md#eliminazioni-e-ripristini) fatto prima di un'eliminazione, di un ripristino o di un `commit_application` con `snapshot` è 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](#limiti). | 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. |
| `INVALID_ZIP` | `zip` non è in base64, oppure lo zip è danneggiato. | Ricrea lo zip e invialo di nuovo. |
| `ZIP_TOO_LARGE` | Lo zip supera 1 MB, o 100 MB una volta decompresso. | Invia uno zip più piccolo, oppure fai il deploy del progetto con la [CLI](https://docs.squarecloud.app/it/cli-reference/deploy.md) o dalla dashboard. |
| `MISSING_MANIFEST` | Lo zip di `upload_application` non ha `squarecloud.app` nella radice, spesso perché il progetto si trova dentro una cartella dello zip. | Comprimi il contenuto della cartella, con `squarecloud.app` (`DISPLAY_NAME`, `MAIN`, `MEMORY`, `VERSION`) nella radice. |
| `BLOCKED_PATH` | Un percorso punta fuori dalla cartella di destinazione, oppure lo zip ha file dentro la cartella `.squarecloud`, che appartiene alla piattaforma e non può essere modificata. In `files` vengono rifiutati anche i file nascosti, i file `.env`, le chiavi private e il file di configurazione. | Togli quei file e invia di nuovo. |
| `INVALID_PATH` | `path` non è una cartella in cui un commit può scrivere. | Scegli un'altra cartella dell'applicazione. |
| `RESTORE_IN_PROGRESS` | Sull'applicazione è in corso un ripristino. | Attendi che finisca e riprova. |
| `RATE_LIMITED` | Un commit è arrivato troppo presto dopo il precedente. | Attendi qualche secondo e riprova. |
| `COMMIT_FAILED` | Non è stato possibile scrivere la nuova versione nell'applicazione. | Riprova, oppure inviala dalla dashboard. |

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](https://docs.squarecloud.app/it/mcp/permissions-and-safety.md#scope) della chiave. Gli altri codici vengono dal tool stesso, e il `summary` li spiega.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.