Reviewed authenticated bot-profile lifecycle

get_current_bot_profile provides an explicit privacy-bounded read of the authenticated current bot instead of exposing the complete Discord User object. Enable it with capabilities.botProfileAudit: true and include bot-profile in tools.toolsets. The read freshly verifies the configured application and bot IDs, requires Discord to identify the current user as that exact bot, and returns only the IDs, transient untrusted username, avatar and banner presence plus animation booleans, and an unknown-field count. It omits media hashes, email, locale, account flags, decoration and collectible data, raw fields, and every unknown value. It creates no cache, activity record, operation receipt, or telemetry payload containing profile text.

Reviewed changes require capabilities.botProfileChanges: true in addition to audit. They use the verified bot token and require no caller-selected application or bot ID, guild allowlist, guild permission, privileged intent, Gateway connection, or Discord audit-log reason. This policy fragment enables username changes plus avatar and banner clearance; adding one or more canonical owned roots also enables image replacement:

{
  "capabilities": {
    "botProfileAudit": true,
    "botProfileChanges": true
  },
  "storage": {
    "botProfileRoots": [
      "/absolute/process-owned/profile-images"
    ]
  },
  "tools": {
    "toolsets": [
      "bot-profile"
    ]
  }
}

The fragment is not a standalone configuration. Keep the existing credential reference, pinned identity, read scope, limits, runtime, Gateway, observability, and any other selected policy unchanged. An empty or omitted storage.botProfileRoots is valid and deliberately leaves local image replacement unavailable.

Each strict change request contains acknowledgeApplicationWideChange: true, a bounded ephemeral reviewReason, a unique one-shot operationKey, and at least one of username, avatar, or banner. Usernames must contain 2 through 32 Unicode scalar values, preserve canonical surrounding and internal spacing, and satisfy Discord's documented prohibited-substring and reserved-name rules. An image change is exactly { "action": "clear" } or { "action": "set", "filePath": "/absolute/path" }. Clear sends JSON null; set accepts only a stable process-owned regular single-link JPEG, PNG, or GIF file contained by a configured root and no larger than 8 MiB. Remote URLs, Discord CDN references, data URIs, base64 input, raw bytes, relative paths, symlinks, hardlinks, foreign-owned files, directories, unstable reads, unsupported formats, and extension-only format claims are rejected before planning.

Planning binds the freshly verified application and bot identities, complete editable current state, exact desired presentation, requested and changed fields, review reason, one-shot key hash, and, for each replacement image, canonical file identity, byte snapshot, decoded format and dimensions, animation evidence, and a domain-separated keyed content digest. Plan output exposes the transient current and desired username and review-safe file metadata, but never a local path, raw image hash, image bytes, raw operation key, or raw Discord object. A matching username and clearance of an already absent image are safe no-ops. An image replacement always remains a real write because Discord does not expose enough evidence to prove that the remote bytes already match.

Use the lifecycle in this order:

1. Call get_current_bot_profile when the current presentation needs inspection.
2. Call plan_bot_profile_change with the exact sparse request and retain the returned keyed digest.
3. Review both verified identities, application-wide impact, current and desired presentation, requested and changed fields, owned-file evidence, privacy omissions, ephemeral rationale boundary, one-shot key hash, risks, warnings, creation time, and verification limits.
4. Call execute_bot_profile_change with the identical request and digest. A compatible MCP host must separately grant write approval and return the signed interactive confirmation requested by the server.
5. The connector rebuilds the complete remote-and-file plan immediately before mutation and stops on identity, profile, file, request, rationale, key, or digest drift.
6. After a durable application-wide claim, one-shot reservation, and pending content-free activity record succeed, the connector sends one sparse non-retried PATCH /users/@me, strictly validates its complete projected result, and performs an independent fresh GET /users/@me readback.

Username and clear operations require exact response and readback equality for the requested field. Image replacement requires both reads to prove presence and the reviewed animation state, then requires the two returned editable profiles to agree; Discord may transform an upload and exposes only a media hash, so the workflow explicitly does not claim remote byte equality. Unrequested username, avatar, and banner state must remain unchanged. The Discord User resource defines the three editable fields and the Image Data contract defines the accepted JPEG, PNG, and GIF data URI formats; the connector constructs that transport encoding internally from the reviewed owned-file bytes.

A known pre-response Discord 4xx refusal is failed. Transport ambiguity, server failure, malformed or mismatched mutation evidence, unreadable or divergent readback, and failed durable receipt finalization are uncertain and may have completed. Every reserved key stays spent; an uncertain result retains the application-wide bot-profile claim and quarantines queued same-application work until an operator inspects the exact bot presentation and resolves the durable evidence. The connector never retries, compensates, restores, or rolls back automatically.

Bot-profile activity records contain only the application and bot IDs, three changed-field booleans, plan digest, operation-key hash, timestamps, fixed verification and outcome values, activity ID, and sanitized error category. Operation receipts use the same content-free application scope. Username, review reason, local paths, file metadata, image dimensions, media hashes, content digests, image bytes, raw operation keys, raw requests and responses, credentials, and transport causes never enter durable records. review_bot_profile_change provides the same exact validation and a plan-only guided review, and explicitly forbids execution.

Canonical source: docs/reference.md