> ## 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 の制限とエラー

> Square Cloud MCP サーバーのプラン別のリクエストとツールの制限、TOOL_RATE_LIMITED の内容、クライアントが受け取る各エラーへの対処法をまとめています。

## 制限

制限はアカウント単位で、そのアカウントのすべての MCP 接続で共有されます。各層は、前の層に重ねて適用されます:

1. **MCP サーバーへのリクエスト。** アカウントごとに 1 分あたり 60 回まで。プランの [API レート制限](https://docs.squarecloud.app/ja/api-reference/limitations-and-restrictions.md#api-の制限)のほうが低い場合は、その値までです。API 呼び出しとは別にカウントされるため、活発なエージェントがほかの連携をブロックすることはありません。超えると、60 秒間リクエストに `429 RATE_LIMITED` が返されます。
2. **API でブロックされたアカウントは、ここでもブロックされます。** アカウントが API レート制限を超えている間は、MCP サーバーも `429 RATE_LIMITED` を返します。
3. **ツールの呼び出し枠:** 1 分あたりのツール呼び出し数で、プランの API レートの半分、最大 60 回です。ツール呼び出しはリクエストよりはるかに多くの処理を行うためです。
4. **ツールごとの上限:** アプリケーション内で読み書きするツールや、エッジネットワークに問い合わせるツールに適用されます。
5. **Cubic のツールごとの制限:** Cubic は Square Cloud の AI アシスタントです。MCP と Cubic は、アカウント単位でこの制限を共有します。

第 3、4、5 層の制限に達すると、後述の `TOOL_RATE_LIMITED` のツール結果が返されます。

| ツール | 1 分あたりの呼び出し数 | 上限到達後の待機時間 |
| - | - | - |
| すべてのツール、`HOBBY-1` | 15 | 60 秒 |
| すべてのツール、`HOBBY-2` | 30 | 60 秒 |
| すべてのツール、`STANDARD-4` 以上 | 60 | 60 秒 |
| `list_files`、`read_file` | 各 20 | 60 秒 |
| `search_files` | 3 | 120 秒 |
| `list_env_vars` | 10 | 60 秒 |
| `create_file`、`edit_file`、`patch_file`、`rename_file` | 各 10 | 120 秒 |
| `edit_config_file` | 5 | 120 秒 |
| `commit_application` | 5 | 120 秒 |
| `delete_file` | 5 | 180 秒 |
| `get_application_logs` | 10 | 60 秒 |
| `get_application_status` | 20 | 60 秒 |
| `get_metrics_history` | 10 | 60 秒 |
| `get_network_analytics`、`get_network_errors`、`get_network_performance`、`get_network_logs` | 各 5 | 60 秒 |
| `search_help_center` | 4 | 60 秒 |
| `list_help_center` | 2 | 60 秒 |
| `start_application`、`stop_application`、`restart_application` | 各 10 | 120 秒 |

* **すべてのツール呼び出しがカウントされます。** リソースや、引数によって決まるスコープ（`set_env_vars` の `restart` など）を理由に拒否された呼び出しも含みます。
* **たとえば `HOBBY-1` では**、MCP が 1 分あたり 15 回を超えてツールを呼び出すことはなく、CLI、SDK、ボットはプランの API レートをすべて使えます。
* **コミットのペースは、API、CLI、ダッシュボードと共通です。** アカウントごとに 2 秒に 1 回、アプリケーションごとに 5 秒に 1 回までで、それより早いと `commit_application` は `RATE_LIMITED` を返します。

### zip とファイル

* **zip:** `upload_application` と `commit_application` は、base64 で送る最大 1 MB の zip を受け付けます。展開後のサイズは最大 100 MB です。ダッシュボードと [CLI](https://docs.squarecloud.app/ja/cli-reference/deploy.md) は最大 100 MB の zip を受け付けるので、より大きなプロジェクトにはそちらを使ってください。
* **ファイル:** `commit_application` は最大 50 個のテキストファイルを受け付けます。1 ファイルあたり最大 128 KB、合計で最大 512 KB です。隠しファイル、`.env` ファイル、秘密鍵、設定ファイルは送れません。設定ファイルは `edit_config_file` で変更します。

### TOOL\_RATE\_LIMITED

制限を超えたツールは実行されません。返されるのは HTTP エラーではなく `isError: true` が付いた通常のツール結果なので、接続はそのまま使えます:

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

達した制限がツールの呼び出し枠の場合、`summary` には `too many AI actions in a short time` と表示され、すべてのツールが待機します。それ以外の場合は、そのツールだけが待機します。制限中のツールをクライアントがもう一度呼び出すと、その 2 回連続の拒否には代わりに `TOOL_EXECUTION_FAILED` が返されます。これは、クライアントには停止を、あなたには数分待つかダッシュボードを使うよう伝えるものです。

## エラー

### HTTP エラー

これらはリクエストの HTTP ステータスとして、`code` を含む JSON ボディとともに返されます。

| ステータス | コード | 発生する状況 | 対処法 |
| - | - | - | - |
| `401` | `ACCESS_DENIED` | キーがない、またはキーが誤っている、失効している、期限切れです。レスポンスには OAuth チャレンジが含まれるため、Claude と ChatGPT は再度サインインを求めます。 | クライアントを再接続するか、新しい [API キー](https://docs.squarecloud.app/ja/mcp/connect.md#api-キーを作成する)を作成します。 |
| `403` | `ACCESS_DENIED` | API キーの代わりにダッシュボードのセッショントークンが送信されました。 | OAuth または API キーで接続します。 |
| `403` | `MISSING_SCOPE` | キーに `mcp` スコープがありません。Claude や ChatGPT のキーを REST API で使った場合にも返されます。 | `mcp` を持つキーを作成します。 |
| `403` | `UPGRADE_REQUIRED` | アカウントに有効なプランがありません。 | [プラン](https://docs.squarecloud.app/ja/platform/plans.md)を契約するか、更新します。 |
| `421` | `WRONG_HOST` | リクエストが `api.squarecloud.app` などほかの Square Cloud のアドレスに送られました。 | `https://mcp.squarecloud.app/mcp` を使います。 |
| `429` | `RATE_LIMITED` | MCP サーバーへのリクエスト制限を超えたか、アカウントが API レート制限でブロックされています。 | 1 分待ってから、クライアントのペースを落とします。 |
| `400` | JSON-RPC エラー | 対応していないプロトコルバージョン（`-32022`、対応バージョンの一覧付き）、または不正な形式のリクエストです。 | クライアントを更新します。 |

### 接続時

| 表示される内容 | 原因 | 対処法 |
| - | - | - |
| `mcp.squarecloud.app` のページに `UNKNOWN_CLIENT` または `INVALID_REDIRECT_URI` | OAuth でサインインできるのは、公開 ID を使う Claude と、ChatGPT だけです。 | Claude では **Use Claude's published identity** を選びます。ほかのクライアントでは [API キー](https://docs.squarecloud.app/ja/mcp/connect.md#api-キーを作成する)で接続します。 |
| `The account is at its API key limit` | アカウントがすでに 10 個のキーを持っています。 | [アカウントのセキュリティ設定](https://squarecloud.app/ja/account/security)でキーを 1 つ失効させ、もう一度接続します。 |
| 同意ページにリクエストの期限切れが表示される | 同意ページの有効期間は 10 分です。 | クライアントから接続をやり直します。 |

### ツールの結果

これらはツールの結果の中で、クライアントが読む `summary` と並んで `code` として返されます。

| コード | 意味 | 対処法 |
| - | - | - |
| `SNAPSHOT_NOT_READY` | 削除、復元、または `snapshot` を指定した `commit_application` の前に作成する[安全用スナップショット](https://docs.squarecloud.app/ja/mcp/permissions-and-safety.md#削除と復元)をまだ作成中です。何も実行されていません。 | クライアントが約 2 分後に同じ引数で再試行します。 |
| `MISSING_SCOPE` | この呼び出しには、キーにないスコープが必要です（データベースのメトリクスに対する `databases:read` など）。 | そのスコープを持つキーを使います。 |
| `RESOURCE_NOT_ALLOWED` | キーはほかのアプリケーションとデータベースに制限されているか、キーの対象にその名前のリソースがありません。 | そのリソースを対象とするキーを使います。 |
| `TOOL_RATE_LIMITED` | [制限](#制限)に達しました。 | `summary` に示された時間だけ待ちます。 |
| `TOOL_EXECUTION_FAILED` | 同じツールが 2 回連続で制限に達したか、ツールが失敗しました。 | 数分待つか、ダッシュボードを使います。 |
| `APP_NOT_FOUND`、`DATABASE_NOT_FOUND` | 名前または ID に一致するアプリケーションやデータベースがありません。 | 先に一覧を取得するよう、クライアントに頼みます。 |
| `INVALID_ZIP` | `zip` が base64 ではないか、zip が壊れています。 | zip を作り直して、もう一度送ります。 |
| `ZIP_TOO_LARGE` | zip が 1 MB を超えているか、展開後に 100 MB を超えます。 | より小さな zip を送るか、[CLI](https://docs.squarecloud.app/ja/cli-reference/deploy.md) またはダッシュボードからプロジェクトをデプロイします。 |
| `MISSING_MANIFEST` | `upload_application` の zip のルートに `squarecloud.app` がありません。多くの場合、プロジェクトが zip 内のフォルダーに入っているためです。 | `squarecloud.app`（`DISPLAY_NAME`、`MAIN`、`MEMORY`、`VERSION`）がルートに来るように、フォルダーの中身を圧縮します。 |
| `BLOCKED_PATH` | パスが送信先フォルダーの外を指しているか、zip に `.squarecloud` フォルダー内のファイルが含まれています。このフォルダーはプラットフォームのもので、変更できません。`files` では、隠しファイル、`.env` ファイル、秘密鍵、設定ファイルも拒否されます。 | それらのファイルを取り除いて、もう一度送ります。 |
| `INVALID_PATH` | `path` が、コミットで書き込めるフォルダーではありません。 | アプリケーションの別のフォルダーを選びます。 |
| `RESTORE_IN_PROGRESS` | アプリケーションで復元が進行中です。 | 完了するまで待ってから、もう一度試します。 |
| `RATE_LIMITED` | 前回のコミットから間を置かずに次のコミットが送られました。 | 数秒待ってから、もう一度試します。 |
| `COMMIT_FAILED` | 新しいバージョンをアプリケーションに書き込めませんでした。 | もう一度試すか、ダッシュボードから送ります。 |

キーで使えないツールや存在しないツールを呼び出すと、JSON-RPC エラー `-32602` `Unknown tool` が返されます。キーの[スコープ](https://docs.squarecloud.app/ja/mcp/permissions-and-safety.md#スコープ)を確認してください。その他のコードはツール自体から返され、`summary` で説明されます。


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