How a tool call works

Before you begin

• Complete the quickstart and keep the test message’s channel_id, message_id, and jump_url.
• Continue using the private test server for every example on this page.

The quickstart used an explicit tool name and Discord ID to make the final call predictable:

Use messages_send with channel_id 112233445566778899 and content hello from discord-mcp. Do not call any other tool.

This avoided two common ambiguities: messages_send does not accept a channel name, and the server does not perform a separate human confirmation for this ordinary write. The prompt above is the call you already completed; you do not need to send the message again.

Request flow

1. Discovery. The client obtains the tool catalog through MCP tools/list.
2. Selection. The client selects the exact messages_send identifier.
3. Validation. discord-mcp validates channel_id as a Discord snowflake and content as a non-empty string of at most 2,000 characters.
4. Execution. The server applies its middleware and resilience policy, then sends an HTTP request to Discord’s create-message endpoint.
5. Result. The tool returns a text summary for the conversation and structured JSON that another tool can reuse.

The MCP call arguments are:

{
  "name": "messages_send",
  "arguments": {
    "channel_id": "112233445566778899",
    "content": "hello from discord-mcp"
  }
}

The structured result has this shape:

{
  "message_id": "112233445566778900",
  "channel_id": "112233445566778899",
  "jump_url": "https://discord.com/channels/999000999000999000/112233445566778899/112233445566778900",
  "timestamp": "2026-08-01T10:00:00.000Z"
}

The IDs and timestamp above are examples. The keys match the runtime output schema.

Reuse structured output

An MCP client can take message_id and channel_id from the result and pass them to a follow-up tool such as reactions_create, messages_pin, or messages_edit. This is safer than asking the model to reconstruct identifiers from prose.

Safety boundary

Caution

MCP annotations describe risk; they do not grant permissions and they do not guarantee a client will ask first. messages_send writes immediately when Discord accepts the request. Only reference pages marked Confirmation required use the __confirm plus MCP_DRY_RUN contract.

The strongest boundary is the bot’s Discord role. Give it access only to the servers, channels, and actions required by your workflows.

Common failures

Result	Meaning	Next action
Invalid arguments	A required field is missing or malformed.	Copy the numeric channel ID and keep content within 2,000 characters.
401	The token is invalid or revoked.	Reset it in the Developer Portal and update the local config.
403	The bot lacks channel permissions.	Check View Channel and Send Messages, including channel overrides.
404	Discord cannot find or expose that channel to the bot.	Call channels_list for the correct guild and reuse the returned ID.

See the exact messages_send reference or return to Troubleshooting.

Tutorial complete

• I can identify the tool name and arguments in the MCP request.
• I can identify message_id, channel_id, jump_url, and timestamp in the result.
• I understand that messages_send writes immediately and is not confirmation-gated.
• I know to reuse IDs from structured output instead of reconstructing them from prose.