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

# MCP-Limits und Fehler

> Die Anfrage- und Tool-Limits des MCP-Servers von Square Cloud pro Plan, wie TOOL_RATE_LIMITED aussieht und was bei jedem Fehler zu tun ist, den ein Client erhalten kann.

## Limits

Die Limits gelten pro Konto und werden von allen MCP-Verbindungen des Kontos geteilt. Jede Ebene greift zusätzlich zur vorherigen:

1. **Anfragen an den MCP-Server.** Bis zu 60 pro Minute und Konto, oder das [API-Rate-Limit](https://docs.squarecloud.app/de/api-reference/limitations-and-restrictions.md#api-limits) deines Plans, falls es niedriger ist. Sie zählen getrennt von deinen API-Aufrufen, sodass ein sehr aktiver Agent nie deine anderen Integrationen blockiert. Darüber antworten Anfragen 60 Sekunden lang mit `429 RATE_LIMITED`.
2. **Ein in der API gesperrtes Konto ist auch hier gesperrt.** Solange das Konto über seinem API-Rate-Limit liegt, antwortet auch der MCP-Server mit `429 RATE_LIMITED`.
3. **Das Tool-Budget:** Tool-Aufrufe pro Minute, die Hälfte der API-Rate deines Plans und höchstens 60, da ein Tool-Aufruf viel mehr Arbeit macht als eine Anfrage.
4. **Limits pro Tool** für die Tools, die in deiner Anwendung lesen oder schreiben oder das Edge-Netzwerk abfragen.
5. **Die Limits pro Tool von Cubic**, dem KI-Assistenten von Square Cloud. Der MCP-Server und Cubic teilen sie sich, pro Konto.

Die Ebenen 3, 4 und 5 antworten mit einem Tool-Ergebnis `TOOL_RATE_LIMITED`, wie unten beschrieben.

| Tools | Aufrufe pro Minute | Pause nach Erreichen |
| - | - | - |
| Alle Tools, `HOBBY-1` | 15 | 60 s |
| Alle Tools, `HOBBY-2` | 30 | 60 s |
| Alle Tools, `STANDARD-4` und höher | 60 | 60 s |
| `list_files`, `read_file` | je 20 | 60 s |
| `search_files` | 3 | 120 s |
| `list_env_vars` | 10 | 60 s |
| `create_file`, `edit_file`, `patch_file`, `rename_file` | je 10 | 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` | je 5 | 60 s |
| `search_help_center` | 4 | 60 s |
| `list_help_center` | 2 | 60 s |
| `start_application`, `stop_application`, `restart_application` | je 10 | 120 s |

* **Jeder Tool-Aufruf zählt**, auch Aufrufe, die wegen einer Ressource oder eines von den Argumenten abhängigen Scopes abgelehnt werden (etwa `restart` bei `set_env_vars`).
* **Bei `HOBBY-1`** zum Beispiel geht der MCP-Server nie über 15 Tool-Aufrufe pro Minute hinaus, und deine CLI, SDKs und Bots behalten die gesamte API-Rate des Plans.
* **Commits teilen sich ein Tempo** mit der API, der CLI und dem Dashboard: einer alle 2 Sekunden pro Konto und einer alle 5 Sekunden pro Anwendung. Früher antwortet `commit_application` mit `RATE_LIMITED`.

### Zips und Dateien

* **Zip:** `upload_application` und `commit_application` nehmen ein Zip bis 1 MB an, als base64 gesendet, und bis 100 MB entpackt. Das Dashboard und die [CLI](https://docs.squarecloud.app/de/cli-reference/deploy.md) nehmen Zips bis 100 MB an: nutze sie für ein größeres Projekt.
* **Dateien:** `commit_application` nimmt bis zu 50 Textdateien an, je bis 128 KB und zusammen bis 512 KB. Versteckte Dateien, `.env`-Dateien, private Schlüssel und die Konfigurationsdatei sind ausgeschlossen; die Konfigurationsdatei änderst du mit `edit_config_file`.

### TOOL\_RATE\_LIMITED

Ein Tool über einem Limit läuft nicht. Die Antwort ist ein reguläres Tool-Ergebnis mit `isError: true`, kein HTTP-Fehler, sodass die Verbindung weiter funktioniert:

```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."
}
```

Ist das Tool-Budget das erreichte Limit, sagt die `summary` `too many AI actions in a short time`, und alle Tools warten; sonst wartet nur dieses Tool. Ruft der Client dasselbe Tool erneut auf, solange es noch begrenzt ist, antwortet diese zweite Ablehnung in Folge stattdessen mit `TOOL_EXECUTION_FAILED`. Das sagt dem Client, dass er aufhören soll, und dir, dass du ein paar Minuten warten oder das Dashboard nutzen sollst.

## Fehler

### HTTP-Fehler

Diese kommen als HTTP-Status der Anfrage zurück, mit einem JSON-Body, der `code` enthält.

| Status | Code | Wann | Was tun |
| - | - | - | - |
| `401` | `ACCESS_DENIED` | Kein Schlüssel, oder der Schlüssel ist falsch, widerrufen oder abgelaufen. Die Antwort enthält die OAuth-Challenge, sodass Claude und ChatGPT dich bitten, dich erneut anzumelden. | Verbinde den Client neu oder erstelle einen neuen [API-Schlüssel](https://docs.squarecloud.app/de/mcp/connect.md#einen-api-schlüssel-erstellen). |
| `403` | `ACCESS_DENIED` | Statt eines API-Schlüssels wurde ein Sitzungstoken des Dashboards gesendet. | Verbinde dich per OAuth oder mit einem API-Schlüssel. |
| `403` | `MISSING_SCOPE` | Dem Schlüssel fehlt der Scope `mcp`. Kommt auch, wenn ein Schlüssel von Claude oder ChatGPT auf der REST-API verwendet wird. | Erstelle einen Schlüssel mit `mcp`. |
| `403` | `UPGRADE_REQUIRED` | Das Konto hat keinen aktiven Plan. | Schließe einen [Plan](https://docs.squarecloud.app/de/platform/plans.md) ab oder verlängere ihn. |
| `421` | `WRONG_HOST` | Die Anfrage ging an eine andere Square Cloud-Adresse, etwa `api.squarecloud.app`. | Nutze `https://mcp.squarecloud.app/mcp`. |
| `429` | `RATE_LIMITED` | Das Anfragelimit des MCP-Servers wurde überschritten, oder das Konto ist durch sein API-Rate-Limit gesperrt. | Warte eine Minute und bremse den Client. |
| `400` | JSON-RPC-Fehler | Eine nicht unterstützte Protokollversion (`-32022`, mit der Liste der unterstützten Versionen) oder eine fehlerhafte Anfrage. | Aktualisiere den Client. |

