Credential lifecycle

discord-mcp never creates, resets, revokes, or stores a Discord bot token. The caller owns the bot in the Discord Developer Portal and supplies its current token through the deployment environment or secret manager.

DISCORD_EXPECTED_BOT_ID adds a non-secret identity lock. When configured, discord-mcp calls Discord’s current-user endpoint before serving MCP and fails startup if the token belongs to a different bot. Successful verification is cached for the process, including stateless HTTP deployments.

Establish the identity lock

The recommended guided command derives the lock and guild boundary from the same live, caller-owned bot and saves them as non-secret profile metadata:

export DISCORD_TOKEN="Bot YOUR_DISCORD_BOT_TOKEN"
discord-mcp setup --profile devbot --client codex

Merge the generated fragment. It forwards DISCORD_TOKEN without storing the secret and starts discord-mcp serve --profile devbot. Inspect the profile:

discord-mcp profile show devbot

Profiles are versioned JSON under %APPDATA%\discord-mcp\profiles on Windows, ~/Library/Application Support/discord-mcp/profiles on macOS, and ${XDG_CONFIG_HOME:-~/.config}/discord-mcp/profiles on Linux. A profile stores the verified bot ID, guild allowlist, client, tool surface, Gateway choice, and the reference env:DISCORD_TOKEN. Unknown fields are rejected; the token value is never stored.

Rerun setup --profile devbot --force to update client or guild metadata for the same bot. Even with --force, the profile cannot be assigned to another bot ID. Remove the old profile explicitly before setting up a genuinely different caller-owned bot.

The identity lock answers “which bot may this deployment use?” The guild allowlist independently answers “which servers may that bot operate against?” Keep both controls.

Rotate a bot token

Record the existing DISCORD_EXPECTED_BOT_ID and stop writes through the deployment. Do not copy the old token into notes, commands, or screenshots.
Reset the bot token from the application’s Bot page in the Discord Developer Portal. The old bot token becomes unusable.
Replace DISCORD_TOKEN in the caller-controlled environment or secret manager. Do not change DISCORD_EXPECTED_BOT_ID during a routine rotation.
In an isolated terminal using the new secret, run:
Terminal window
```
discord-mcp doctor --profile devbot --online
discord-mcp smoke --profile devbot
```
token-online must report the expected bot. smoke is read-only by default and proves the real MCP-to-Discord path.
Restart every process that inherited the old environment, then resume writes only after the new process is healthy.

If startup reports Discord bot identity mismatch, the new token belongs to a different application. Restore the intended caller-owned bot token. Do not change the expected ID merely to silence the failure.

Revoke or retire access

For a suspected leak, reset the token immediately in the Developer Portal, remove it from every caller-controlled secret store, and stop or restart all deployments that inherited it. Removing the bot from a guild cuts off that guild, but it does not replace token reset after credential exposure.

To retire a deployment permanently:

stop the MCP process and its tunnel or reverse-proxy route;
delete its DISCORD_MCP_ACCESS_TOKEN from the caller’s secret store;
remove its Discord bot token from the runtime environment;
run discord-mcp profile remove devbot --yes to remove the local metadata;
remove the bot from guilds it no longer needs; and
reset the bot token if another party or system may still possess it.

Removing a profile does not revoke or reset a Discord token. The command says this explicitly and reports tokenRevoked: false in JSON mode.

One deployment still represents one caller-owned bot identity. Do not reuse a shared bot token across unrelated callers or turn DISCORD_TOKEN into a central multi-tenant credential store.