Authorization controls which tools a client can access based on assigned scopes. The MCP server uses scopes to enforce security at two levels: tool discovery and tool invocation. Proper configuration ensures that only authorized clients can view and execute specific tools.

The security.authorization.tools property maps tool names (or the keyword default) to arrays of scopes. These scopes determine whether a tool is visible and executable for a client.

Effects of scope mapping:

Here are some of the effects of scope mapping:
  • Discovery filtering—If a client lacks the required scopes, the tool is hidden from discovery.
  • Invocation enforcement—If a client attempts to call a tool without the required scopes, the server returns an insufficient_scope error (HTTP 401) along with metadata that directs the client to obtain the correct scopes.
The following example shows how to configure scope mappings for tools: 

{
  "security": {
    "authorization": {
      "tools": {
        "default": ["mcp_access"],
        "select_prompts": ["prompts.read"],
        "list_all_tags": ["schema.read"],
        "get_tool_schema": ["schema.read"],
        "get_filter_fields": ["schema.read"]
      }
    }
  }

Best practice

Always define a default scope to provide consistent baseline gating for all tools, which ensures that unauthorized clients cannot access tools without explicit permission.