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

# Discord Agent Proxy 使用ドキュメント

> Discord Agent Proxy API guide - Ace Data Cloud

Discord Agent Proxy は**独立してデプロイ**されるサービスです。あなた自身の Discord アカウント認証情報を保管し、Discord との常駐接続を維持し、このアカウントの機能を **MCP** と **REST API** の 2 つのインターフェースを通じて公開することで、AI またはプログラムがあなたに代わって Discord を操作できるようにします。

コンテナ内には**いかなる AI モデルも含まれておらず**、実行のみを担当します——あなたの AI クライアント（Claude、Cursor など）または独自のプログラムが呼び出しを開始します。

```
AI クライアント  ──MCP /mcp──┐
                             ├─→ Discord Agent Proxy ──→ Discord
あなたのプログラム ──REST /api───┘      （あなたのアカウント認証情報を保管）
```

## ⚠️ 使用前に必ずお読みください

プログラムによる**個人アカウント**（self-bot）の自動操作は Discord の利用規約に違反しており、アカウントが BAN されるリスクがあります。これは本サービスの本質的な前提です。あなた自身のアカウント認証情報を提供し、リスクはご自身で負担してください。

**専用のサブアカウントを使用し、メインアカウントを使用しないことを強く推奨します。**

## サービスのデプロイ

