Privacy-minimized Welcome Screens and reviewed replacement

get_guild_welcome_screen returns one complete bounded Welcome Screen audit for a separately allowlisted guild. Set capabilities.welcomeScreenAudit: true and list every eligible guild in scopes.welcomeScreenGuildIds. This allowlist must be a subset of readScope.guildIds when the outer read allowlist exists. The equivalent discord://guilds/{guildId}/welcome-screen resource applies the same policy and always omits member-facing text.

Every audit verifies the configured application and bot identities, exact guild and owner, connector membership, complete bounded roles, visible direct guild channels and their permission overwrites, guild emoji inventory, guild features, and effective MANAGE_GUILD evidence. Descriptions and Unicode emoji text are omitted by default and returned only transiently when includeText is explicitly true. Exact configured channel IDs and custom emoji IDs remain visible for structural review; a configured or desired channel omitted from Discord's HTTP inventory is an unsafe reference that blocks replacement rather than evidence that the guild has no other channels. Unknown response fields are counted without returning their values. Discord permits an enabled Welcome Screen to be read publicly but requires MANAGE_GUILD to read a disabled one, so a disabled screen that the connector cannot authoritatively fetch is reported as unavailable rather than reconstructed from partial evidence.

Changes have no immediate-call path. Set capabilities.welcomeScreenChanges: true in addition to audit scope. The strict request is one complete ordered replacement containing the exact enabled state, a nullable guild description, and no more than five channel entries. Each entry contains one exact channel ID, a non-empty bounded description, and a tagged absent, custom-ID, or Unicode emoji selection. A zero-entry array deliberately clears every channel entry, while null deliberately clears the guild description.

Planning requires fresh COMMUNITY guild-feature evidence, complete MANAGE_GUILD authority, authoritative current state with no unknown fields, and one unique one-shot operation key. Every desired channel must be a direct text, announcement, forum, or media channel visible to @everyone; parent inheritance, a general read allowlist, or connector-only visibility cannot make a channel eligible. A custom emoji must resolve by exact ID in the target guild, be available, structurally valid, and unrestricted by role. A Unicode emoji must be one normalized emoji grapheme. Missing references, duplicate channels, restricted emoji, unsupported or hidden channels, unavailable current state, incomplete inventories, or an uncertain same-guild predecessor block planning.

1. Call get_guild_welcome_screen with text omitted to inspect structure, permission evidence, reference health, guild features, and unknown-field counts. Request transient text only if the member-facing copy itself must be reviewed.
2. Call plan_guild_welcome_screen_change with the exact complete ordered desired state, Discord audit-log reason, and unique one-shot operation key.
3. Review the verified application and bot IDs, exact guild, complete current and desired states, order-sensitive additions, removals, moves and modifications, public-channel and emoji evidence, COMMUNITY and enablement state, permission evidence, privacy boundary, risks, warnings, operation-key hash, and keyed digest.
4. If the plan reports already-current, no confirmation, reservation, activity record, or Discord write is needed.
5. Call execute_guild_welcome_screen_change with identical inputs plus the digest.
6. Approve the signed MCP confirmation only if every displayed field, order, permission, reference, risk, warning, audit reason, operation-key hash, and digest remains intended, then inspect the verification result before any follow-up.

The process-keyed HMAC digest binds the normalized complete request, verified identities, exact guild features and owner, connector membership and roles, effective permissions, visible direct-channel and overwrite evidence, exact configured and desired channel references, complete emoji evidence, authoritative current state, privacy projection, verification boundary, risks, warnings, and one-shot key hash. A connector restart invalidates outstanding digests. The MCP adapter rebuilds the plan before approval, and the service rebuilds it immediately before mutation. Any identity, feature, permission, visible channel, emoji, current-state, order, text, enablement, audit-reason, or operation-key drift invalidates the reviewed plan.

Execution atomically reserves the operation-key hash and appends a pending content-free activity record before one non-retried PATCH carrying the encoded Discord audit-log reason. The response must be a complete authoritative Welcome Screen object that matches the requested fields, and a fresh full evidence read then verifies the exact enabled state plus complete ordered configuration. Matching controlled state is completed; valid server-adjusted state is completed-with-drift; a known pre-write Discord client error is failed; and transport failure, Discord server error, malformed success, failed response validation, failed readback, or failed receipt finalization is uncertain. The connector never retries or issues a compensating replacement.

All Welcome Screen changes in one guild serialize inside one process because every request replaces shared complete state. The production facade additionally acquires a durable exact guild Welcome Screen collection claim, so connector processes sharing the activity-state root exclude overlapping replacements. An uncertain result retains that claim for operator review before another key can be reserved. Activity and operation records contain only the exact guild ID, plan digest, operation-key hash, timestamps, fixed verification and outcome values, activity ID, and sanitized error category. Descriptions, Unicode emoji, guild and channel names, channel IDs, custom emoji IDs, permission evidence, audit reasons, raw operation keys, raw payloads, and transport causes never enter durable records, diagnostics, or telemetry.

API response and fresh readback verify server-controlled state but cannot prove what a member sees in a Discord client, so an enabled plan recommends a separate fresh non-staff client check. See Discord's Welcome Screen object and endpoints and permission flags.

Canonical source: docs/reference.md