Discord
Use Discord with Mastra in two ways:
- Agent tools let an agent act in Discord servers, for example to send messages or manage channels.
- Agent chat lets people talk to your agent in Discord through bot messages and interactions such as slash commands and buttons.
Mastra Connect sets up both from one Discord bot and keeps its token on the Mastra platform. For agent chat, you can also manage the bot credentials yourself.
ConnectDirect link to Connect
Before you start, complete the Connect setup to install @mastra/connect and configure your platform project.
One discord connection provides both agent tools and agent chat. It uses a bot token, not a user OAuth token.
Create a Discord botDirect link to Create a Discord bot
- In the Discord Developer Portal, create an application.
- Open Bot, add a bot, then select Reset Token and copy the bot token.
- For agent chat, enable Message Content Intent under Privileged Gateway Intents.
When mastra connect add discord asks for a credential, enter the bot token.
Agent toolsDirect link to Agent tools
Give agents tools to send and manage messages, and manage channels, threads, roles, members, and webhooks in Discord.
Connect an account with the discord provider ID. Run this command from the directory that contains your .env file:
mastra connect add discord
Then pass tools() to the agent and select the provider:
import { Agent } from '@mastra/core/agent'
import { tools } from '@mastra/connect'
export const discordAgent = new Agent({
id: 'discord-agent',
name: 'Discord agent',
instructions:
'You help people send and manage messages, and manage channels, threads, roles, members, and webhooks in Discord.',
model: '__GATEWAY_OPENAI_MODEL_LUNA__',
tools: tools({ providers: ['discord'] }),
})
The agent gets 34 Discord tools, with keys such as discord_add_guild_member_role. See Discord tools for the full list, and the tools() parameters to restrict tools or require approval before a call runs.
Agent chatDirect link to Agent chat
Your server needs a public URL that Discord can reach for webhook delivery and OAuth callbacks. Mastra platform supplies this URL. When you host elsewhere, set MASTRA_SERVER_URL to your public server URL. For local development, use a public HTTPS tunnel.
-
If you haven't added the connection yet, run
mastra connect add discordand enter the bot token. -
Pass
channels()to theMastraconstructor. It registers the Discord channel provider and its routes:src/mastra/index.tsimport { Mastra } from '@mastra/core'import { channels } from '@mastra/connect'import { assistant } from './agents/assistant'export const mastra = new Mastra({agents: { assistant },channels: await channels({ providers: ['discord'] }),})To register other channels too, add their provider IDs to
providers. -
Start your Mastra application.
-
In Studio, connect the Discord channel to an agent. If the bot isn't already in a server, open the generated authorization URL, choose the server, and approve the requested permissions.
Discord uses the Gateway for messages and the HTTP interactions route for slash commands and buttons. See Discord permissions for the scopes and permissions requested by the bot invite.
Self-managed setupDirect link to Self-managed setup
Use the Chat SDK Discord adapter with your own Discord application and credentials.
Install the adapterDirect link to Install the adapter
Install the Discord adapter from the Chat SDK:
- npm
- pnpm
- Yarn
- Bun
npm install @chat-adapter/discord
pnpm add @chat-adapter/discord
yarn add @chat-adapter/discord
bun add @chat-adapter/discord
Agent configurationDirect link to Agent configuration
Add createDiscordAdapter() to the agent's channels.adapters object:
import { Agent } from '@mastra/core/agent'
import { createDiscordAdapter } from '@chat-adapter/discord'
export const discordAgent = new Agent({
id: 'discord-agent',
name: 'Discord Agent',
instructions: 'Answer questions and help with tasks in Discord.',
model: 'openai/gpt-6.1-sol',
channels: {
adapters: {
discord: createDiscordAdapter(),
},
},
})
Register the agent on the Mastra instance:
import { Mastra } from '@mastra/core'
import { discordAgent } from './agents/discord-agent'
export const mastra = new Mastra({
agents: { discordAgent },
})
Adapter setupDirect link to Adapter setup
Follow the Chat SDK Discord adapter docs for Discord-specific setup, including application creation, bot tokens, interaction endpoints, permissions, and Gateway behavior.
The adapter reads Discord credentials from environment variables such as:
DISCORD_BOT_TOKEN=your-discord-bot-token
DISCORD_PUBLIC_KEY=your-discord-application-public-key
DISCORD_APPLICATION_ID=your-discord-application-id
Webhook URLDirect link to Webhook URL
Mastra generates the Discord webhook route from the agent ID and adapter key:
/api/agents/discord-agent/channels/discord/webhook
Use your public Mastra server URL as the base URL:
https://your-app.example.com/api/agents/discord-agent/channels/discord/webhook
Use this URL anywhere the Discord adapter docs ask for the interactions endpoint or webhook URL. Discord regular message events may require Gateway setup outside the generated webhook route. Follow the Chat SDK adapter docs for that path.