Skip to main content

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.

Connect
Direct 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 bot
Direct link to Create a Discord bot

  1. In the Discord Developer Portal, create an application.
  2. Open Bot, add a bot, then select Reset Token and copy the bot token.
  3. 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 tools
Direct 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:

src/mastra/agents/discord-agent.ts
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 chat
Direct 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.

  1. If you haven't added the connection yet, run mastra connect add discord and enter the bot token.

  2. Pass channels() to the Mastra constructor. It registers the Discord channel provider and its routes:

    src/mastra/index.ts
    import { 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.

  3. Start your Mastra application.

  4. 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 setup
Direct link to Self-managed setup

Use the Chat SDK Discord adapter with your own Discord application and credentials.

Install the adapter
Direct link to Install the adapter

Install the Discord adapter from the Chat SDK:

npm install @chat-adapter/discord

Agent configuration
Direct link to Agent configuration

Add createDiscordAdapter() to the agent's channels.adapters object:

src/mastra/agents/discord-agent.ts
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:

src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { discordAgent } from './agents/discord-agent'

export const mastra = new Mastra({
agents: { discordAgent },
})

Adapter setup
Direct 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:

.env
DISCORD_BOT_TOKEN=your-discord-bot-token
DISCORD_PUBLIC_KEY=your-discord-application-public-key
DISCORD_APPLICATION_ID=your-discord-application-id

Webhook URL
Direct 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.