Discord Agent Proxy User Documentation

Discord Agent Proxy is a self-deployed service: it stores your own Discord account credentials, maintains a persistent connection with Discord, and exposes the capabilities of this account through MCP and REST API interfaces, allowing AI or programs to operate Discord on your behalf.

The container does not contain any AI models; it is only responsible for execution—initiated by your AI client (Claude, Cursor, etc.) or your own program.

AI Client ──MCP /mcp──┐
                    ├─→ Discord Agent Proxy ──→ Discord
Your Program ──REST /api───┘      (stores your account credentials)

¶ ⚠️ Must Read Before Use

Automating operations on a personal account (self-bot) violates Discord's terms of service, and there is a risk of account suspension. This is an inherent premise of this service: you provide your own account credentials and assume the risk.

It is strongly recommended to use a dedicated secondary account, do not use your main account.

¶ Deploying the Service

Go to Console → Applications, find Discord Agent Proxy, and create an application. After creation, go to the configuration page, enter your Discord account credentials, and deploy.

Once deployment is complete, the configuration page will display two pieces of information:

Item	Example	Purpose
MCP Access URL	`https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/mcp`	Configure in AI client
Access Token	`V0p7kAWY...`	For authentication, see below

¶ How to Obtain Discord Account Credentials

Log in to Discord in a web browser (discord.com/app)
Press F12 to open the developer tools, switch to the Network panel
Click on any channel in Discord and observe the request list
Open any request sent to discord.com/api, and find the authorization field in Request Headers
Copy its value

This string of credentials is equivalent to your account's login state, do not share it with anyone. If leaked, changing the password in Discord will immediately invalidate it.

¶ Authentication Method

All interfaces, except for /health and /readyz, require the access token to be included in the request headers:

Authorization: Bearer <your access token>

Note: This service only accepts header-based authentication and does not support appending tokens in the URL like ?token=xxx. Directly opening the interface address in a browser will return 401 unauthorized, which is normal and does not indicate deployment failure. To check if the process is alive, visit /health; to check if the Discord connection can handle requests, visit /readyz. These two probes do not require authentication. When the proxy access token is not configured, protected interfaces return 503 and will not be anonymously accessible.

¶ Check Service Status

curl https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/health
curl https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/readyz

/health only indicates that the HTTP process is alive:

{ "status": "ok" }

/readyz indicates whether the Discord Gateway is available. When the connection is normal, it returns HTTP 200:

{ "status": "ready", "gateway_ready": true }

When the connection is ongoing, credentials are invalid, or the connection is interrupted, Kubernetes's direct probe of the Pod returns HTTP 503, and the instance backend automatically retries. At this time, the Pod will be temporarily removed from the public Service, so it cannot be guaranteed that this diagnostic JSON can be read through the instance domain name; please check the Deployment status in the console and call MCP / REST again after it returns to Ready.

¶ Using in AI Client (MCP)

For example, using Claude Code:

claude mcp add --transport http discord \
  https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/mcp \
  --header "Authorization: Bearer <your access token>"

For clients like Cursor that support static request headers, please configure the Streamable HTTP address according to their current documentation. Clients that accept the following structure can be used:

{
  "mcpServers": {
    "discord": {
      "type": "http",
      "url": "https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/mcp",
      "headers": {
        "Authorization": "Bearer <your access token>"
      }
    }
  }
}

This is not a universal configuration format for all MCP clients. The remote connector for Claude Desktop / Claude.ai is established by the cloud and does not read any HTTP request headers from the local claude_desktop_config.json; currently, if a static Bearer request header is needed, please use Claude Code or a client that explicitly supports this capability.

Once configured, you can directly instruct the AI to operate Discord using natural language, for example:

Check if I have new messages in the "Project Discussion" channel, and if someone asks about the release date, help me reply that it's this Friday.

¶ Available Tools