[コンソール → アプリケーション](https://platform.acedata.cloud/console/applications) にアクセスし、Discord Agent Proxy を見つけてアプリケーションを作成します。作成後、まずサブスクリプションを有効化し、その後設定ページに入り Discord アカウント認証情報を入力してデプロイします。インスタンスリソースはプラットフォームによって自動的に設定されるため、スペックを選択する必要はありません。

デプロイを送信するとアプリケーション管理ページに移動します。Telegram、WeChat のデプロイと同じ「概要 / ログ / ドキュメント」レイアウトを使用します。「概要」にはインスタンスとサブスクリプションの状態が表示され、アカウント照会によって Discord が接続されているかを確認できます。コンテナが正常に稼働していても、アカウントが必ず接続済みであるとは限りません。

「概要」の Discord アカウントカードでは、次の 2 つの接続情報が提供されます。

| 項目 | 例 | 用途 |
| - | - | - |
| MCP 接続アドレス | `https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/mcp` | AI クライアントに設定 |
| アクセストークン | `V0p7kAWY...` | 認証用、以下を参照 |

### コンソールでインターフェースを確認・テストする

このアプリケーションの「ドキュメント」タブを開くと、全 14 個の REST 操作のリクエストパラメータ、レスポンス構造、および Shell、Python、JavaScript などの言語のサンプルを確認できます。インスタンスアドレスとアクセストークンは自動的に入力されます。トークンはデフォルトで非表示です。

`GET /api/whoami` を選択し、「テスト」をクリックすると、プロキシが接続しているアカウントを確認できます。メッセージの送信、編集、削除などの操作は実際の Discord アカウントに適用されるため、リクエスト内容を確認してからテストしてください。

「OpenAPI (JSON) をダウンロード」では、完全なインターフェース定義をエクスポートできます。ファイルにはインスタンスアドレスが含まれますが、アクセストークンは含まれません。Discord アカウント認証情報を変更する必要がある場合は、「概要」で「再デプロイ」を選択し、新しい認証情報を入力して送信してください。

### Discord アカウント認証情報の取得方法

1. パソコンのブラウザで Discord にログインします（[discord.com/app](https://discord.com/app)）
2. `F12` を押して開発者ツールを開き、**Network（ネットワーク）** パネルに切り替えます
3. Discord で任意のチャンネルをクリックし、リクエスト一覧を確認します
4. `discord.com/api` 宛ての任意のリクエストを開き、**Request Headers（リクエストヘッダー）** 内の `authorization` フィールドを見つけます
5. その値をコピーします

この認証情報はあなたのアカウントのログインセッションと同等です。**絶対に誰にも共有しないでください**。漏洩した場合は、Discord でパスワードを変更すれば直ちに無効化できます。

## 認証方法

`/health` と `/readyz` を除くすべてのインターフェースでは、**リクエストヘッダー**にアクセストークンを含める必要があります。

```
Authorization: Bearer <あなたのアクセストークン>
```

> **注意：本サービスはリクエストヘッダーによる認証のみを受け付け、`?token=xxx` のように URL の末尾にトークンを付加する方式はサポートしていません。** ブラウザで直接インターフェースアドレスを開くと `401 unauthorized` が返されますが、これは正常な動作であり、デプロイの失敗を意味するものではありません。プロセスが稼働しているかを確認したい場合は `/health` にアクセスしてください。Discord 接続がリクエストを処理できるか確認したい場合は `/readyz` にアクセスしてください。これら 2 つのプローブはいずれも認証不要です。プロキシアクセストークンが未設定の場合、保護されたインターフェースは `503` を返し、匿名で公開されることはありません。

## サービス状態の確認

```bash theme={null}
curl https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/health
curl https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/readyz
```

`/health` は HTTP プロセスが稼働していることのみを示します。

```json theme={null}
{ "status": "ok" }
```

`/readyz` は Discord Gateway が利用可能かどうかを示します。接続が正常な場合は HTTP 200 を返します。

```json theme={null}
{ "status": "ready", "gateway_ready": true }
```

接続中、認証情報が無効、または接続が中断された場合、Kubernetes による Pod への直接プローブは HTTP 503 を返し、インスタンスバックエンドによって自動的に再試行されます。このとき Pod は一時的にパブリック Service から除外されるため、インスタンスドメインを通じてこの診断 JSON を読み取れることは保証されません。コンソールで Deployment の状態を確認し、Ready に復帰してから MCP / REST を呼び出してください。

## AI クライアントでの使用（MCP）

Claude Code を例にします。

```bash theme={null}
claude mcp add --transport http discord \
  https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/mcp \
  --header "Authorization: Bearer <あなたのアクセストークン>"
```

Cursor など静的リクエストヘッダーをサポートするクライアントでは、現在のドキュメントに従って Streamable HTTP アドレスを設定してください。以下の構造を受け付けるクライアントでは使用できます。

```json theme={null}
{
  "mcpServers": {
    "discord": {
      "type": "http",
      "url": "https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer <あなたのアクセストークン>"
      }
    }
  }
}
```

これはすべての MCP クライアントに共通する設定形式ではありません。Claude Desktop / Claude.ai のリモートコネクタはクラウド側で確立され、ローカルの `claude_desktop_config.json` にある HTTP リクエストヘッダーを読み取りません。現在、静的な Bearer リクエストヘッダーが必要な場合は、Claude Code またはこの機能を明示的にサポートするクライアントを使用してください。

設定完了後は、自然言語で直接 AI に Discord の操作を指示できます。例：

> 「プロジェクトディスカッション」チャンネルに新しいメッセージがあるか確認して、誰かがリリース日時について質問していたら、今週金曜日だと返信して。

### 利用可能なツール

| MCP ツール | 役割 |
| - | - |
| `discord_whoami` | 現在代理しているアカウントを確認する |
| `discord_list_guilds` | アカウントが参加しているすべてのサーバーを一覧表示する |
| `discord_list_channels` | 特定のサーバー配下のチャンネルを一覧表示する |
| `discord_create_text_channel` | テキストチャンネルを作成する |
| `discord_list_members` | サーバーメンバーを一覧表示する |
| `discord_send_message` | メッセージを送信する（特定のメッセージへの返信を指定可能） |
| `discord_read_messages` | チャンネルの最近のメッセージを読み取る |
| `discord_edit_message` | 自分が送信したメッセージを編集する |
| `discord_delete_message` | メッセージを削除する |
| `discord_search_messages` | チャンネル内でメッセージを検索する |
| `discord_add_reaction` | メッセージに絵文字リアクションを追加する |
| `discord_pin_message` | メッセージをピン留めする |
| `discord_create_dm` | 1対1のダイレクトメッセージを開始し、チャンネル ID を返す |
| `discord_send_dm` | 特定のユーザーにダイレクトメッセージを送る |

## プログラムでの使用（REST API）

すべての REST エンドポイントは `/api` 配下にあり、レスポンスボディは統一して `{"data": ...}`、エラー時は `{"error": "..."}` となります。

### 現在のアカウントを確認する

```bash theme={null}
curl https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/api/whoami \
  -H "Authorization: Bearer <你的访问令牌>"
```

### メッセージを送信する

```bash theme={null}
curl -X POST https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/api/messages \
  -H "Authorization: Bearer <你的访问令牌>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <本次发送的唯一操作 ID>" \
  -d '{"channel_id": "1234567890", "content": "你好"}'
```

同じ送信を再試行する際は同じ `Idempotency-Key` を再利用してください。プロセスは初回の結果を返し、重複して送信しません。インスタンスの再起動時には最大 5,000 件のメモリ上の重複排除記録が消去されるため、呼び出し元は長期的な配信状態を引き続き自ら追跡する必要があります。

オプションのパラメーター `reply_to` は、指定したメッセージへの返信に使用します。

```json theme={null}
{ "channel_id": "1234567890", "content": "收到", "reply_to": "9876543210" }
```

### メッセージを読み取る

```bash theme={null}
curl "https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/api/channels/1234567890/messages?limit=20" \
  -H "Authorization: Bearer <你的访问令牌>"
```

### 完全なエンドポイント一覧

| メソッドとパス | パラメーター | 役割 |
| - | - | - |
| `GET /api/whoami` | — | 現在代理しているアカウント情報 |
| `GET /api/guilds` | — | アカウントが参加しているサーバー一覧 |
| `GET /api/guilds/{guild_id}/channels` | — | サーバー配下のチャンネル一覧 |
| `POST /api/guilds/{guild_id}/channels` | `{name}` | テキストチャンネルを作成する |
| `GET /api/guilds/{guild_id}/members` | `?limit=`（デフォルト 100） | サーバーメンバー一覧 |
| `POST /api/messages` | `{channel_id, content, reply_to?}` | メッセージを送信する |
| `GET /api/channels/{channel_id}/messages` | `?limit=`（デフォルト 50、上限 100） | 最近のメッセージを読み取る |
| `GET /api/channels/{channel_id}/messages/search` | `?q=`（必須）`&limit=`（デフォルト 25） | メッセージを検索する |
| `PATCH /api/channels/{channel_id}/messages/{message_id}` | `{content}` | メッセージを編集する |
| `DELETE /api/channels/{channel_id}/messages/{message_id}` | — | メッセージを削除する |
| `POST /api/channels/{channel_id}/messages/{message_id}/reactions` | `{emoji}` | 絵文字リアクションを追加する |
| `POST /api/channels/{channel_id}/messages/{message_id}/pin` | — | メッセージをピン留めする |
| `POST /api/dms` | `{recipient_id}` | ダイレクトメッセージを開始し、チャンネル ID を返す |
| `POST /api/dms/send` | `{recipient_id, content}` | ダイレクトメッセージを送信する |

### チャンネル ID とユーザー ID の取得方法

Discord クライアントで **ユーザー設定 → 詳細設定** を順に開き、**開発者モード**を有効にします。その後、任意のチャンネルまたはユーザーを右クリックすると、メニューに「ID をコピー」が表示されます。

`GET /api/guilds` および `GET /api/guilds/{guild_id}/channels` を直接呼び出して列挙することもできます。

## よくある質問

**`401 unauthorized` が返される**

アクセストークンが正しくないか、`?token=` の方法で渡されています。トークンがリクエストヘッダー `Authorization: Bearer &lt;トークン>` を通じて渡されており、コンソールに表示されているものと一致していることを確認してください。

**`503` が返される**

Discord との接続がまだ確立されていません。まず `/readyz` にアクセスして `gateway_ready` を確認してください。長時間 `false` の場合は、アカウント認証情報が無効になっていることが多いため、再取得して再デプロイしてください。

**`403` または `404` が返される**

アカウント自体に対応する権限がない（たとえば、そのサーバーに参加していない、そのチャンネルで発言する権限がない）か、ID が間違っています。この種のエラーは Discord からのものであり、代理サービスの問題ではありません。

**`429` が返される**

Discord のレート制限に達しました。レスポンス内の `retry_after` フィールドに推奨される待機秒数が示されます。呼び出し頻度を下げてください。

**メッセージ送信後にアカウントが凍結された**

前述のとおり、個人アカウントの自動操作は Discord の利用規約に違反します。専用のサブアカウントを使用し、操作頻度を制御して、一斉送信などのセンシティブな行為を避けてください。

## 検証範囲

2026 年 8 月 1 日の本番 smoke では、専用アカウントを使用してアカウント、サーバー、チャンネル、メンバー、メッセージの読み取り、検索、送信、編集、リアクション、削除を検証しました。自動テストは認証、パラメーター検証、エラーマッピング、および現在の依存ライブラリのシグネチャをカバーしています。worker または chart の変更後には、引き続き smoke を再実行する必要があり、過去の検証を継続的な可用性の証明とみなすことはできません。


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