GuildBridge

About

There is no official Discord MCP server, yet much of the coordination with contributors in the MCP community happens on Discord. GuildBridge fills that gap for me — it gives MCP clients authenticated, permission-aware access to Discord servers so that AI agents can read, search, and post messages where the conversation is already happening. It very much came to life on the heels of a problem that I had that I solved by building my own MCP server.

Prerequisites

• Node.js (v18+)

• A Cloudflare account (using the free tier is sufficient)

• A Discord application with:

  • A bot user added to the servers you want to access

  • OAuth2 configured (client ID + secret)

Discord App Setup

1. Go to the Discord Developer Portal and create (or select) an application.

2. Under Bot, click "Reset Token" to get your bot token. Save it.

3. Under OAuth2, note the Client ID and Client Secret.

4. Under OAuth2 > Redirects, add your callback URL:

   • Local dev: http://localhost:8788/callback

   • Production: https://<your-worker>.workers.dev/callback (you will get this URI later when you deploy your MCP server to Cloudflare)

5. Under OAuth2 > Scopes, ensure identify and guilds are selected.

6. Under Bot > Privileged Gateway Intents, enable Message Content Intent if you want full message content in search results.

7. Invite the bot to your server(s) using the OAuth2 URL Generator with the bot scope and these permissions: View Channels, Read Message History, Send Messages.

Local Development

# Install dependencies
npm install

# Copy the example files and fill in your values
cp wrangler.jsonc.example wrangler.jsonc
cp .dev.vars.example .dev.vars

# Start the dev server
npm run dev

The server runs at http://localhost:8788. The MCP endpoint is at /mcp.

.dev.vars

Deploy to Cloudflare

The Worker binds to three stateful Cloudflare resources: a KV namespace (OAuth state + allowlist), a D1 database (audit log), and a Zero Trust Access application (gates /admin). You can provision all three at once with Terraform, or create them individually with the wrangler CLI.

Option A — Terraform

Provisions KV, D1, and the Access app + policy in one shot. Requires a Cloudflare API token with Workers KV Storage:Edit, D1:Edit, and Access: Apps and Policies:Edit scopes.

cd terraform
cp terraform.tfvars.example terraform.tfvars
# edit terraform.tfvars — set account ID, worker hostname, admin emails

export CLOUDFLARE_API_TOKEN=...
terraform init
terraform apply

Wire the outputs into your config:

Then apply the D1 schema, set the remaining secrets, and deploy:

cd ..
npx wrangler d1 migrations apply "$(terraform -chdir=terraform output -raw d1_database_name)" --remote
npx wrangler secret bulk .dev.vars
terraform -chdir=terraform output -raw cf_access_aud | npx wrangler secret put CF_ACCESS_AUD
npm run deploy

If you used Terraform, skip the Setup subsections under Admin Panel and Observability — those resources already exist.

Option B — Manual (wrangler CLI)

# Create the KV namespace (https://developers.cloudflare.com/kv/)
npx wrangler kv namespace create OAUTH_KV

Copy the output id into wrangler.jsonc replacing PLACEHOLDER_KV_ID. (D1 and Access setup are covered under Observability and Admin Panel below.)

# Set secrets (https://developers.cloudflare.com/workers/configuration/secrets/)
npx wrangler secret bulk .dev.vars

# Deploy
npm run deploy

