Discord bot setup

GuildControl MCP is self-hosted and uses no shared application identity. Each operator creates and controls a separate Discord application, bot user, installation, and token. The connector is the local software that drives that bot; it is not a hosted bot, relay, or account provider. A Developer Portal URL containing an application ID identifies one account-owned application and does not install that application for other operators.

The recommended first installation is derived from the same immutable read-only preset contract used by setup. Create an application in the Discord Developer Portal, confirm its Bot page has a bot user, copy the public Application ID, enable Guild Install on the Installation page, copy the target Server ID with Discord Developer Mode, and run:

npx --yes guildcontrol@0.1.2 preset install server-observer \
  --application-id APPLICATION_ID \
  --guild-id GUILD_ID \
  --html ./guildcontrol-onboarding.html

preset install validates both public IDs and prints a fixed-origin Discord authorization URL with the bot scope, the exact preset permission bitfield, the selected guild_id, and disable_guild_select=true. Discord's bot authorization flow documents this callback-free shape: it requires no redirect URI, client secret, authorization code, or user access token. Supplying the exact scope and permission bitfield avoids depending on mutable default install settings. The command itself needs no credential, contacts neither Discord nor a browser, opens no Gateway, writes no profile or config, and creates no activity record.

Optional --html FILE exclusively writes a private deterministic guildcontrol.onboarding-html.v2 guide for the exact plan. The page exposes the public IDs, required permissions and intents, fixed-origin install link, credential reference, pinned npx post-install commands, and one read-only first-use request through an accessible checklist and non-secret copy controls. It never accepts or embeds a token, automatically navigates, fetches a resource, persists checklist state, or configures a client. Its restrictive content security policy authorizes only the exact embedded interaction script, while every external Discord navigation requires a deliberate link click. The CLI reports separate plan and HTML SHA-256 digests and refuses to replace an existing file.

For server-observer, the generated grant is only VIEW_CHANNEL, decimal bitfield 1024, and no privileged intent. For channel-reader, it is VIEW_CHANNEL plus READ_MESSAGE_HISTORY, decimal bitfield 66560, with MESSAGE_CONTENT identified as the recommended Developer Portal intent. Discord defines these bits in its permission flags and documents that channel message history needs both effective permissions in its message resource. Preset construction mechanically rejects ADMINISTRATOR, noncanonical or duplicate permissions, and any write-capable tool.

Application-owned emoji access is application-scoped rather than guild-scoped. Discord documents bot-token authentication for the verified application's application-owned emoji endpoints, so this capability adds no guild permission or privileged intent to an installation URL. The connector never accepts an application ID from an emoji tool call; it uses the application and bot identities pinned in the configuration and verified from the token.

One-to-one private messaging is also outside guild permissions, but it is not a shared-bot service. The operator's same pinned bot token opens or reuses a DM only during an approved exact-recipient send. Discord's Create DM documentation says DMs should generally follow a user action and warns that opening many private channels can cause rate limiting or blocking. Configure only users who reasonably expect contact, keep the bot available through the intended Discord interaction or shared installation context, and expect blocks, privacy settings, or platform eligibility to reject some deliveries. The connector never enumerates private channels, finds recipients by name, creates group DMs, or subscribes to DM Gateway events. Discord's Message Content intent exception covers content in DMs with the app, so the dedicated workflow adds no privileged intent.

Privileged intents normally begin as a manual Developer Portal decision. An operator may instead enable the separate reviewed application-security workflow after strict policy already justifies Guild Members or Message Content. The workflow changes only the corresponding limited application flag through Discord's Modify Current Application endpoint, never Presence, a full-authorization flag, a disablement, Public Bot, code-grant requirements, install settings, or arbitrary application metadata. The operator still owns the application, bot, installations, and token, and should inspect the Developer Portal after any uncertain outcome.

Complete the first installation in this order:

1. Keep Public Bot disabled unless other people should be allowed to install this application.
2. Enable only the privileged intents named by the generated plan. Message Content is recommended for channel-reader; Guild Members is not part of either first-install preset.
3. Open the printed URL while signed in as a member with Manage Server authority for the target server, verify the locked server and named permissions, and approve the installation.
4. Restrict the installed bot role with category or channel overrides wherever possible. The OAuth grant seeds a guild role, while effective channel permissions still depend on role and overwrite evaluation.
5. Store the bot token in a secret-capable local launcher or MCP host setting under DISCORD_BOT_TOKEN, or mount it as a protected file. Do not put its value in a config file, client arguments, shell history, source control, or an authorization URL.
6. Make the token available only through the chosen secret input and run the plan's setup command, replacing its optional CHANNEL_ID placeholder and adding --token-file ABSOLUTE_FILE when using a mounted file. Setup discovers and verifies both public identities from the bot credential, completes the bounded ID-only installed-guild inventory, compares it with every configured guild, and saves only the external credential reference in the non-secret config.
7. Translate the portable descriptor printed by successful setup into the MCP host, then run the generated natural-language list_channels first-use request for the exact guild. The tool defaults to a compact bounded directory page and exposes an authenticated continuation only when the answer needs more channels. This final layer proves the host launch and one useful scoped read, not any write authority.
8. Use config validate, online doctor, or smoke only when a manual edit, launch failure, or assurance requirement calls for independent evidence. Online doctor rechecks the token's application and bot identities, privacy-safe application security posture, and complete configured-versus-installed guild drift; smoke launches a child connector and negotiates its read-only MCP path.

