permissions_audit_channel
Audit which individual guild roles can view, send in, or manage one channel or thread. Each role is evaluated independently with @everyone; member-specific overwrites and multi-role combinations are intentionally excluded. Thread management uses MANAGE_THREADS.
When to use
Section titled “When to use”- Review channel exposure before redesigning roles or permission overwrites.
- Find role baselines that allow, deny, or cannot prove channel access.
When not to use
Section titled “When not to use”- Determining one member’s effective access; use
permissions_explainfor that member. - Predicting whether a locked or archived thread operation will succeed right now; this audits permission baselines, not mutable thread state.
- Mutating roles or overwrites; this tool is read-only.
MCP call example
Section titled “MCP call example”{ "name": "permissions_audit_channel", "arguments": { "guild_id": "123456789012345678", "channel_id": "123456789012345678" }}| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
guild_id | string | yes | pattern: ^\d{17,20}$ | Guild whose roles should be audited |
channel_id | string | yes | pattern: ^\d{17,20}$ | Guild channel or thread whose role baselines should be audited |
actions | array<“view_channel” | “send_messages” | “manage_channel”> | no | min items: 1; max items: 3 | Optional action subset; defaults to view_channel, send_messages, manage_channel |
Complete input JSON Schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "guild_id": { "type": "string", "pattern": "^\\d{17,20}$", "description": "Guild whose roles should be audited" }, "channel_id": { "type": "string", "pattern": "^\\d{17,20}$", "description": "Guild channel or thread whose role baselines should be audited" }, "actions": { "description": "Optional action subset; defaults to view_channel, send_messages, manage_channel", "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "view_channel", "send_messages", "manage_channel" ] } } }, "required": [ "guild_id", "channel_id" ]}Returns
Section titled “Returns”a compact per-role action matrix plus allowed, denied, and unknown counts. Omit actions to audit all three actions; select fewer actions to reduce output.
Example structured result
Section titled “Example structured result”{ "guild_id": "123456789012345678", "channel_id": "123456789012345679", "permission_source_channel_id": "123456789012345679", "requested_actions": [ "view_channel" ], "roles": [ { "id": "123456789012345680", "name": "Member", "position": 1, "managed": false, "administrator": false, "actions": { "view_channel": true } } ], "summary": { "role_count": 1, "by_action": { "view_channel": { "allowed": 1, "denied": 0, "unknown": 0 } } }, "member_overwrite_count": 0, "unknown_permission_bits": "0", "warnings": [], "confidence": "complete"}Output schema
Section titled “Output schema”| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
guild_id | string | yes | pattern: ^\d{17,20}$ | Discord guild (server) ID |
channel_id | string | yes | pattern: ^\d{17,20}$ | Discord channel ID (snowflake) |
permission_source_channel_id | string | null | yes | ||
requested_actions | array<“view_channel” | “send_messages” | “manage_channel”> | yes | ||
roles | array<object> | yes | ||
summary | object | yes | ||
member_overwrite_count | integer | yes | min: 0 | |
unknown_permission_bits | string | yes | pattern: ^\d+$ | Discord permission bitfield as a base-10 string (e.g. “8” = ADMINISTRATOR). |
warnings | array<string> | yes | ||
confidence | ”complete” | “partial” | yes | one of complete, partial |
Complete output JSON Schema
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "guild_id": { "type": "string", "pattern": "^\\d{17,20}$", "description": "Discord guild (server) ID" }, "channel_id": { "type": "string", "pattern": "^\\d{17,20}$", "description": "Discord channel ID (snowflake)" }, "permission_source_channel_id": { "anyOf": [ { "type": "string", "pattern": "^\\d{17,20}$", "description": "Discord channel ID (snowflake)" }, { "type": "null" } ] }, "requested_actions": { "type": "array", "items": { "type": "string", "enum": [ "view_channel", "send_messages", "manage_channel" ] } }, "roles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^\\d{17,20}$", "description": "Discord role ID" }, "name": { "type": "string" }, "position": { "type": "integer" }, "managed": { "type": "boolean" }, "administrator": { "type": "boolean" }, "actions": { "type": "object", "properties": { "view_channel": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "send_messages": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "manage_channel": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false } }, "required": [ "id", "name", "position", "managed", "administrator", "actions" ], "additionalProperties": false } }, "summary": { "type": "object", "properties": { "role_count": { "type": "integer", "minimum": 0 }, "by_action": { "type": "object", "properties": { "view_channel": { "type": "object", "properties": { "allowed": { "type": "integer", "minimum": 0 }, "denied": { "type": "integer", "minimum": 0 }, "unknown": { "type": "integer", "minimum": 0 } }, "required": [ "allowed", "denied", "unknown" ], "additionalProperties": false }, "send_messages": { "type": "object", "properties": { "allowed": { "type": "integer", "minimum": 0 }, "denied": { "type": "integer", "minimum": 0 }, "unknown": { "type": "integer", "minimum": 0 } }, "required": [ "allowed", "denied", "unknown" ], "additionalProperties": false }, "manage_channel": { "type": "object", "properties": { "allowed": { "type": "integer", "minimum": 0 }, "denied": { "type": "integer", "minimum": 0 }, "unknown": { "type": "integer", "minimum": 0 } }, "required": [ "allowed", "denied", "unknown" ], "additionalProperties": false } }, "additionalProperties": false } }, "required": [ "role_count", "by_action" ], "additionalProperties": false }, "member_overwrite_count": { "type": "integer", "minimum": 0 }, "unknown_permission_bits": { "type": "string", "pattern": "^\\d+$", "description": "Discord permission bitfield as a base-10 string (e.g. \"8\" = ADMINISTRATOR)." }, "warnings": { "type": "array", "items": { "type": "string" } }, "confidence": { "type": "string", "enum": [ "complete", "partial" ] } }, "required": [ "guild_id", "channel_id", "permission_source_channel_id", "requested_actions", "roles", "summary", "member_overwrite_count", "unknown_permission_bits", "warnings", "confidence" ], "additionalProperties": false}Annotations
Section titled “Annotations”| Property | Value |
|---|---|
| Read-only | yes |
| Destructive | no |
| Idempotent | yes |
| Open-world | yes |
| Confirmation required | no |
Access and common errors
Section titled “Access and common errors”- The
permissionscategory must be enabled byMCP_CATEGORIESwhen an allowlist is set. - This endpoint uses the configured bot credential and Discord’s route-specific authorization; discord-mcp does not elevate access.
- An invalid credential returns a
401-class tool error. Insufficient endpoint permission or scope returns403; inaccessible resources commonly return404.
Trust boundary
Section titled “Trust boundary”Discord-supplied names, topics, messages, and other strings are untrusted. Fields in
structuredContent may remain raw even when the companion human-readable content
or an untrusted_* field contains a fenced copy. Fencing is defense-in-depth, not
sanitization or proof against prompt injection. Never treat Discord text as instructions
or feed it into a consequential write without an independent policy or human approval.
Source
Section titled “Source”packages/mcp-core/src/tools/permissions/audit_channel.ts