Architecture

Trace a tool call from MCP input to Discord REST. Tools live in a Sapphire-style registry and pass through six middleware stages: telemetry → default guild → validation → category gate → preconditions → audit. The REST adapter adds bulkhead, circuit-breaker, retry, and timeout policies. Optional Gateway mode emits notifications for five URI keys and falls back to REST-only startup when the Gateway connection cannot boot.

System design

graph TD
  Client[MCP client] --> Transport[InMemoryTransport / stdio / Streamable HTTP]
  Transport --> Server[MCP SDK v2 Server]
  Server --> MW[Middleware chain]
  MW --> Tool[Tool piece]
  Tool --> REST[Resilient REST adapter]
  REST --> Discord[Discord REST API]
  Tool -. optional .-> Sampling[Client LLM via sampling]
  Server -. optional .-> Gateway[Gateway client]
  Gateway --> DiscordWS[Discord Gateway WebSocket]

• MCP client sends JSON-RPC tools/call over stdio or Streamable HTTP.
• Transport owns JSON-RPC framing; the CLI defaults to stdio, serve --http provides stateless Streamable HTTP, and tests use InMemoryTransport. The HTTP entry negotiates MCP 2026-07-28 and retains a stateless 2025-era compatibility path.
• MCP SDK v2 Server bridges MCP to the piece registry and hosts the middleware, tool, precondition, and resource stores.
• Middleware chain applies telemetry, default guild, validation, category gate, preconditions, and audit before execution.
• Tool piece implements one of the 209 tools, using Discord REST, MCP sampling back to the client for intelligence, or caller-invoked external inspiration discovery.
• REST adapter wraps @discordjs/rest in Cockatiel bulkhead, circuit-breaker, retry, and timeout policies.
• Gateway client is optional under --gateway; it emits notifications for five URI keys but does not add resource list/read handlers.

Registry and repository shape

discord-mcp uses Sapphire’s explicit “piece + store” model. Tool and Precondition classes are registered by server.ts; boot does not scan the filesystem. The stores provide lookup by name, while the container supplies the configured REST client, logger, and config to tool pieces.

This keeps tool construction consistent, but registration is intentionally explicit: adding a tool also requires adding it to server.ts.

packages/
  mcp-core/                # Tools, middleware, resilience policy
    src/
      tools/               # 209 tool definitions
      middleware/          # 6 stages + compose
      preconditions/       # ConfirmRequired, CategoryEnabled
      pieces/              # Tool and Precondition base classes
      stores/              # Tool/precondition lookup + resources
      rest/                # Cockatiel-wrapped @discordjs/rest
      gateway/             # Optional discord.js client
      pipeline/            # mcp_pipeline executor
      errors/              # Error hierarchy + formatErrorForUser
      audit/               # Audit sinks + redaction
      telemetry/           # OTel boot + metrics
  mcp-server/              # CLI, stdio, and Streamable HTTP transport wiring

mcp-core has no transport assumptions. mcp-server is the thin shell that wires it to stdio or Streamable HTTP, OpenTelemetry, and signal handling. The remote HTTP shell uses the SDK v2 per-request handler factory to create a fresh core runtime per request, so it does not share MCP session state. Its bearer-token deployment model is documented in OpenAI remote MCP.

Sources: server.ts, Tool.ts, and ToolStore.ts.

Note

The middleware boundary centralizes validation, category restriction, confirmation, audit, and observability. Tools still need registration and tests, but do not reimplement those controls.

Explore a subsystem

Middleware chainThe ordered target, validation, scope, write, confirmation, telemetry, and audit controls wrapping every tool call.

Components V2The V2 layout primitives (Container, Section, MediaGallery, ActionRow), the schema validator, the preview renderer, the 5 templates, and the flags=32768 contract.

PipelineThe mcp_pipeline executor: sequential fail-fast calls, {{stepN.path}} interpolation, recursion guard, and partial-failure semantics.

GatewayThe optional --gateway mode: five event URI keys, an allowlisted live guild snapshot, in-memory subscriptions, debounce, and REST-only fallback.

Error handlingThe error hierarchy (client vs server), formatErrorForUser shape, recovery-hint contract, DRY_RUN_PREVIEW pattern, Cockatiel mappings.

ConfirmationThe payload-bound Components V2 approval and the __confirm:true + MCP_DRY_RUN=false guard for explicitly registered high-risk tools.

SamplingZero-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 limitsDiscord’s global and route buckets, the @discordjs/rest scheduler, and the boundary with local resilience policies.

Choose a path

If you’re a contributor, start with the system design above, then jump to the 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.

Related

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