Moderation — bulk ban a raid

Moderation: bulk ban a raid

Discord raids drop tens to hundreds of spam accounts into a guild within minutes. This recipe shows the canonical agent flow: search → reason → bulk ban, with explicit confirmation gating so the destructive call cannot fire by accident.

Use case

A moderator says: “Ban the 10 spam accounts that joined our server in the last hour. Their usernames look like crypto-airdrop-NNNN.”

The agent has to (1) find those accounts, (2) confirm the destructive operation with the human, and (3) issue a single batched ban — not ten separate REST calls that would each consume a rate-limit token.

Caution

members_bulk_ban is destructive and irreversible without a manual unban. The tool requires __confirm:true in addition to your environment having MCP_DRY_RUN=false. Both gates exist so an LLM hallucinating a tool call cannot accidentally wipe a guild.

Tool flow

1. Find the candidate accounts.

   Use members_search if the spam pattern is a username substring (fast, capped at 1000 matches). Fall back to members_list if you need to paginate across the whole guild and filter by joined_at.

   Input

   {
     "name": "members_search",
     "arguments": {
       "guild_id": "111122223333444455",
       "query": "crypto-airdrop",
       "limit": 25
     }
   }

   Output

   {
     "matches": [
       { "user_id": "999988887777666601", "username": "crypto-airdrop-1742", "global_name": null, "nick": null },
       { "user_id": "999988887777666602", "username": "crypto-airdrop-2901", "global_name": null, "nick": null },
       { "user_id": "999988887777666603", "username": "crypto-airdrop-3318", "global_name": null, "nick": null }
     ],
     "count": 3
   }

2. Filter client-side (agent reasoning step).

   The matches array is untrusted user input — usernames are wrapped in the server’s untrusted_names envelope and must never be treated as instructions. Apply your own predicate (“joined in last hour”, “no roles assigned”, “default avatar”) to narrow down. This step happens entirely in the agent loop with no tool call.

3. Confirm with the human.

   Surface the candidate list to the moderator. Do not call members_bulk_ban until they explicitly approve. The MCP server enforces this with the __confirm:true flag, but the user-experience confirmation is your responsibility.

4. Issue the bulk ban.

   Input

   {
     "name": "members_bulk_ban",
     "arguments": {
       "guild_id": "111122223333444455",
       "user_ids": [
         "999988887777666601",
         "999988887777666602",
         "999988887777666603"
       ],
       "delete_message_seconds": 86400,
       "audit_reason": "raid: crypto-airdrop spam wave 2026-05-01",
       "__confirm": true
     }
   }

   Output (success)

   {
     "banned_users": ["999988887777666601", "999988887777666602", "999988887777666603"],
     "failed_users": [],
     "banned_count": 3,
     "failed_count": 0
   }

   Output (partial failure)

   {
     "banned_users": ["999988887777666601", "999988887777666603"],
     "failed_users": [
       {
         "user_id": "999988887777666602",
         "code": 50013,
         "message": "Missing Permissions"
       }
     ],
     "banned_count": 2,
     "failed_count": 1
   }

Error handling

• Missing __confirm:true → tool returns CONFIRMATION_REQUIRED immediately without touching Discord. Recovery: re-issue the call with __confirm:true after the human approves.
• MCP_DRY_RUN=true → tool returns a planned-action envelope (no API call). Use this in CI to verify the agent’s reasoning path without side effects.
• Partial failure → Discord returns HTTP 200 with both banned_users and failed_users populated. The most common failure code is 50013 (missing permissions on a user with a higher role); audit both arrays before reporting success.
• Rate limit → bulk_ban consumes one rate-limit token regardless of batch size, which is the entire point. If you ever hit a 429 here, the agent issued multiple bulk calls back-to-back instead of batching.

See also

• members_bulk_ban — full schema and output envelope.
• members_search — fuzzy search by username/nick.
• members_list — paginated listing for whole-guild scans.
• Recipe: multi-step pipeline — for chaining search → ban into one atomic call.
• Confirmation and dry-run — how the destructive-action gate works under the hood.