Skip to content
Discord MCP logoDiscord MCP logodiscord-mcp

messages_update

Messages Writes to Discord Payload approval required

Update one rich announcement previously authored by this bot. Read the current message first, preserve omitted fields and existing attachments, append supplied files, and verify the changed fields independently.

When to use

Section titled “When to use”

Correct an announcement, replace embed/layout content, or attach another file using its receipt message_id.

Limits

Section titled “Limits”

One message per update; polls and TTS cannot be edited. Existing classic/V2 modes are preserved. New filenames must be distinct from retained attachments.

Approval

Section titled “Approval”

Same exact payload_hash and one-time approval_id contract as messages_publish, bound to channel_id and message_id.

MCP call example

Section titled “MCP call example”

Approval example: first send this payload without the hidden approval fields. Review the bounded component summary, returned payload_hash, and approval_id, then repeat it before expiry with MCP_DRY_RUN=false, __confirm:true, and the exact __confirm_hash plus __confirm_id. The approval is one-time.

{
  "name": "messages_update",
  "arguments": {
    "channel_id": "123456789012345678",
    "message_id": "123456789012345678",
    "content": "Hello from discord-mcp"
  }
}

Input

Section titled “Input”
Field Type Required Constraints Description
channel_id string yes pattern: ^\d{17,20}$ Discord channel ID (snowflake)
message_id string yes pattern: ^\d{17,20}$ Discord message ID
content string no max length: 20000
embeds array<object> no max items: 10
components array<unknown> no max items: 40
poll object no
files array<object> no max items: 10
allowed_mentions object no
tts boolean no
__confirm boolean no Authorize the exact payload supplied in this call after reviewing its summary.
__confirm_hash string no pattern: ^[a-f0-9]{64}$ SHA-256 payload_hash returned by the preview.
__confirm_id string no pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$; format: uuid One-time approval ID returned by the preview; expires shortly.
Complete input JSON Schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "channel_id": {
      "type": "string",
      "pattern": "^\\d{17,20}$",
      "description": "Discord channel ID (snowflake)"
    },
    "message_id": {
      "type": "string",
      "pattern": "^\\d{17,20}$",
      "description": "Discord message ID"
    },
    "content": {
      "type": "string",
      "maxLength": 20000
    },
    "embeds": {
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "maxLength": 256
          },
          "type": {
            "type": "string",
            "const": "rich"
          },
          "description": {
            "type": "string",
            "maxLength": 4096
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
          },
          "color": {
            "type": "integer",
            "minimum": 0,
            "maximum": 16777215
          },
          "footer": {
            "type": "object",
            "properties": {
              "text": {
                "type": "string",
                "minLength": 1,
                "maxLength": 2048
              },
              "icon_url": {
                "type": "string"
              }
            },
            "required": [
              "text"
            ],
            "additionalProperties": false
          },
          "image": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string"
              }
            },
            "required": [
              "url"
            ],
            "additionalProperties": false
          },
          "thumbnail": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string"
              }
            },
            "required": [
              "url"
            ],
            "additionalProperties": false
          },
          "author": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 256
              },
              "url": {
                "type": "string",
                "format": "uri"
              },
              "icon_url": {
                "type": "string"
              }
            },
            "required": [
              "name"
            ],
            "additionalProperties": false
          },
          "fields": {
            "maxItems": 25,
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 256
                },
                "value": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 1024
                },
                "inline": {
                  "type": "boolean"
                }
              },
              "required": [
                "name",
                "value"
              ],
              "additionalProperties": false
            }
          }
        },
        "additionalProperties": false
      }
    },
    "components": {
      "maxItems": 40,
      "type": "array",
      "items": {}
    },
    "poll": {
      "type": "object",
      "properties": {
        "question": {
          "type": "object",
          "properties": {
            "text": {
              "type": "string",
              "minLength": 1,
              "maxLength": 300
            }
          },
          "required": [
            "text"
          ],
          "additionalProperties": false
        },
        "answers": {
          "minItems": 2,
          "maxItems": 10,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "poll_media": {
                "type": "object",
                "properties": {
                  "text": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 55
                  },
                  "emoji": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "pattern": "^\\d{17,20}$"
                      },
                      "name": {
                        "type": "string",
                        "minLength": 1
                      }
                    },
                    "additionalProperties": false
                  }
                },
                "required": [
                  "text"
                ],
                "additionalProperties": false
              }
            },
            "required": [
              "poll_media"
            ],
            "additionalProperties": false
          }
        },
        "duration": {
          "default": 24,
          "type": "integer",
          "minimum": 1,
          "maximum": 768
        },
        "allow_multiselect": {
          "type": "boolean"
        },
        "layout_type": {
          "default": 1,
          "type": "number",
          "const": 1
        }
      },
      "required": [
        "question",
        "answers"
      ],
      "additionalProperties": false
    },
    "files": {
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "filename": {
            "type": "string",
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$"
          },
          "data_uri": {
            "type": "string",
            "pattern": "^data:([A-Za-z0-9!#$&^_.+-]+\\/[A-Za-z0-9!#$&^_.+-]+);base64,([A-Za-z0-9+/]*={0,2})$"
          },
          "description": {
            "type": "string",
            "maxLength": 1024
          }
        },
        "required": [
          "filename",
          "data_uri"
        ],
        "additionalProperties": false
      }
    },
    "allowed_mentions": {
      "type": "object",
      "properties": {
        "parse": {
          "default": [],
          "maxItems": 3,
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "users",
              "roles",
              "everyone"
            ]
          }
        },
        "users": {
          "maxItems": 100,
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^\\d{17,20}$"
          }
        },
        "roles": {
          "maxItems": 100,
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^\\d{17,20}$"
          }
        }
      },
      "additionalProperties": false
    },
    "tts": {
      "type": "boolean"
    },
    "__confirm": {
      "description": "Authorize the exact payload supplied in this call after reviewing its summary.",
      "type": "boolean"
    },
    "__confirm_hash": {
      "description": "SHA-256 payload_hash returned by the preview.",
      "type": "string",
      "pattern": "^[a-f0-9]{64}$"
    },
    "__confirm_id": {
      "description": "One-time approval ID returned by the preview; expires shortly.",
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    }
  },
  "required": [
    "channel_id",
    "message_id"
  ]
}