The generator deliberately covers only the two audited read-only first-use presets. Arbitrary write-enabled policies need feature-specific Discord permissions, narrower local allowlists, and reviewed execution gates, so no single static permission bitfield can represent them safely.

Add Send Messages and Add Reactions later only for exact channels selected for interactions. Static Components V2 additionally require Message Content intent, View Channel, Read Message History, and the applicable direct-channel or thread send permission. Static rich embeds use their own exact scope and additionally require Message Content intent, View Channel, Read Message History, Embed Links, and the applicable direct-channel or thread send permission. Add Manage Messages only after selecting exact channels for reviewed reaction moderation, retain View Channel and Read Message History, add Connect for voice or Stage targets, and keep both reaction identity-audit and moderation toggles disabled until their shared exact channel allowlist is configured. Add Attach Files and the applicable send permission only after selecting exact attachment channels and dedicated local attachment directories, and keep the local attachment toggle disabled until both scopes are configured. Add View Channel, Read Message History, and Send Messages only after selecting exact forum channels, add Manage Threads only when moderated tags are needed, and keep the local forum-post toggle disabled until those channel IDs are configured. Add Create Public Threads only after selecting exact text or announcement parents for anchored or standalone-public creation, add Create Private Threads only after selecting exact text parents for standalone-private creation, retain Read Message History for message-anchored creation, and keep the local thread-creation toggle disabled until those parent IDs are configured. For thread governance, retain View Channel, add Send Messages in Threads only for unarchive or member-add workflows, and add Manage Threads only for the selected lifecycle, metadata, invitation-policy, or membership actions that require it; keep both local thread-governance gates disabled until exact guild and thread allowlists are configured. Enable the Guild Members privileged intent only after selecting exact member-directory guilds, and keep the local member-directory toggle disabled until that allowlist is configured. Add Ban Members only after selecting exact guilds for ban audit or reviewed ban changes, and keep the local ban-audit toggle disabled until that guild allowlist is configured. Add Change Nickname only after selecting exact guilds for the self-only nickname route. Add Manage Nicknames only when the separate other-member gate is intentional, then protect ineligible users and keep the bot's highest role strictly above every eligible target. Add Pin Messages only after selecting exact pin channels or threads, and keep the local pin-management toggle disabled until those IDs are configured. For announcement crossposts, enable Message Content intent, retain View Channel and Read Message History, add Send Messages to each exact selected direct announcement channel, and add Manage Messages only when another author owns a message that may be published. For native message forwarding, enable Message Content intent, grant View Channel plus Read Message History on every exact source, and grant View Channel, Read Message History, plus Send Messages on every exact target so independent readback remains possible; keep forwarding and its separate cross-guild gate disabled until both direct-channel allowlists and pinned identities are configured. Add Manage Webhooks and retain View Channel only after selecting exact direct channels for webhook audit or administration, and keep all webhook toggles disabled until those channel IDs are configured. Add Manage Guild only after selecting exact guilds for capability-safe invite and privacy-bounded vanity URL audit or invite revocation, and keep both invite toggles disabled until those guild IDs are configured. Add Manage Guild plus Manage Roles only after selecting exact guilds for onboarding replacement, and keep onboarding audit and change toggles disabled until those guild IDs are configured. Add Manage Guild only after selecting exact Community guilds for Welcome Screen audit or replacement, and keep both Welcome Screen toggles disabled until those guild IDs are configured. Add Manage Guild only after selecting exact guilds for authenticated widget-settings audit or replacement, keep all three widget gates disabled until those guild IDs are configured, and enable the separate public-exposure gate only when a reviewed workflow may enable the widget or select a different non-null channel. Add Create Guild Expressions only after selecting exact guilds for emoji, sticker, or soundboard creation, add Manage Guild Expressions only when cross-owner updates or deletions are required, configure dedicated local expression or soundboard roots before the corresponding creation workflow, and keep each local audit and change toggle disabled until its exact scope is configured. Add Create Events only after selecting exact scheduled-event guilds; add Manage Events only for cross-owner changes, add the documented stage or voice channel permissions only to exact hosting targets, configure dedicated local cover roots before image changes, and keep the local scheduled-event audit, subscriber-audit, and change toggles disabled until those scopes are configured. Scheduled-event subscriber audit reuses the event read permissions, explicitly disables member expansion, and does not require the Guild Members privileged intent. Add View Channel, Connect, Manage Channels, Mute Members, and Move Members only after selecting exact Stage channels for lifecycle management, add Mention Everyone only for deliberately reviewed guild-wide start notifications, and keep all three local Stage toggles disabled until their exact channel scope is configured. Add View Channel and Connect only after selecting exact member voice-audit guilds and voice or Stage channels; add only the required Move Members, Mute Members, or Deafen Members permission after selecting exact ordinary voice channels for reviewed changes, and keep both local voice gates disabled until both allowlists are configured. Add Manage Channels and retain View Channel only after selecting exact direct guild channels for reviewed metadata changes, and keep the local metadata-change toggle disabled until those channel IDs are configured. Add Manage Roles and retain View Channel only after selecting exact direct guild channels for permission-overwrite changes, and keep the local permission-overwrite toggle disabled until those channel IDs are configured. Add Manage Channels only after selecting exact channel-creation or scaffold guilds and parent categories, and keep both local toggles disabled until those guild IDs are configured. For channel ordering, select exact guilds, grant Manage Channels at guild scope or through complete visible parent-category evidence, and keep the independent audit and change gates disabled until the exact guild scope is configured. For channel retirement, select one exact direct target, grant Manage Guild at guild scope, retain View Channel and Manage Channels on the target, add Manage Webhooks for webhook-capable targets, and add Read Message History plus Manage Threads for text, forum, or media targets; keep audit and execution disabled until the exact channel is configured. Add Manage Roles only after selecting exact role-creation, scaffold, member-role, role-configuration, role-deletion, or role-ordering scopes; add Manage Guild only for the role-deletion dependency audit, list every assignable, configurable, or deletable role by exact ID, select role ordering by exact guild, keep the bot's highest role above every target, anchor, affected role, and target member, and keep every local toggle disabled until its narrower scope is configured. Add Manage Messages only after selecting message-deletion channels. Add only the specific member permission needed for planned guild administration, keep the bot's highest role above eligible targets, and keep the local administration toggle disabled until exact guild and protected-user IDs are configured.

