Dis.gg MCP Docs

Usage Guide

This page is the practical reference for calling the public Dis.gg MCP service.

Endpoints #

  • POST /v1: JSON-RPC 2.0 endpoint. This is the recommended transport.
  • GET /v1/tools/list: helper endpoint to list visible tools.
  • POST /v1/tools/list: compatibility alias for the same helper.
  • POST /v1/tools/call: helper endpoint to call one tool without wrapping the request yourself in JSON-RPC.
  • GET /v1/sse: legacy SSE stream.
  • POST /v1/sse/message?sessionId=...: legacy SSE message ingress.
  • GET /healthz: health check.

Required Header #

  • Authorization: Bot <TOKEN>

Even when you use the Dis.gg MCP service from another client, the credential sent to Discord is still a Discord bot token.

Security Headers Worth Using Early #

The most useful request-time controls are:

  • X-Allowed-Methods
  • X-Allowed-Paths
  • X-Target-Guilds
  • X-Target-Channels
  • X-Target-Users
  • X-Permission-Bits
  • X-Privileged-Intents
  • X-Allowed-Mentions
  • X-Current-User
  • X-Current-Guild
  • X-Current-Channel
  • X-Current-Message
  • X-Owner-Access
  • X-Privileged-Call
  • X-Debug-Mode

X-Image-Model is only relevant when you use util_generate_image.

X-Allowed-Mentions is especially useful if you want to keep models from opening mentions more broadly than intended.

X-Current-User is useful when your client already knows which Discord user is already in scope. DM-capable tools can then omit user_id and user_name.

X-Current-Guild is useful when your client already knows which Discord guild is in scope. Many guild-scoped tools can then omit guild_id and guild_name.

X-Current-Channel is useful when a client already knows which Discord channel is handling the current reply. Many channel-scoped tools can then omit channel_id and channel_name. It also lets the Discord MCP service hide or block redundant calls to send_message for that same channel.

X-Current-Message is useful when your client already knows the exact message that triggered the request. When it is combined with X-Current-Guild and X-Current-Channel, the Discord MCP can build a precise context link for DM attribution. The header stays optional context even if the original message is ephemeral or already deleted.

If X-Target-Users: 0 is set, the Discord MCP hides DM-only tools. Otherwise, DM-capable message tools remain available and can accept user_id or user_name instead of a channel.

For some Discord MCP-local tools, tools/list is context-aware. For example, util_generate_image can expose provider-specific inputs when the selected provider supports them, and send_message can be hidden when replying normally is enough.

For exact formats and edge cases, see Headers.

JSON-RPC Example #

Request:

{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}

Response:

{"jsonrpc":"2.0","id":1,"result":{"tools":[...]}}

Helper Endpoint Example #

Request body:

{"name":"get_current_application","arguments":{}}

Typical headers:

  • Authorization: Bot <TOKEN>
  • X-Owner-Access: 1

Error Model #

  • JSON-RPC always answers with HTTP 200 and either result or error.
  • Helper endpoints return Dis.gg MCP service errors as {error}.
  • When Discord answers with JSON, helper endpoints forward that upstream payload with the matching status.
  • X-Response-Src tells you whether the response came from mcp or discord.
  • SSE compatibility requests on /v1/sse/message always return a success HTTP status. When a tool call fails, the Discord MCP sends a structured error result so the client and model can still read the actual failure reason.

Recommended Integration Pattern #

  1. Start with restrictive X-Allowed-Paths and X-Allowed-Methods.
  2. Add X-Target-* restrictions for every user-facing workflow.
  3. Keep X-Permission-Bits as low as possible.
  4. Use X-Allowed-Mentions if your application needs strict mention rules.
  5. Use X-Current-User, X-Current-Guild, X-Current-Channel, and X-Current-Message when your client already knows the active Discord context.
  6. Reserve owner and privileged headers for trusted operator contexts only.
  7. Prefer compact tools such as get_messages_id_range when they fit the use case better than raw Discord payloads.