Reviewed additive channel creation

Channel creation has no immediate-call path. Set capabilities.channelCreation: true and list every eligible guild in scopes.channelCreationGuildIds. The channel-creation guild allowlist must be a subset of readScope.guildIds when the read allowlist is present. Grant the bot Manage Channels and View Channels at the guild and, when used, exact parent category. View Channels is required so the planner can collect the strongest available collision and capacity evidence.

The narrow surface creates only categories, text channels, and forum channels. A category accepts only its exact name. Text and forum channels may also specify an exact parent category ID, topic, NSFW flag, slowmode from 0 through 21600 seconds, and default thread archive duration of 60, 1440, 4320, or 10080 minutes. Every request requires a non-blank Discord audit-log reason whose URL-encoded form fits Discord's 512-character limit and a unique operation key containing 16 through 128 safe ASCII characters. The workflow never creates permission overwrites, moves channels, changes positions, edits existing channels, deletes channels, or performs rollback.

1. Call plan_channel_creation with the exact guild, channel kind, name, optional settings, audit reason, and one-shot operation key.
2. Review the exact guild and optional parent IDs, untrusted names, desired settings, guild and parent permission evidence, visibility-bounded inventory, warnings, hashed operation key, action, and keyed digest.
3. If the action is none, the exact visible channel already has the requested state and no confirmation or write is needed.
4. Call execute_channel_creation with identical inputs plus the digest.
5. Approve the signed MCP confirmation only if every exact ID, setting, warning, reason, operation-key hash, and digest remains intended.
6. Review the returned channel ID, readback state, activity ID, and outcome before any follow-up.

Planning verifies the exact guild, connector bot membership, complete role evidence, effective guild permissions, the optional exact parent category and its overwrite evidence, logical-name collision candidates, visible guild capacity, and visible parent-child capacity. Logical matching normalizes Unicode compatibility forms, letter case, spaces, underscores, and hyphens. Multiple matches are ambiguous and fail closed. One matching channel with different settings is a conflict rather than an implicit edit. Discord channel inventories can omit channels that the bot cannot view, so every plan labels collision and capacity evidence as visibility-bounded.

The process-keyed digest covers the normalized request, raw operation key inside the keyed input, operation-key hash, bot identity and roles, effective permissions, relevant role state, guild owner, parent overwrites, logical-name candidates, visible child IDs, and visible channel count. A connector restart invalidates the digest. Immediately before approval, the MCP adapter rebuilds the plan. Immediately before mutation, the service rebuilds it again and requires the same digest.

Discord's create-channel endpoint has no idempotency token. Before the single POST, the connector atomically reserves the operation-key hash in a durable private receipt beside the configured activity file, then appends a pending content-free activity record. The raw key, channel name, topic, audit reason, role names, and other Discord content are absent from both records. A reserved key is permanently spent, including after a known failure or an uncertain timeout, transport error, or Discord 5xx response. Do not retry it. Inspect the exact guild and Discord audit log before considering a fresh reviewed request with a new key, especially after an uncertain result.

Inside one connector process, executions for the same guild, parent, and normalized logical name serialize across different operation keys and supported channel kinds. A queued execution rebuilds its plan after the preceding write, and it is blocked without reserving its key if that preceding write ends uncertain. The production facade additionally acquires durable exact guild channel-collection and optional parent-channel claims, so connector processes sharing the activity-state root exclude overlapping channel creation and retain the claims after uncertainty. This closes connector-local races without pretending that Discord supplies a global uniqueness constraint.

After a successful POST, the connector validates the response identity and performs an exact channel GET. A matching readback returns completed; a safe identity with server-adjusted settings returns completed-with-drift and the observed values. A write whose receipt or final activity update fails reports that local recording failure without hiding the known channel ID. The connector never retries the POST and never deletes a newly created channel as compensation. See Discord's create guild channel reference.

Canonical source: docs/reference.md