For parent-category permission synchronization, select each eligible direct child by exact ID in the independent synchronization scope. Retain View Channel, Manage Channels, and Manage Roles on the current and prospective child, retain View Channel on its exact parent category, and ensure the connector holds every permission copied from the parent. Keep the capability disabled until concurrent permission editors and overlapping connector processes are stopped for the reviewed operation.

For invite creation, grant only View Channel and Create Instant Invite on each exact selected direct channel, configure a dedicated private capability-file root, and keep the independent creation gate disabled until both local boundaries are configured. Add Manage Guild only for exact-user acceptance. Persistent invite role assignment is a separate opt-in: enable the nonprivileged Gateway layout, grant Manage Roles, list each eligible standard role by exact ID, keep every selected role strictly below the connector, and ensure the connector holds every guild and channel permission those roles can grant. Invite audit and revocation remain separate guild-scoped capabilities that require Manage Guild.

For channel metadata changes on voice or Stage channels, retain Connect on the exact target because Discord's implicit permission rules otherwise make channel-management authority ineffective.

Exact ordinary voice-channel status reuses the same metadata gate and exact channel allowlist. Grant Set Voice Channel Status and retain View Channel on each selected target. Discord additionally requires Manage Channels whenever the connector is not connected to that exact target. The derived status-evidence Gateway connection uses only the nonprivileged GUILDS intent, and no new configuration or environment setting is needed.

For guild profiles, select exact guilds for transient text audit and keep the audit gate disabled until that allowlist is configured. Add Manage Guild only when reviewed name or description changes are needed, then enable the separate change gate. Profile audit remains useful without that permission because it explicitly reports whether the connector is authorized to change the profile.

The optional real-time feed and layout-only channel-completeness connection need no privileged intent in the Developer Portal. Discord documents bot installation in its getting started guide, Gateway connection behavior in its Gateway reference, guild profile, channel creation, channel ordering, role creation, role configuration, role deletion, role ordering, member nickname changes, member-role changes, member voice changes, and member moderation in its guild resource reference, obfuscated channel semantics and the CHANNEL_OBFUSCATED flag in its channel resource reference, exact member voice-state lookup in its voice resource reference, invite behavior and revocation in its invite resource reference, soundboard behavior and permissions in its soundboard reference, scheduled-event behavior and permissions in its guild scheduled event reference, Stage lifecycle behavior in its Stage instance reference, channel metadata and permission-overwrite changes in its channel resource reference, and announcement crossposting, native message forwarding, and message deletion in its message resource reference.

Exact voice-channel status uses Discord's Set Voice Channel Status endpoint, Get Current User Voice State endpoint, Request Channel Info command, and Channel Info plus Voice Channel Status Update dispatches.

Canonical source: docs/reference.md