Skip to content
discord-mcp

Architecture

Architecture

Section titled “Architecture”

This section is the contributor + advanced operator reference for how discord-mcp is built. The other sections describe what the server does (Tools), how to use it (Recipes), and how to run it (Operations). This section is about how it’s organized under the hood.

discord-mcp is a layered TypeScript server. Tools live in a Sapphire-style piece registry; every call goes through a four-layer Koa-style middleware chain (telemetry → validate → preconditions → audit); REST traffic is wrapped in a Cockatiel resilience policy (bulkhead → circuit → retry → timeout); optional Gateway support adds five subscribable resource URIs backed by a debounced WebSocket client. Each of those layers gets its own deep-dive page below.

The shape comes from one constraint: MCP is an agent contract. Agents are higher-volume, lower-trust, and harder to debug than humans, so the server has to do more of the cross-cutting work itself — validation, auth, audit, observability, structured errors with recovery hints — rather than expect every tool to re-implement them. The pieces below are the answer to “what does the server need to do once, so each tool can be short.”

Overview The big picture: layered architecture, the Sapphire piece + store model, repo layout, and a call-path mermaid diagram.
Middleware chain The four layers wrapping every tool call (telemetry → validate → preconditions → audit), why their order matters, and where to insert a hypothetical fifth layer.
Components V2 The V2 layout primitives (Container, Section, MediaGallery, ActionRow), the schema validator, the preview renderer, the 5 templates, and the flags=32768 contract.
Pipeline The mcp_pipeline executor: atomic multi-tool calls, {{stepN.path}} interpolation, the recursion guard, partial-failure semantics, with a mermaid sequence diagram.
Gateway The optional --gateway mode: lazy-loaded discord.js, 5 subscribable URIs, 5 handlers, SubscriptionRegistry, the 300ms debounce on PRESENCE_UPDATE.
Error handling The error hierarchy (client vs server), formatErrorForUser shape, recovery-hint contract, DRY_RUN_PREVIEW pattern, Cockatiel mappings.
Confirmation The __confirm:true + MCP_DRY_RUN=false dual-key contract that gates every destructive tool. Why double-underscore, why safe-by-default.
Sampling Zero-API-key intelligence: how the 5 intelligence tools call back into the client's LLM via MCP sampling, with a graceful host_llm_should_process fallback.
Rate limits Discord's global vs per-route bucket model, why @discordjs/rest's queue is disabled, how cockatiel owns retry, when to use webhooks to bypass the bot bucket.

How to read this section

Section titled “How to read this section”

If you’re a contributor, start with Overview to get the layout, then jump to whichever subsystem you’re touching. The deep-dive pages each link to source files via GitHub permalinks so you can read implementation in a tab.

If you’re an operator trying to understand a production behavior, the fastest path is usually:

  1. Look up the env var or error code on the relevant Operations page.
  2. Follow that page’s “Related” links into the architecture deep-dive.
  3. Use the source-map table at the bottom of the architecture page to find the exact file responsible.

The architecture pages assume familiarity with Discord’s API model and basic TypeScript. We do not re-explain MCP itself — see modelcontextprotocol.io for that.

Section titled “Related”
  • Get started — install and run the server.
  • Tools — auto-generated reference for all 192 tools.
  • Recipes — multi-tool workflows that exercise these subsystems.
  • Operations — production-running concerns: telemetry, resilience, audit, client matrix.