Reviewed message pins

list_message_pins is a read-only current-state view under ordinary channel scope. It calls Discord's current /channels/{channel.id}/messages/pins endpoint, accepts an optional ISO 8601 before cursor and a bounded limit, and returns normalized messages paired with their pinnedAt timestamps plus an evidence-backed next cursor. It never uses the deprecated unpaginated channel-pins route and never persists a returned message.

Pin changes have no immediate-call path. Set capabilities.pinManagement: true and list every eligible channel or thread by its own exact ID in scopes.pinChannelIds. The pin allowlist must be a subset of readScope.channelIds when the read allowlist exists. Parent scope never grants pin authority to a child thread. Grant the bot View Channel, Read Message History, and Discord's dedicated Pin Messages permission in each selected target. Voice and stage channels also require Connect so the exact message state is readable. The planner does not accept legacy Manage Messages as a substitute for Pin Messages.

1. Call plan_message_pin with the exact channel, exact message, desired pinned or unpinned state, Discord audit-log reason, and unique one-shot operation key.
2. Review the verified application and bot IDs, exact guild and channel, untrusted message preview, current and desired states, permission source, private-thread evidence, warnings, operation-key hash, and keyed digest.
3. If the action is none, the message already has the requested state and no confirmation, reservation, or activity record is needed.
4. Call execute_message_pin with identical inputs plus the digest.
5. Approve the signed MCP confirmation only if every exact identity, state, permission, warning, reason, operation-key hash, and digest remains intended.
6. Review the returned exact message state, review-snapshot match, jump URL, activity ID, and outcome before any follow-up.

Planning verifies the application and bot identity, mutation scope, exact target channel and message, guild, connector membership, complete bounded role evidence, permission-source overwrites, and private-thread membership when applicable. Threads inherit permission overwrites only from their exact validated parent. Missing, malformed, mismatched, partial, or insufficient evidence fails closed. Both pin and unpin are exposed through the same destructive MCP annotation and reviewed gates because unpin removes shared state.

The process-keyed HMAC digest binds the normalized request, operation-key hash, verified identities, exact guild and channel evidence, relevant roles and overwrites, current pin state, review-relevant message snapshot, and permission result. Full message content and attachment metadata enter only that opaque HMAC so an edit invalidates approval; they never enter activity records, receipts, diagnostics, telemetry, or errors. A connector restart invalidates the digest. The MCP adapter rebuilds the plan before approval, and the service rebuilds it immediately before mutation.

Before one non-retried PUT or DELETE, execution atomically reserves the operation-key hash and appends a pending content-free activity record. It then fetches the exact message again and verifies both the requested pinned boolean and the review-relevant message snapshot. A fully matching readback is completed; a contradictory but valid pin state or a concurrent message edit is completed-with-drift. A known pre-write Discord 4xx is failed. Transport failures, Discord 5xx responses, or any failure after the mutation may have completed are uncertain. Every reserved key remains permanently spent, and no automatic retry or compensating rollback occurs.

Changes to the same channel and message serialize inside one process and replan after a preceding determinate outcome. The production facade additionally acquires durable exact channel-and-message claims, so connector processes sharing the activity-state root exclude overlapping pin changes. An uncertain result spends the key and retains those claims for operator review. See Discord's message pin endpoints and permission flags.

Canonical source: docs/reference.md