Auth0 Management API Scopes Required for Each MCP Server Tool Category

The Auth0 MCP Server requires specific Auth0 Management API scopes for each tool category, declared in the _meta.requiredScopes field of every tool definition.

The auth0/auth0-mcp-server repository implements a Model Context Protocol (MCP) server that exposes Auth0 Management API operations as callable tools. Each tool explicitly declares its required Auth0 Management API scopes in metadata, allowing the server to enforce authorization before executing operations. Understanding these scope requirements is essential for generating valid access tokens and avoiding 403 Forbidden errors.

How Scope Enforcement Works in the Auth0 MCP Server

The server validates Auth0 Management API scopes using a per-tool metadata system. In src/utils/scopes.ts, the DEFAULT_SCOPES array is defined as empty (lines 8‑9), meaning tools without explicit scope declarations require no authorization.

However, most tools declare specific requirements in their _meta.requiredScopes field. For example, in src/tools/applications.ts (lines 30‑33), the list applications tool declares:

_meta: {
  requiredScopes: ['read:clients']
}

When a request arrives, the server checks the caller's token against these required scopes. If the token lacks any required scope, the server returns a 403 error with a message indicating which Auth0 Management API scope is missing.

Complete Auth0 Management API Scopes Reference by Tool Category

The following sections detail the exact Auth0 Management API scopes required for each tool category implemented in the Auth0 MCP Server.

Applications

The applications tool category manages Auth0 clients (applications). According to src/tools/applications.ts, three distinct scopes are required depending on the operation:

• read:clients – Required for listing applications (lines 30‑33) and retrieving specific application details
• create:clients – Required for creating new applications (lines 39‑40)
• update:clients – Required for updating existing applications (lines 49‑50)

Actions

The actions tool category manages Auth0 Actions for custom login flows. In src/tools/actions.ts, the scope requirements are:

• read:actions – Required for listing and retrieving action details (lines 50‑51)
• create:actions – Required for creating new actions (lines 41‑42)
• update:actions – Required for updating action code and deploying actions (lines 25‑26)

Logs

The logs tool category provides access to Auth0 tenant logs. As defined in src/tools/logs.ts (lines 43‑44), only one scope is required:

• read:logs – Required for querying and retrieving log entries

Forms

The forms tool category manages Auth0 Forms (for custom prompts). According to src/tools/forms.ts:

• read:forms – Required for listing and retrieving forms (lines 22‑23)
• create:forms – Required for creating new forms (lines 100‑101)
• update:forms – Required for updating existing forms (lines 59‑60)

Resource Servers (APIs)

The resource servers tool category manages API definitions. In src/tools/resource-servers.ts:

• read:resource_servers – Required for listing and retrieving API definitions (lines 38‑39)
• create:resource_servers – Required for creating new APIs (lines 57‑58)
• update:resource_servers – Required for updating existing APIs (lines 71‑72)

Application Grants

The application grants tool category manages Machine-to-Machine (M2M) grants. As defined in src/tools/application-grants.ts (lines 34‑35):

• create:client_grants – Required for creating client grants (M2M authorization)

Default Scope Behavior and Utility Functions

Tools that do not explicitly declare _meta.requiredScopes inherit the DEFAULT_SCOPES defined in src/utils/scopes.ts. This constant is an empty array (lines 8‑9), meaning no Auth0 Management API scopes are required for these tools.

The server also provides a getAllScopes() utility function (lines 15‑21 in src/utils/scopes.ts) that aggregates all unique scopes declared across every tool. This function is useful for generating documentation or validating that a token contains all potentially required scopes before execution.

Code Examples: Request Payloads with Required Scopes

The following JSON examples demonstrate how to structure requests to the Auth0 MCP Server for each tool category, with comments indicating the required Auth0 Management API scopes.

Applications – List (requires read:clients)

{
  "tool": "auth0_list_applications",
  "token": "<ACCESS_TOKEN_WITH_read:clients>",
  "parameters": {
    "page": 0,
    "per_page": 10,
    "include_totals": true
  }
}

Applications – Create (requires create:clients)

{
  "tool": "auth0_create_application",
  "token": "<ACCESS_TOKEN_WITH_create:clients>",
  "parameters": {
    "name": "My New SPA",
    "app_type": "spa"
  }
}

Actions – Deploy (requires update:actions)

{
  "tool": "auth0_deploy_action",
  "token": "<ACCESS_TOKEN_WITH_update:actions>",
  "parameters": {
    "id": "act_1234567890"
  }
}

Logs – List (requires read:logs)

{
  "tool": "auth0_list_logs",
  "token": "<ACCESS_TOKEN_WITH_read:logs>",
  "parameters": {
    "take": 50,
    "sort": "date:-1"
  }
}

Forms – Update (requires update:forms)

{
  "tool": "auth0_update_form",
  "token": "<ACCESS_TOKEN_WITH_update:forms>",
  "parameters": {
    "id": "frm_abcdef",
    "name": "Updated Form Title"
  }
}

Resource Servers – Create (requires create:resource_servers)

{
  "tool": "auth0_create_resource_server",
  "token": "<ACCESS_TOKEN_WITH_create:resource_servers>",
  "parameters": {
    "name": "My API",
    "identifier": "https://api.example.com",
    "signing_alg": "RS256"
  }
}

Application Grants – Create (requires create:client_grants)

{
  "tool": "auth0_create_application_grant",
  "token": "<ACCESS_TOKEN_WITH_create:client_grants>",
  "parameters": {
    "client_id": "client_123",
    "audience": "https://api.example.com",
    "scope": ["read:data", "write:data"]
  }
}

If a token lacks any required Auth0 Management API scope, the server returns a 403 Forbidden error with a descriptive message indicating which scope is missing, as implemented in the error handling of each handler file.

Summary

• The Auth0 MCP Server enforces Auth0 Management API scopes through a per-tool metadata system using _meta.requiredScopes.
• Applications require read:clients, create:clients, or update:clients depending on the operation.
• Actions require read:actions, create:actions, or update:actions.
• Logs only require read:logs.
• Forms require read:forms, create:forms, or update:forms.
• Resource Servers require read:resource_servers, create:resource_servers, or update:resource_servers.
• Application Grants require create:client_grants.
• Tools without explicit scope declarations inherit DEFAULT_SCOPES (empty array) from src/utils/scopes.ts, requiring no authorization.
• The getAllScopes() utility aggregates all unique scopes for documentation and validation purposes.

Frequently Asked Questions

What happens if my access token is missing a required Auth0 Management API scope?

The Auth0 MCP Server returns a 403 Forbidden response with a specific error message indicating which scope is missing. For example, if you attempt to list applications without read:clients, the error message will explicitly mention that your token might not have the required read:clients scope.

Can I use a single access token with all scopes for all tool categories?

Yes, you can generate an access token containing all the Auth0 Management API scopes required by the tools you intend to use. The getAllScopes() function in src/utils/scopes.ts (lines 15‑21) can help you identify the complete set of unique scopes across all tool categories for this purpose.

Are there any tools in the Auth0 MCP Server that do not require any scopes?

Yes. Tools that do not explicitly declare a _meta.requiredScopes field inherit the DEFAULT_SCOPES constant from src/utils/scopes.ts, which is defined as an empty array (lines 8‑9). These tools can be invoked with access tokens that have no specific Auth0 Management API scopes assigned.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}