Choose a connection mode

Make three choices independently: where the MCP connection runs, how the tool catalog is advertised, and whether the workflow needs live Discord notifications. Start with the first row unless your MCP host or deployment model requires something else.

Recommended combinations

Combination	Use it when	Host-visible catalog	Gateway	Continue with
Local stdio + progressive	A local client can start discord-mcp and use the direct plan/apply/evidence lifecycle for one-request architecture, then search/dispatch other tools. This is the guided setup default.	7 visible tools when authorized (4 search/dispatch tools plus 3 architecture tools)	Optional	Client setup
Local stdio + full	A compatibility-oriented client must receive its allowed direct tool contracts up front.	up to 209 visible tools; allowlists can reduce this	Optional	Tool-surface configuration
Streamable HTTP + full	A remote caller has native deferred loading or tool search, such as the OpenAI Responses API.	up to 209 direct tools; the caller defers them	Unavailable	OpenAI remote MCP
Streamable HTTP + progressive	A remote MCP host lacks native deferred loading but can use the direct plan/apply/evidence lifecycle for one-request architecture, then search and dispatch other tools.	7 tools when architecture is authorized; otherwise 4 visible tools for discovery/dispatch	Unavailable	Tool-surface configuration

HTTP does not create per-user Discord identities

One HTTP deployment uses one Discord bot token and one shared bearer credential. Every authenticated caller acts with that bot’s Discord permissions. If callers need different Discord rights, give them separate bots and deployment credentials rather than sharing one endpoint.

1. Choose the transport

Local stdio

Use stdio when the MCP client can start a local process, communicate over stdin/stdout, and pass DISCORD_TOKEN through the child-process environment. It is the default transport, requires no public network listener, and is the only transport that can add Gateway notifications.

The guided path verifies one caller-owned bot, saves a non-secret local profile, and generates the client fragment:

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

Follow Client setup for Codex, Claude Desktop, Claude Code, Antigravity CLI, Cursor Agent CLI, DeepSeek Harness, legacy Gemini CLI enterprise deployments, the Cursor editor, or a generic stdio host.

Streamable HTTP

Use HTTP when the MCP caller cannot start the local process or must reach a separately operated deployment. The caller needs Streamable HTTP MCP support, a public HTTPS /mcp endpoint, and a way to send Authorization: Bearer <DISCORD_MCP_ACCESS_TOKEN>. The server is stateless and binds to 127.0.0.1 by default so a reverse proxy can own TLS and public ingress deliberately.

HTTP does not support Gateway subscriptions. It still exposes the same Discord tool behavior, authorization policy, safety middleware, and progressive/full choice as stdio. Follow OpenAI remote MCP for the shared-bot security model, proxy boundary, and deployment example.

2. Choose the tool surface

The tool surface changes what the MCP host sees; it does not change what the bot is authorized to do. MCP_CATEGORIES, ALLOWED_GUILDS, Discord permissions, and write controls still apply after discovery.

• progressive advertises mcp_tools_search, mcp_tools_read, mcp_tools_write, and mcp_tools_destructive, plus build_discord_server, guild_blueprint_apply, and guild_blueprint_evidence when guild architecture is authorized. The read-only front door is the progressive alias of canonical guild_blueprint_plan; together the three direct tools form the obvious preview, approved apply/resume, and independent evidence lifecycle. Other Discord tools remain searchable under their canonical names and are called through the risk-matched dispatcher. Use it when the host does not already defer a large MCP catalog.
• full advertises up to 209 direct tools. MCP_CATEGORIES and ALLOWED_GUILDS can intentionally hide contracts that the configured server scope cannot use. Choose this surface for compatibility or when the caller already supplies native deferred loading, such as OpenAI Responses API tool_search.

Guided setup defaults to progressive because it is the better local starting point. Raw serve and legacy init default to full for backward compatibility. An OpenAI HTTP deployment normally keeps full because adding server-side discovery would create a second discovery layer; a remote Codex setup can use progressive when the client itself does not defer MCP tools.

See MCP_TOOL_SURFACE for the exact environment contract. Switching an existing profile or client fragment requires a client restart because the already-running MCP child does not reload its startup configuration.

3. Decide whether to add Gateway

Gateway is not a transport. It is an optional stdio-only event layer that connects to Discord’s Gateway WebSocket and turns selected events into MCP resource notifications. REST-backed tool calls work without it.

Enable it with guided setup or direct stdio startup:

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

The notification surface uses known resource URIs and subscriptions; it does not implement live resources/list or resources/read. Capability advertisement alone is not proof that the Gateway client connected, so verify one real event before depending on it. HTTP does not support Gateway subscriptions and rejects CLI/profile combinations that request both modes.

Read the Gateway architecture for exact event mappings, then run the Gateway subscription recipe.

Client capability requirements

Client releases change independently, so verify capabilities instead of relying on a hard-coded version matrix.

discord-mcp feature	Client capability	Behavior when absent
Discord tool catalog	tools list/call	Core functionality is unavailable.
Progressive discovery	Ability to call the seven visible MCP tools when guild architecture is authorized, or the four search/dispatcher tools otherwise	Use the full surface if the host cannot search and dispatch.
Components V2 schema/template catalog	resources list/read	Use the tool reference and builder tools instead.
Live Gateway notifications	Resource subscriptions	guild/{id}/info can be reread as an allowlisted snapshot; voice/presence/typing/audit URIs remain signal-only.
Intelligence tools	Sampling	The tool returns a host-processing fallback payload instead of completed analysis.
Confirmation gate	No capability beyond tools	Legacy destructive calls use __confirm; Components V2 send/edit/template use __confirm_hash + one-time __confirm_id; discord-mcp does not require MCP elicitation.

Caution

The server advertises subscription support even when Gateway mode is inactive. Treat a real notification—not initialization metadata—as the success signal.

Verify the chosen mode

1. Run discord-mcp doctor --online --profile devbot where DISCORD_TOKEN is available.
2. Restart the MCP client and inspect tools/list: expect seven tools for progressive when guild architecture is authorized, or four search/dispatcher tools otherwise; full can expose up to 209, with fewer expected when category or guild allowlists narrow the server.
3. Follow the verified first-tool flow for a read-only identity and channel check through the chosen surface.
4. If the workflow needs sampling, verify whether the result is completed or a host-processing fallback.
5. If Gateway is enabled, prove one real subscription notification end to end.

For exact flags, see the CLI reference. For all access controls, see Access and scope. For startup problems, use Troubleshooting.