Skip to content
Discord MCP logoDiscord MCP logodiscord-mcp

Client setup

This lesson covers the default local stdio MCP setup for clients that can spawn an MCP server as a subprocess. The recommended setup command verifies one caller-owned bot, saves a non-secret local profile, and generates a client-specific configuration fragment. Codex and Grok Build receive TOML, DeepSeek Harness and Continue receive YAML, and the remaining clients receive their host’s JSON-shaped fragment. Continue’s generated YAML uses version 1.0.0. It prints the fragment by default, so you stay in control of the file you merge it into.

The eight new adapters below are available from v0.30.0. Guided setup pins its launcher to that package version. To inspect configurations without credentials, run npx --yes @discord-mcp/cli@0.29.0 init --client <id>.

If you need remote HTTP, the full direct-tool catalog, or live Gateway notifications, first choose a connection mode. The tutorial below follows the recommended local stdio + progressive path.

Before you begin

  • Confirm that discord-mcp --version works in your terminal.
  • Keep your bot token available in a password manager or another private location.
  • Find your client’s local MCP configuration file before generating a snippet.

Load the token into the terminal that will run setup. Launch command-line clients from an environment that still contains the variable; desktop clients may need the equivalent user/session environment configured before restart. Continue IDE users should follow the .continue/.env instructions in that tab.

Terminal window
read -rsp 'Discord bot token: ' DISCORD_TOKEN && printf '\n'
export DISCORD_TOKEN
Terminal window
$env:DISCORD_TOKEN = Read-Host 'Discord bot token' -MaskInput

Choose your client

Section titled “Choose your client”
Terminal window
discord-mcp setup --profile devbot --client claude-desktop

Merge the printed discord-mcp entry into the mcpServers object, then fully quit and reopen Claude Desktop.

OS Config file
macOS ~/Library/Application Support/Claude/claude_desktop_config.json
Windows %APPDATA%\Claude\claude_desktop_config.json
Linux ~/.config/Claude/claude_desktop_config.json

What success looks like after restart

Section titled “What success looks like after restart”

setup defaults to the progressive surface so the client does not have to load every Discord contract into its context at once. Check the saved choice with discord-mcp profile show devbot; the Client/tool surface line should match what you expect.

Section titled “progressive (recommended)”

The client should show 7 visible tools when guild architecture is authorized: mcp_tools_search, mcp_tools_read, mcp_tools_write, mcp_tools_destructive, and the direct architecture lifecycle build_discord_server, guild_blueprint_apply, and guild_blueprint_evidence. The read-only front door is the progressive alias of canonical guild_blueprint_plan and the one-request entrypoint for server architecture; the next two tools apply/resume an explicitly approved plan and verify its Activity Evidence. Other Discord tools remain searchable under their canonical names and are invoked through the risk-matched dispatcher. Without guild architecture authorization, the surface has 4 visible tools for search and dispatch.

The individual Discord tool names are intentionally absent from tools/list in this mode. Run your first Discord tools demonstrates the complete search-and-dispatch path; do not switch to the full surface just to follow the tutorial.

full (compatibility)

Section titled “full (compatibility)”

The client can show up to 222 visible direct tools. MCP_CATEGORIES and ALLOWED_GUILDS can intentionally reduce that number; this mode exposes every contract allowed by the resulting server scope immediately, at a larger context and tool-selection cost.

If your MCP client cannot use the discovery and dispatcher tools, rerun setup for the same verified bot with --tool-surface full --force plus your existing setup options, merge the new fragment, and restart the client.

Why a full restart is required

Section titled “Why a full restart is required”

The setup terminal and the MCP client are separate process trees:

setup terminal  ->  verifies the bot and saves the profile/snippet
MCP client      ->  starts discord-mcp as a child  ->  connects to Discord

The discord-mcp child reads its profile, package version, and inherited environment when the client starts it. Changing the token, profile, generated config, or pinned package does not rewrite an already-running child process. Fully quitting and reopening the MCP client makes it spawn a fresh child with the new state. Likewise, doctor checks the environment of the terminal where you run it; a passing result there does not change an older client process.

The generated snippet runs a pinned @discord-mcp/cli package through npx, rather than an absolute CLI or npm-cache path, so restarting the client or replacing the installation does not require editing the fragment. The non-secret profile is still local to the operating-system user that created it. If you move machines, rerun setup there instead of copying the profile blindly.

If you intentionally place a token directly in any client config, treat that whole file as a secret: do not commit, share, or screenshot it.

After restarting, confirm that your client can list discord-mcp’s tools without a startup error. Unit 3 performs the online token diagnostic and the first authenticated tool call, so you do not need to expose the token to a second process yet.

Checklist for moving on

Section titled “Checklist for moving on”
  • I merged the generated discord-mcp entry without removing my other MCP servers.
  • discord-mcp profile show devbot reports the intended bot ID and guild allowlist.
  • My client can resolve DISCORD_TOKEN through its launch environment or private secret provider (Continue IDE uses .continue/.env); generated fragments and profiles contain no literal token.
  • I fully restarted the MCP client after changing its configuration.
  • The client can list the expected progressive or full tool surface without a server startup error.