### Beim Verbinden

| Was du siehst | Warum | Was tun |
| - | - | - |
| `UNKNOWN_CLIENT` oder `INVALID_REDIRECT_URI` auf einer Seite von `mcp.squarecloud.app` | Nur Claude mit seiner veröffentlichten Identität und ChatGPT melden sich per OAuth an. | Wähle in Claude **Use Claude's published identity**. Verbinde andere Clients mit einem [API-Schlüssel](https://docs.squarecloud.app/de/mcp/connect.md#einen-api-schlüssel-erstellen). |
| `The account is at its API key limit` | Das Konto hat bereits 10 Schlüssel. | Widerrufe einen Schlüssel in deinen [Sicherheitseinstellungen des Kontos](https://squarecloud.app/de/account/security) und verbinde erneut. |
| Die Zustimmungsseite meldet, dass die Anfrage abgelaufen ist | Sie gilt 10 Minuten. | Starte die Verbindung im Client neu. |

### Tool-Ergebnisse

Diese kommen in einem Tool-Ergebnis als `code` zurück, neben einer `summary`, die der Client liest.

| Code | Bedeutung | Was tun |
| - | - | - |
| `SNAPSHOT_NOT_READY` | Der [Sicherheits-Snapshot](https://docs.squarecloud.app/de/mcp/permissions-and-safety.md#löschungen-und-wiederherstellungen) vor einer Löschung, einer Wiederherstellung oder einem `commit_application` mit `snapshot` wird noch erstellt. Nichts ist gelaufen. | Der Client versucht es in etwa 2 Minuten mit denselben Argumenten erneut. |
| `MISSING_SCOPE` | Dieser Aufruf braucht einen Scope, den der Schlüssel nicht hat, etwa `databases:read` für die Metriken einer Datenbank. | Nutze einen Schlüssel mit diesem Scope. |
| `RESOURCE_NOT_ALLOWED` | Der Schlüssel ist auf andere Anwendungen und Datenbanken beschränkt, oder keine der abgedeckten Ressourcen trägt diesen Namen. | Nutze einen Schlüssel, der die Ressource abdeckt. |
| `TOOL_RATE_LIMITED` | Ein [Limit](#limits) wurde erreicht. | Warte die Zeit aus der `summary` ab. |
| `TOOL_EXECUTION_FAILED` | Dasselbe Tool hat zweimal in Folge ein Limit erreicht, oder es ist fehlgeschlagen. | Warte ein paar Minuten oder nutze das Dashboard. |
| `APP_NOT_FOUND`, `DATABASE_NOT_FOUND` | Keine Anwendung oder Datenbank passt zum Namen oder zur ID. | Bitte den Client, sie zuerst aufzulisten. |
| `INVALID_ZIP` | `zip` ist kein base64, oder das Zip ist beschädigt. | Erstelle das Zip neu und sende es erneut. |
| `ZIP_TOO_LARGE` | Das Zip ist größer als 1 MB, oder entpackt größer als 100 MB. | Sende ein kleineres Zip, oder deploye das Projekt mit der [CLI](https://docs.squarecloud.app/de/cli-reference/deploy.md) oder über das Dashboard. |
| `MISSING_MANIFEST` | Das Zip von `upload_application` hat keine `squarecloud.app` im Stammverzeichnis, oft weil das Projekt in einem Ordner des Zips liegt. | Packe den Inhalt des Ordners, mit `squarecloud.app` (`DISPLAY_NAME`, `MAIN`, `MEMORY`, `VERSION`) im Stammverzeichnis. |
| `BLOCKED_PATH` | Ein Pfad zeigt aus dem Zielordner heraus, oder das Zip enthält Dateien im Ordner `.squarecloud`, der zur Plattform gehört und nicht geändert werden kann. In `files` werden außerdem versteckte Dateien, `.env`-Dateien, private Schlüssel und die Konfigurationsdatei abgelehnt. | Entferne diese Dateien und sende erneut. |
| `INVALID_PATH` | `path` ist kein Ordner, in den ein Commit schreiben kann. | Wähle einen anderen Ordner der Anwendung. |
| `RESTORE_IN_PROGRESS` | Auf der Anwendung läuft gerade eine Wiederherstellung. | Warte, bis sie fertig ist, und versuche es erneut. |
| `RATE_LIMITED` | Ein Commit kam zu kurz nach dem vorherigen. | Warte ein paar Sekunden und versuche es erneut. |
| `COMMIT_FAILED` | Die neue Version konnte nicht in die Anwendung geschrieben werden. | Versuche es erneut, oder lade sie über das Dashboard hoch. |

Ein Tool, das dein Schlüssel nicht nutzen kann, oder eines, das nicht existiert, antwortet mit dem JSON-RPC-Fehler `-32602` `Unknown tool`. Prüfe die [Scopes](https://docs.squarecloud.app/de/mcp/permissions-and-safety.md#scopes) des Schlüssels. Andere Codes kommen vom Tool selbst, und die `summary` erklärt sie.


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