Privacy-minimized guild settings and reviewed changes

get_guild_settings returns one bounded named guild-settings audit for a separately allowlisted guild. Set capabilities.guildSettingsAudit: true and list every eligible guild in scopes.guildSettingsGuildIds. This allowlist must be a subset of readScope.guildIds when the outer read allowlist exists. Enabling the audit activates nonprivileged layout-only Gateway evidence and requires pinned application and bot IDs. The equivalent discord://guilds/{guildId}/settings resource applies the same policy and privacy projection.

The supported surface is finite: member verification level, default message notifications, explicit-media filtering, nullable AFK voice channel, AFK timeout, nullable system text or announcement channel, six named system-notification suppressions, and premium progress-bar enablement. Callers never provide Discord numeric enums or a raw system-channel bitfield. Guild and channel names, role names, member data, raw payloads, and unknown values are omitted. Unknown system-channel bits are reduced to a presence value so future Discord additions cannot be mistaken for known state.

Every read verifies the expected application and bot, exact guild and owner, connector membership, complete bounded roles, complete effective guild permissions, and continuity-safe channel evidence. The channel inventory is accepted only when one bounded HTTP pass is bracketed by identical complete Gateway layouts and the HTTP result is complete or an exact non-obfuscated subset. AFK references are eligible only when exact trusted metadata identifies an ordinary guild voice channel. System references are eligible only when exact trusted metadata identifies a guild text or announcement channel. An omitted or obfuscated current reference remains visible as an unsafe structural reference rather than being silently cleared.

Changes have no immediate-call path. Set capabilities.guildSettingsChanges: true in addition to audit scope. A strict request must select at least one supported field, a bounded Discord audit-log reason, and a unique one-shot operation key. Omitted settings are preserved. A supplied null deliberately clears the applicable channel reference. A supplied notification-suppression array is one complete named list, sorted and deduplicated during normalization. Unknown existing system-channel bits block a suppression-list change because safely preserving or replacing their meaning is impossible, while unrelated scalar changes can proceed without touching that bitfield.

Planning requires the exact guild owner or complete MANAGE_GUILD authority, complete permission evidence that separately reports any unknown bits, authoritative finite-valued current settings, and eligible trusted metadata for each requested non-null channel. A request can explicitly clear an unsafe current channel reference, and a scalar-only request does not require unrelated unsafe channel metadata to become trusted. The plan reports exact requested and changed fields, complete named current and desired states, direction-aware effects, privacy and inventory evidence, risks, warnings, and verification limits. Weakening verification or filtering, broadening default notifications, reducing suppressions, changing routing, and changing presentation are visible effects rather than hidden numeric transitions.

1. Call get_guild_settings to inspect the complete named state, authority, channel references, inventory continuity, unknown-bit boundary, privacy projection, and verification limits.
2. Call plan_guild_settings_change with only the intended fields, the Discord audit-log reason, and a unique one-shot operation key.
3. Review the verified application and bot IDs, exact guild, requested and changed fields, complete current and desired settings, effects, permission and channel evidence, unknown-bit 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_settings_change with identical inputs plus the digest.
6. Approve the signed MCP confirmation only if every displayed identity, field, reference, effect, 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 sparse request, verified identities, exact guild owner, connector membership and roles, effective permissions, continuity-safe channel evidence, complete authoritative current and desired settings, requested and changed fields, effects, 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, authority, permission, channel-layout, current-state, requested-field, 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 sparse PATCH carrying the encoded Discord audit-log reason. The response must be a complete valid Guild object, its requested controlled fields are compared with the reviewed values, and a second complete fresh evidence read verifies the authoritative state. Exact response and readback agreement is completed; valid controlled-field divergence is completed-with-drift and reports field names only; a definite Discord client refusal is failed; and transport failure, Discord server error, malformed success, failed response validation, failed readback, or failed receipt finalization is uncertain. Every reserved key remains spent, and the connector never retries, rolls back, or compensates automatically.

All guild-settings changes in one guild serialize inside one process. The production facade additionally acquires a durable exact guild-settings collection claim, so connector processes sharing the activity-state root exclude overlapping changes. An uncertain result retains that claim for operator review before another execution can replan, reserve, or write. 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; activity records additionally contain sorted requested field names. Setting values, channel IDs, guild, role, and channel names, permission evidence, audit reasons, raw operation keys, raw payloads, and transport causes never enter durable records, diagnostics, or telemetry. See Discord's Modify Guild endpoint and permission flags.

Canonical source: docs/reference.md