Discord Channels & Messages
Run a Discord server's chat from a bot: read channel history, search a guild's messages, reply in place with message_reference, react, pin-check and spin off threads, or open a DM with a member. Built for community managers who answer the same questions every day.
Connect this API to an AI agent Browse all specs
What you can do with Discord Channels & Messages via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /users/@me |
getBotUser | Get the bot's own user profile (id, username) |
| GET | /users/@me/guilds |
listBotGuilds | List the servers (guilds) the bot has joined |
| GET | /guilds/{guild_id}/channels |
listGuildChannels | List the channels in a server |
| GET | /guilds/{guild_id}/threads/active |
listActiveGuildThreads | List the active threads in a server |
| GET | /channels/{channel_id} |
getChannel | Get a channel or thread by id |
| GET | /channels/{channel_id}/messages |
listChannelMessages | Read recent messages in a channel (before/after/around a message id) |
| POST | /channels/{channel_id}/messages |
sendChannelMessage | Post a message (or reply to one) in a channel |
| GET | /channels/{channel_id}/messages/{message_id} |
getChannelMessage | Get one message from a channel |
| PATCH | /channels/{channel_id}/messages/{message_id} |
editChannelMessage | Edit a message the bot sent |
| GET | /channels/{channel_id}/messages/pins |
listPinnedMessages | List the pinned messages in a channel |
| GET | /guilds/{guild_id}/messages/search |
searchGuildMessages | Search a server's messages by text, author or channel |
| PUT | /channels/{channel_id}/messages/{message_id}/reactions/{emoji_name}/@me |
addReaction | React to a message with an emoji |
| POST | /channels/{channel_id}/messages/{message_id}/threads |
startThreadFromMessage | Start a thread from a message |
| POST | /users/@me/channels |
openDirectMessage | Open a direct-message channel with a user |
Authentication
BotToken
API key — sent as the Authorization header
Discord bot token, sent as Authorization: Bot <token>.
How to get a credential
- Open the Discord Developer Portal (https://discord.com/developers/applications) and create an application.
- Go to Bot, click Reset Token and copy the token (it is shown once).
- Under Privileged Gateway Intents, turn on Message Content Intent if the agent must read message text.
- Go to OAuth2 > URL Generator, tick the
botscope and the permissions below, open the generated URL and add the bot to your server. - Store the value as
Bot <token>(the word Bot, a space, then the token).
Permissions used
| Bot permission | Operations |
|---|---|
| View Channels | getBotUser, listBotGuilds, listGuildChannels, getChannel, listActiveGuildThreads |
| Read Message History | listChannelMessages, getChannelMessage, listPinnedMessages, searchGuildMessages |
| Send Messages | sendChannelMessage, editChannelMessage, openDirectMessage |
| Add Reactions | addReaction |
| Create Public Threads | startThreadFromMessage |
Common errors
- 401 Unauthorized: the token is wrong or missing the
Botprefix. Reset it and storeBot <token>. - 403 Missing Access / Missing Permissions (50001 / 50013): the bot is not in that server or lacks the permission in that channel. Re-invite it with the permissions above or fix the channel overrides.
- 400 Invalid Form Body (50035): a field is wrong, e.g. an empty message or content over 2000 characters.
- 429 Too Many Requests: rate limited. Wait
retry_afterseconds from the response, then retry.
Save it in VX Agents as an API key credential for this spec; it is sent on every call.
Usage guide
Setup
- Credential: a Discord bot token stored as
Bot <token>(with theBotprefix). Invite the bot to the server with View Channels, Read Message History, Send Messages, Add Reactions and Create Public Threads. Turn on the Message Content intent, or messagecontentcomes back empty. - Worth pinning:
guild_id(the server) and thechannel_idof the support or announcements channel. Right-click > Copy ID in Discord (Developer Mode on) shows them.
Answer questions in a channel
listBotGuilds→ pick the server, thenlistGuildChannelsto find the channel (type0 = text, 5 = announcement, 15 = forum).listChannelMessageswithlimit(max 100) to read the latest messages; page back withbefore=<oldest message id>.searchGuildMessagesto find earlier answers (content,author_id,channel_id). If it returns 202, the index is still building: waitretry_afterseconds and try again.- Show the user the draft reply, then
sendChannelMessagewithcontentandmessage_reference.message_idto reply in place. Useallowed_mentions: {"parse": []}unless the user wants to ping people. - Long discussion?
startThreadFromMessagewith aname, then post in the thread with its id aschannel_id. addReaction(URL-encode the emoji, e.g.%E2%9C%85; custom emoji asname:id) to mark a question handled.
Good to know
- Ask the user before calling
sendChannelMessage,editChannelMessage,openDirectMessageorstartThreadFromMessage: everyone in the channel sees them. DMs fail with 50007 when the user blocks DMs from server members. - Ids are snowflakes: send them as strings. Timestamps are ISO 8601 UTC.
contentmax 2000 characters, up to 10 embeds.editChannelMessageonly works on the bot's own messages.listPinnedMessagesuses the current/messages/pinsendpoint (returnsitemsandhas_more; page withbefore).- Rate limits are per route: on 429, wait
retry_afterseconds. - Source: Discord API reference (https://docs.discord.com/developers/resources/message), checked 2026-10-16.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Discord Channels & Messages” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.