Skip to content
Home › Tool Design & MCP Integration

MCPToolset Allowlist and Denylist

Tool Design & MCP Integration

Definition

The mcp_toolset entry in the tools array configures which tools from a connected MCP server are exposed to Claude, via allowlist or denylist patterns.

Key points

  • mcp_toolset fields: type (must be "mcp_toolset"), mcp_server_name (matches a server name), optional default_config, configs (per-tool overrides keyed by tool name), cache_control.
  • Per-tool config fields: enabled (boolean, default true), defer_loading (boolean, default false).
  • Config merge precedence (high→low): tool-specific configs → set-level default_config → system defaults.
  • Allowlist: default_config: {enabled: false} + explicitly enable specific tools in configs.
  • Denylist: leave default enabled, set enabled: false on unwanted tools in configs (good for making a server read-only).
  • Validation: server must exist and be referenced by exactly one toolset; each server referenced by only one toolset; unknown tool names in configs log a backend warning but produce no error.

Why it matters for the exam

  • Tested as the mechanism to restrict a broad MCP server to a safe subset (e.g. read-only).
  • Know which pattern (default off + enable) is the allowlist vs (default on + disable) the denylist.

Common gotchas

  • Unknown tool names in configs are a warning only, not an error — easy to over-assume a 400.
  • A server must be referenced by exactly one toolset; referencing it from two is invalid.
  • defer_loading is per-tool config, not a security control — see Defer Loading and Tool Search.

See also

Sources

Referenced by