Skip to main content
For auth providers, credential vault, and scope challenges, see the Authentication overview.

Overview

The Authorities system provides declarative, built-in authorization on tools, resources, prompts, and skills. Instead of writing imperative access-control checks inside every handler, you declare who can access what directly in decorator metadata. Authorities supports four authorization paradigms: These paradigms can be composed using allOf, anyOf, and not combinators to express complex policies. The system consists of two packages:
  • @frontmcp/auth — Core types, evaluation engine, registries, and errors
  • @frontmcp/sdk — Built-in flow stages (checkEntryAuthorities, filterByAuthorities) for enforcement, configured via @FrontMcp({ authorities }) metadata
No plugin required — authorities is a first-class framework feature.

Quick Start

Add the authorities config to your @FrontMcp() decorator and set authorities on any entry.
If a user without the required role calls delete_user, the checkEntryAuthorities flow stage throws an AuthorityDeniedError with MCP error code -32003 before the handler executes.

JWT Claims Mapping

Every identity provider stores roles and permissions in different JWT claim paths. The claimsMapping option tells the engine where to find them.
Auth0 uses namespaced custom claims for roles and the standard permissions claim.
The claimsMapping supports dot-path traversal (e.g., realm_access.roles) and also direct key lookup for namespaced claims containing dots (e.g., https://myapp.com/roles).

Custom Claims Resolver

For more complex scenarios, provide a claimsResolver function instead of (or in addition to) claimsMapping. It takes precedence when both are configured.

Authority Profiles

Profiles are named, reusable authorization policies registered at the server or app level. They let you write authorities: 'admin' instead of repeating the full policy object on every entry.

Registering Profiles

Using Profiles on Entries

When an array of profiles is provided, they are evaluated with AND semantics — every profile must pass for access to be granted.

RBAC

Role-based access control checks the user’s roles and permissions against required values.

Roles

Permissions

Permission checks follow the same all/any semantics as roles.

Combining Roles and Permissions

When both roles and permissions are specified in the same policy, they are combined with AND by default.

ABAC

Attribute-based access control evaluates conditions against a context envelope with four namespaces:

Simple Match

The match field provides simple equality checks. All pairs must match (AND semantics).

Advanced Conditions

The conditions field supports a rich set of operators for more complex checks.

Operator Reference

Dynamic Value References

Condition values can reference runtime data instead of using static literals.

ReBAC

Relationship-based access control delegates checks to an external authorization backend (e.g., SpiceDB, OpenFGA, or a custom database query).

Configuring a Relationship Resolver

First, implement the RelationshipResolver interface and pass it in the authorities config.

Using ReBAC on Entries

Multiple Relationships (AND)

Pass an array of relationship checks. All must pass.

Resource ID Sources

Combinators

For complex authorization requirements, compose policies using allOf, anyOf, not, and the operator field.

allOf (AND)

All nested policies must pass.

anyOf (OR)

At least one nested policy must pass.

not (Negation)

Invert a nested policy.

operator: ‘OR’

By default, top-level fields in a single policy object are combined with AND. Set operator: 'OR' to use OR instead.

Nested Composition

Combinators nest freely for arbitrarily complex policies.

Custom Evaluators

Extend the authorities system with your own evaluators for domain-specific checks.

Defining an Evaluator

Implement the AuthoritiesEvaluator interface.

Registering Evaluators

Using Custom Evaluators in Policies

Reference evaluators under the custom field. The key must match the evaluator name.
If a referenced custom evaluator is not registered, the policy is denied with the message custom evaluator '<name>' is not registered.

Discovery Filtering

List flows automatically filter entries based on the caller’s authorities via the built-in filterByAuthorities stage. When a client calls tools/list, resources/list, or prompts/list, entries the user is not authorized to access are silently removed from the results.
This ensures AI agents only see tools they can actually call, preventing wasted context and failed invocations.

Hooking into Authority Checks

Authority enforcement runs as native flow stages, not plugin hooks. This means developers can hook into them with Will, Did, and Around decorators — just like any other flow stage.

Flow Stages Reference

Will Hook — Run Before the Authority Check

Use Will to add custom pre-checks, logging, or feature-flag gates that run before the built-in authority evaluation.

Did Hook — Run After the Authority Check

Use Did to audit authority decisions or emit metrics after the check completes (whether it passed or threw).

Around Hook — Replace the Entire Authority Check

Use Around to wrap or completely replace the built-in authority evaluation with custom logic. This is useful for integrating external policy engines like OPA or Cedar.

Hooking into List Filtering

Error Handling

When an authorities check fails at execution time (as opposed to list filtering), the checkEntryAuthorities stage throws an AuthorityDeniedError.

AuthorityDeniedError

JSON-RPC Error Format

The error serializes to a standard JSON-RPC error for MCP transport:

Denial Reasons

The deniedBy field provides actionable feedback:

Type-Safe Profiles

Use the FrontMcpAuthorityProfiles global interface augmentation to get autocomplete and compile-time checks for profile names.

Declaring Profiles

Create a type declaration file (e.g., authorities.d.ts) in your project:

Autocomplete in Decorators

Once declared, TypeScript provides autocomplete when using string profile references:

Metadata Augmentation

The @frontmcp/auth authorities module automatically augments all entry metadata interfaces to accept the authorities field:
This means authorities is accepted on @Tool(), @Resource(), @ResourceTemplate(), @Prompt(), and @Skill() decorators without any additional configuration.