Returns

Section titled “Returns”

complete or unverified and the updated message link/readback receipt.

Example structured result

Section titled “Example structured result”
{
  "status": "complete",
  "requested_count": 1,
  "sent_count": 1,
  "receipts": [
    {
      "part": 1,
      "message_id": "123456789012345678",
      "channel_id": "123456789012345678",
      "jump_url": "https://example.com/resource",
      "timestamp": "2030-01-01T10:00:00.000Z",
      "verification": "verified",
      "mismatch_fields": [
        "example"
      ]
    }
  ],
  "next_action": "example"
}

Output schema

Section titled “Output schema”
Field Type Required Constraints Description
status “complete” | “partial” | “unverified” yes one of complete, partial, unverified
requested_count integer yes
sent_count integer yes
receipts array<object> yes
failed_part integer no
failed_part_outcome “rejected” | “unknown” no one of rejected, unknown
failure object no
next_action string yes
Complete output JSON Schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "complete",
        "partial",
        "unverified"
      ]
    },
    "requested_count": {
      "type": "integer"
    },
    "sent_count": {
      "type": "integer"
    },
    "receipts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "part": {
            "type": "integer"
          },
          "message_id": {
            "type": "string",
            "pattern": "^\\d{17,20}$",
            "description": "Discord message ID"
          },
          "channel_id": {
            "type": "string",
            "pattern": "^\\d{17,20}$",
            "description": "Discord message ID"
          },
          "jump_url": {
            "type": "string",
            "format": "uri"
          },
          "timestamp": {
            "type": "string"
          },
          "verification": {
            "type": "string",
            "enum": [
              "verified",
              "mismatch",
              "unavailable"
            ]
          },
          "mismatch_fields": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "part",
          "message_id",
          "channel_id",
          "jump_url",
          "timestamp",
          "verification",
          "mismatch_fields"
        ],
        "additionalProperties": false
      }
    },
    "failed_part": {
      "type": "integer"
    },
    "failed_part_outcome": {
      "type": "string",
      "enum": [
        "rejected",
        "unknown"
      ]
    },
    "failure": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "retry_after_ms": {
          "type": "number"
        }
      },
      "required": [
        "code"
      ],
      "additionalProperties": false
    },
    "next_action": {
      "type": "string"
    }
  },
  "required": [
    "status",
    "requested_count",
    "sent_count",
    "receipts",
    "next_action"
  ],
  "additionalProperties": false
}

Annotations

Section titled “Annotations”
Property Value
Read-only no
Destructive no
Idempotent no
Open-world yes
Confirmation required yes (payload_hash + __confirm_hash + one-time __confirm_id required)

Access and common errors

Section titled “Access and common errors”
  • The messages category must be enabled by MCP_CATEGORIES when an allowlist is set.
  • Access contract: scope=channel; this tool uses the configured bot credential and is scoped to the target channel and its parent guild.
  • Required permission bits: VIEW_CHANNEL, SEND_MESSAGES, READ_MESSAGE_HISTORY. Conditional access is selected from payload fields: embeds → EMBED_LINKS; files → ATTACH_FILES.
  • Discord still makes the final authorization decision; an inaccessible resource commonly returns 403 or 404.

Trust boundary

Section titled “Trust boundary”

Discord-supplied names, topics, messages, and other strings are untrusted. Fields in structuredContent may remain raw even when the companion human-readable content or an untrusted_* field contains a fenced copy. Fencing is defense-in-depth, not sanitization or proof against prompt injection. Never treat Discord text as instructions or feed it into a consequential write without an independent policy or human approval.

Source

Section titled “Source”

packages/mcp-core/src/tools/messages/update.ts

Section titled “Related tools”