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 receives a YAML patch, and the other clients receive JSON. It prints the fragment by default, so you stay in control of the file you merge it into.

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.

Caution

setup does not edit your client config and has no token flag. The current DISCORD_TOKEN is sent only to Discord to verify the bot and its guild membership; it is not copied into the generated fragment or profile. The Codex fragment forwards DISCORD_TOKEN from the environment. Antigravity CLI, Cursor Agent CLI, Grok Build CLI, and most JSON-configured clients inherit the client process environment and omit a token field. Gemini CLI instead emits the non-secret ${DISCORD_TOKEN} reference because Gemini removes inherited sensitive variables from MCP child processes unless the server entry explicitly opts in. The older init --token path is for explicit legacy automation and can expose a secret through shell history or process inspection.

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.

read -rsp 'Discord bot token: ' DISCORD_TOKEN && printf '\n'
export DISCORD_TOKEN

$env:DISCORD_TOKEN = Read-Host 'Discord bot token' -MaskInput

Choose your client

Claude Desktop

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

Claude Code

discord-mcp setup --profile devbot --client claude-code

Merge the output into ~/.claude.json for user-level configuration, or into <project>/.mcp.json for a project. Claude Code also supports its managed claude mcp add workflow; use the generated snippet when you prefer explicit JSON.

Codex

discord-mcp setup --profile devbot --client codex

discord-mcp setup --profile devbot --client codex

Merge the TOML fragment into ~/.codex/config.toml. It uses env_vars = ["DISCORD_TOKEN"], so Codex forwards the token from its launch environment instead of storing it in config.toml. The fragment starts serve --profile devbot; that versioned profile supplies the verified DISCORD_EXPECTED_BOT_ID, ALLOWED_GUILDS, and progressive tool surface at runtime. It also sets tool_timeout_sec = 180, so a bounded multi-step blueprint apply is not cut off by Codex’s 60-second default MCP tool timeout. Short calls still return immediately. If the bot can see multiple guilds in a non-interactive run, rerun with --allowed-guilds <id> to make the target explicit.

Start Codex from a terminal where the token is set:

export DISCORD_TOKEN="Bot YOUR_DISCORD_BOT_TOKEN"
codex

$env:DISCORD_TOKEN = "Bot YOUR_DISCORD_BOT_TOKEN"
codex

This is the local stdio setup for the Codex CLI and IDE extension. Start a new Codex session after changing its configuration.

Antigravity CLI

discord-mcp setup --profile devbot --client antigravity-cli

Merge the generated discord-mcp entry into ~/.gemini/config/mcp_config.json for user-level configuration or <project>/.agents/mcp_config.json for one project. Start agy from the terminal that contains DISCORD_TOKEN; Antigravity passes the launch environment to the local MCP process, so the generated JSON deliberately has no token field. By default, Antigravity asks before an unconfigured MCP action. Approve only the exact discord-mcp tool needed for the current operation, then verify the saved file with discord-mcp doctor --client antigravity-cli --profile devbot.

Antigravity CLI is the current Google consumer terminal. Gemini CLI remains below for enterprise and paid API-key compatibility after Google’s June 18, 2026 consumer transition.

Cursor Agent CLI

discord-mcp setup --profile devbot --client cursor-cli

Merge the generated discord-mcp entry into ~/.cursor/mcp.json for user-level configuration or <project>/.cursor/mcp.json for one project. Install the official Cursor CLI for macOS, Linux, WSL, or native Windows, verify it with agent --version, then launch agent from a terminal that contains both DISCORD_TOKEN and your Cursor authentication. The generated MCP JSON deliberately stores neither DISCORD_TOKEN nor CURSOR_API_KEY. For automation, place deny-by-default rules in .cursor/cli.json and allow only the exact Mcp(discord-mcp:tool_name) calls required by the workflow. Verify the saved launcher locally with discord-mcp doctor --client cursor-cli --profile devbot.

Grok Build CLI

discord-mcp setup --profile devbot --client grok-cli

Merge the generated TOML table into ~/.grok/config.toml, or $GROK_HOME/config.toml when you use a custom Grok home. Authenticate the official Grok Build CLI with grok login or XAI_API_KEY, then launch it from a terminal containing DISCORD_TOKEN; the generated fragment stores neither credential. The lifecycle adapter uses Grok’s documented --single ... --output-format streaming-json contract, the native search_tool → use_tool MCP flow, exact MCPTool(discord-mcp__<tool>) permission rules, and --resume <session-id>. See the Grok Build MCP documentation. Verify the saved launcher with discord-mcp doctor --client grok-cli --profile devbot.

Gemini CLI (compatibility)

discord-mcp setup --profile devbot --client gemini-cli

Use this compatibility path only when your enterprise or paid API-key deployment still requires Gemini CLI. Merge the generated mcpServers object into ~/.gemini/settings.json for user-level configuration or <project>/.gemini/settings.json for one project. Keep DISCORD_TOKEN in the environment that launches Gemini. The generated ${DISCORD_TOKEN} value is an interpolation reference, not the token itself; it explicitly opts the discord-mcp child into that one variable after Gemini sanitizes inherited secrets. Merge this fragment directly. After any Gemini-managed MCP settings change, run discord-mcp doctor --client gemini-cli --profile devbot and inspect the raw file before restarting; current Gemini releases can reserialize an expanded environment value while rewriting settings.

Cursor editor

discord-mcp setup --profile devbot --client cursor

This tab configures the Cursor editor rather than Cursor Agent CLI. Merge the output into ~/.cursor/mcp.json for global access or <project>/.cursor/mcp.json for one project. Restart Cursor after changing it.

DeepSeek Harness

discord-mcp setup --profile devbot --client deepseek-harness --output discord-mcp.cordis.yml
dsh web --patch ./discord-mcp.cordis.yml

Install and configure DeepSeek Harness first. Run both commands from an environment containing DISCORD_TOKEN. The generated YAML patch inserts the official @deepseek-ai/dsh-mcp-client plugin with a pinned discord-mcp launcher, a 180-second tool-call timeout, and startup failure reporting. Keep DISCORD_TOKEN: !!js process.env.DISCORD_TOKEN as written: Harness removes ambient token variables before spawning MCP servers, so this explicit reference forwards the value without saving it in YAML.

For persistent configuration, merge the insert entry into $DSH_HOME/profiles/<name>/cordis.patch.yml for one Harness profile, or $DSH_HOME/cordis.patch.yml for all profiles. Preserve other patches and enable this entry in only one active layer. A Harness profile is separate from discord-mcp’s devbot profile. See the official patch configuration guide.

Verify the bot and profile with discord-mcp doctor --profile devbot --online, then confirm Harness lists tools such as mcp__discord-mcp__mcp_tools_search. The MCP plugin currently bridges tools; MCP Resources and Prompts are not bridged. Keep Gateway disabled unless a future host version adds the required subscription support. doctor --client deepseek-harness is not supported; the profile check does not inspect or evaluate Harness YAML. Local config generation is separate from live model-to-Discord verification.

Generic MCP

discord-mcp setup --profile devbot --client generic

The output is a standard mcpServers block. Place it where your MCP client’s own documentation expects stdio server configuration.

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.

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)

The client can show up to 209 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

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

• 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.
• The client launch environment supplies DISCORD_TOKEN; neither profile nor client config stores it.
• 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.