Run your first Discord tools

This is the shortest verified path from a local install to a real Discord tool call. You will first prove the connection with a read-only request, then send one message to a test channel.

Before you begin

• Keep the bot installed in your private test server.
• Confirm that your restarted MCP client lists the seven progressive tools described in Client setup when guild architecture is authorized (or the four search/dispatcher tools otherwise), or the allowed direct tools if you deliberately selected the compatibility surface.
• Have the bot token and test server ID available privately.

Note

This tutorial follows the recommended progressive surface: exact Discord tools are loaded with mcp_tools_search and invoked through a risk-matched dispatcher. If you intentionally configured the full surface, the same Discord tools are visible directly; keep the same arguments and safety boundary, but the meta-tool calls are unnecessary.

1. Validate the token against Discord.

   doctor reads the current terminal environment, not the client config. Set the token only for this terminal and run the online checks:

   Bash

   read -rsp 'Discord bot token: ' DISCORD_TOKEN && printf '\n'
   export DISCORD_TOKEN
   discord-mcp doctor --profile devbot --online
   unset DISCORD_TOKEN

   PowerShell

   $env:DISCORD_TOKEN = Read-Host 'Discord bot token' -MaskInput
   discord-mcp doctor --profile devbot --online
   Remove-Item Env:DISCORD_TOKEN

   The first example requires Bash; the second requires PowerShell 7. If neither is available, skip this optional diagnostic rather than placing the token in a command or shell history.

   Find the token-online row with status OK and the message Discord accepted token in the report. Exit 1 can still mean the online token check passed with another warning; inspect every line. Fix failures on exit 2.

2. Prove the client connection read-only.

   In the MCP client you restarted during Unit 2, ask:

   First call mcp_tools_search with query users_get_current. Confirm that the exact match names mcp_tools_read as its dispatcher, then call mcp_tools_read with tool users_get_current and args {}. Tell me the bot username and ID. Do not invoke any other Discord tool.

   The hidden Discord tool needs no arguments. A successful dispatched result identifies the same bot you created in the Developer Portal.

3. Discover the channel ID.

   Replace the example with your copied server ID:

   First call mcp_tools_search with query channels_list. Confirm that the exact match names mcp_tools_read as its dispatcher, then call mcp_tools_read with tool channels_list and args {"guild_id":"999000999000999000"}. Return the ID for general. Do not invoke any other Discord tool.

   The result includes channels[].id. Keep the ID for the next step.

4. Send one test message.

   First call mcp_tools_search with query messages_send. Confirm that the exact match names mcp_tools_write as its dispatcher, then call mcp_tools_write with tool messages_send and args {"channel_id":"112233445566778899","content":"hello from discord-mcp"}. Do not invoke any other Discord tool.

   A successful result contains message_id, channel_id, jump_url, and timestamp. Open jump_url to verify the message in Discord.

Caution

mcp_tools_write preserves the underlying tool’s behavior; it does not add a confirmation step. messages_send is a write, but it is not destructive and is not confirmation-gated. It can execute on the first dispatched call. Keep onboarding inside a test server, set ALLOWED_GUILDS to that server ID, and grant the bot only the Discord permissions it needs.

Checklist for moving on

• Exact searches returned the expected read or write dispatcher and input contract.
• mcp_tools_read returned my bot account and the channel ID from my private test server.
• mcp_tools_write returned message_id, channel_id, jump_url, and timestamp from messages_send.
• I opened jump_url and verified the test message in Discord.

Next, read How a tool call works or open the tool reference.