MCP Tool	Function
`discord_whoami`	View which account the proxy is currently using
`discord_list_guilds`	List all servers the account has joined
`discord_list_channels`	List channels under a specific server
`discord_create_text_channel`	Create a text channel
`discord_list_members`	List server members
`discord_send_message`	Send a message (can specify a reply to a specific message)
`discord_read_messages`	Read recent messages in a channel
`discord_edit_message`	Edit a message sent by yourself
`discord_delete_message`	Delete a message
`discord_search_messages`	Search for messages in a channel
`discord_add_reaction`	Add a reaction to a message
`discord_pin_message`	Pin a message
`discord_create_dm`	Start a one-on-one chat, returns channel ID
`discord_send_dm`	Send a private message to a user

¶ Using in Program (REST API)

All REST interfaces are mounted under /api, with the response body uniformly as {"data": ...}, and in case of an error as {"error": "..."}.

¶ View Current Account

curl https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/api/whoami \
  -H "Authorization: Bearer <your access token>"

¶ Send Message

curl -X POST https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/api/messages \
  -H "Authorization: Bearer <your access token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <unique operation ID for this send>" \
  -d '{"channel_id": "1234567890", "content": "Hello"}'

Retrying the same send with the same Idempotency-Key will return the first result without resending. Restarting the instance will clear up to 5,000 records of memory deduplication, so the caller still needs to track the long-term delivery status themselves.

The optional parameter reply_to is used to reply to a specified message:

{ "channel_id": "1234567890", "content": "Received", "reply_to": "9876543210" }

¶ Read Messages

curl "https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud/api/channels/1234567890/messages?limit=20" \
  -H "Authorization: Bearer <your access token>"

¶ Complete API List

Method and Path	Parameters	Purpose
`GET /api/whoami`	—	Current proxy account information
`GET /api/guilds`	—	List of servers the account has joined
`GET /api/guilds/{guild_id}/channels`	—	List of channels under the server
`POST /api/guilds/{guild_id}/channels`	`{name}`	Create text channel
`GET /api/guilds/{guild_id}/members`	`?limit=` (default 100)	List of server members
`POST /api/messages`	`{channel_id, content, reply_to?}`	Send message
`GET /api/channels/{channel_id}/messages`	`?limit=` (default 50, max 100)	Read recent messages
`GET /api/channels/{channel_id}/messages/search`	`?q=` (required) `&limit=` (default 25)	Search messages
`PATCH /api/channels/{channel_id}/messages/{message_id}`	`{content}`	Edit message
`DELETE /api/channels/{channel_id}/messages/{message_id}`	—	Delete message
`POST /api/channels/{channel_id}/messages/{message_id}/reactions`	`{emoji}`	Add reaction
`POST /api/channels/{channel_id}/messages/{message_id}/pin`	—	Pin message
`POST /api/dms`	`{recipient_id}`	Start private chat, return channel ID
`POST /api/dms/send`	`{recipient_id, content}`	Send private message

¶ How to Get Channel ID and User ID

In the Discord client, open User Settings → Advanced Settings, and enable Developer Mode. Then right-click on any channel or user, and the menu will show "Copy ID".

You can also directly call GET /api/guilds and GET /api/guilds/{guild_id}/channels to enumerate.

¶ Common Issues

Returns 401 unauthorized

The access token is incorrect, or it was passed using ?token=. Please ensure the token is passed through the request header Authorization: Bearer <token> and matches what is displayed in the console.

Returns 503

The connection to Discord has not yet been established. First, access /readyz to check gateway_ready. If it remains false for a long time, it is likely due to invalid account credentials; please re-obtain and redeploy.

Returns 403 or 404

The account itself does not have the corresponding permissions (e.g., not in the server, no permission to speak in that channel), or the ID was entered incorrectly. These errors come from Discord, not from the proxy service.

Returns 429

Triggered Discord's rate limit; the retry_after field in the response gives the suggested wait time in seconds. Please reduce the call frequency.

Account banned after sending messages

As mentioned earlier, automating personal account operations violates Discord's Terms of Service. Please use a dedicated account and control the operation frequency, avoiding mass sending and other sensitive behaviors.

¶ Validation Scope

On August 1, 2026, production smoke tests validated account, server, channel, member, read messages, search, send, edit, respond, and delete using a dedicated account. Automated tests cover authentication, parameter validation, error mapping, and current dependency library signatures; smoke tests should still be re-executed after worker or chart changes, and historical validation should not be considered proof of ongoing availability.