Configure discord-mcp

discord-mcp receives its runtime settings through environment variables in your MCP client configuration. Start with the smallest safe configuration, verify it, then add controls for the behavior you need.

Start with a safe baseline

Set the bot token and restrict the deployment to the Discord server IDs it is supposed to control:

DISCORD_TOKEN=your-discord-bot-token
ALLOWED_GUILDS=111122223333444455
MCP_WRITE_MODE=preview
MCP_ACCESS_MODE=advisory
MCP_DM_CONSENT_MODE=require
MCP_ALLOW_USER_SCOPED=false

This starts the server with REST-only transport, info logging, retry, circuit breaking, and audit logging enabled. Destructive tools stay in dry-run mode until you explicitly opt in. ALLOWED_GUILDS is optional for backward compatibility, but strongly recommended whenever the bot can see more than one server. MCP_ACCESS_MODE=advisory is the compatibility default. The built-in stdio and HTTP transports provide a conservative read-only evidence resolver for warn and enforce; custom embedders should inject an equivalent provider before turning on enforce.

MCP_DM_CONSENT_MODE=require adds an explicit, one-time caller-approval step before users_create_dm contacts a user. The host/operator must obtain any human consent separately; the returned MCP preview is not proof of a human click. Keep the default advisory mode only when the deployment has a separate consent workflow.

Caution

MCP_DRY_RUN arms the 31 legacy confirmation-gated tools and the stricter payload-bound policy for components_v2_send, components_v2_edit, and components_v2_send_from_template. Setting it to false removes the dry-run half, but legacy calls still need __confirm: true; Components V2 calls additionally need the exact __confirm_hash and one-time __confirm_id returned by their preview.

This setting does not protect ordinary writes. With the default MCP_WRITE_MODE=allow, ordinary writes can execute immediately. Set MCP_WRITE_MODE=preview when every mutation should return a preview instead.

Add controls by intent

Limit accessAllow only the guilds and tool categories your agent needs.

Control writesUnderstand dry-run mode and make deliberate production changes.

Observe trafficExport traces to an OTLP collector or inspect spans locally.

Tune reliabilityAdjust retry, timeout, circuit breaker, and concurrency limits.

Record mutationsChoose the audit sink and file location that fit your operations.

Verify before using an agent

Run the online doctor after the client has started the server:

discord-mcp doctor --online

It reports missing or invalid schema-backed environment variables. Use the environment variable reference for the exact accepted values and defaults. MCP_DRY_RUN is intentionally not part of that schema validation, so verify that value byte-for-byte before enabling writes.