After deploying, Wrangler will print your worker URL (e.g. https://guildbridge.<your-subdomain>.workers.dev). Add https://<your-worker-url>/callback as a redirect URI in the Discord Developer Portal.

Connect an MCP Client

Point any MCP-compatible client at the server URL:

https://<your-worker>.workers.dev/mcp

Or locally:

http://localhost:8788/mcp

To test with the MCP Inspector:

npx @modelcontextprotocol/inspector@latest

Enter the URL above, complete the Discord OAuth flow, and the tools will become available.

Tools

Admin Panel

The admin panel at /admin lets you add and remove allowed Discord users at runtime, without redeploying. The allowlist is stored in KV and is the sole source the OAuth callback checks. The allowlist is fail-closed — an empty list rejects everyone, so you must seed at least one user via /admin before the first OAuth login will succeed.

Setup

1. In the Cloudflare Zero Trust dashboard, create an Access Application for <your-worker-domain>/admin*.

2. Configure an identity provider (email OTP, Google, etc.).

3. Copy the Application Audience (AUD) tag and set it as the CF_ACCESS_AUD secret.

4. Set the CF_ACCESS_TEAM_DOMAIN secret to your Zero Trust team name.

Once deployed, visit https://<your-worker>.workers.dev/admin to manage the allowlist.

For local development, set DEV_SKIP_CF_ACCESS=true in .dev.vars to bypass CF Access JWT validation, then visit http://localhost:8788/admin.

Observability

Every MCP tool invocation is audited. Events are dual-written to D1 (ordered audit trail, queryable from the admin panel's Activity tab) and Analytics Engine (fire-and-forget metrics, queried via the Cloudflare dashboard SQL API).

Captured per event: timestamp, tool name, Discord user ID + username, outcome (ok/error), duration, guild_id (when present), channel_id (when present), created message_id (for send_message/reply_to_message), error message (on failure). Message content and search queries are never captured.

Setup

# Create the D1 database (one-time)
npx wrangler d1 create guildbridge-audit

Copy the output database_id into wrangler.jsonc replacing PLACEHOLDER_D1_ID, then apply the schema:

# Local dev
npx wrangler d1 migrations apply guildbridge-audit --local

# Production
npx wrangler d1 migrations apply guildbridge-audit --remote

Analytics Engine requires no setup — the TOOL_AUDIT binding in wrangler.jsonc is enough. In local dev, writeDataPoint is a no-op stub; it only writes when deployed.

Querying

Admin panel: https://<your-worker>.workers.dev/admin → Activity tab. Filter by tool or user ID.

D1 directly:

npx wrangler d1 execute guildbridge-audit --command \
  "SELECT * FROM audit_log ORDER BY ts DESC LIMIT 20"

Analytics Engine (aggregates):

npx wrangler analytics-engine sql \
  "SELECT blob1 AS tool, count() AS calls, avg(double1) AS avg_ms
   FROM guildbridge_tool_calls
   WHERE timestamp > now() - INTERVAL '7' DAY
   GROUP BY tool"

Field mapping: indexes[0] = userId, blobs = [tool, username, outcome, guildId, channelId, messageId, error], doubles = [durationMs].

Access Control

Every tool call goes through a layered access check before touching the Discord API. Guild membership is verified via the user's OAuth token, and channel visibility is enforced by computing Discord's permission algorithm from the bot's perspective.

flowchart TD
    A[Tool call] --> B{Channel or guild scoped?}

    B -->|Guild scoped| C[assertGuildAccess]
    B -->|Channel scoped| D[assertChannelAccess]

    C --> E[Fetch user guilds via OAuth token]
    E --> F{User is member?}
    F -->|No| G[Access denied]

    D --> H[Fetch channel info via bot token]
    H --> I{Channel in a guild?}
    I -->|No| G
    I -->|Yes| C

    F -->|Yes| J[getGuildPermContext]
    J --> K[Fetch guild roles + member roles + guild info]
    K --> L{User is guild owner?}
    L -->|Yes| M[Access granted]
    L -->|No| N[computePermissions]

    N --> O[Base: @everyone role perms]
    O --> P[OR in member role perms]
    P --> Q{ADMINISTRATOR set?}
    Q -->|Yes| M
    Q -->|No| R[Apply @everyone channel overwrite]
    R --> S[Apply matching role channel overwrites]
    S --> T[Apply member-specific channel overwrite]
    T --> U{VIEW_CHANNEL set?}
    U -->|Yes| M
    U -->|No| G

For list_channels and search_messages, the same permission computation is applied as a post-filter — channels the user can't see are stripped from results.

Token Usage

GuildBridge uses two distinct Discord tokens with intentionally separate roles:

The bot token never leaves the server. The user's Discord OAuth token is obtained during the OAuth2 login flow, embedded into an encrypted MCP access token, and returned to the MCP client. GuildBridge does not store the user's token server-side — the MCP client holds the encrypted token and sends it with each request, where it is decrypted to extract the OAuth token for guild membership checks.

sequenceDiagram
    participant Client as MCP Client
    participant Server as GuildBridge
    participant Discord as Discord API

    note over Client,Discord: OAuth Flow (one-time setup)
    Client->>Server: Connect to /mcp
    Server-->>Client: 401 — authenticate via OAuth
    Client->>Server: /authorize
    Server->>Discord: Redirect to Discord OAuth
    Discord-->>Server: /callback with auth code
    Server->>Discord: Exchange code for user OAuth token
    Discord-->>Server: User OAuth token
    Server-->>Client: Encrypted MCP token (contains user OAuth token)

    note over Client,Discord: Tool Calls (ongoing)
    Client->>Server: Tool call + MCP token (Bearer)
    Server->>Server: Decrypt MCP token → extract user OAuth token
    Server->>Discord: Verify guild membership (Bearer user OAuth token)
    Discord-->>Server: User's guild list
    Server->>Discord: Execute tool action (Bot token from env)
    Discord-->>Server: API response
    Server-->>Client: Tool result

During the OAuth flow, short-lived session state is managed via:

• CSRF token — HTTP-only cookie, validates the approval form submission (600s TTL)

• State token — stored in Cloudflare KV, binds the OAuth request across redirects (600s TTL)

• Approved clients cookie — HMAC-signed, lets returning users skip the approval dialog (30 days)

Contributing

See CONTRIBUTING.md for setup instructions, code style guidelines, and how to submit changes. Please also review the AI Usage Policy before contributing.