Package org.apache.juneau.rest.server.mcp.v20260728

Class McpResourceServerConfig

java.lang.Object
org.apache.juneau.rest.server.mcp.v20260728.McpResourceServerConfig
public class McpResourceServerConfig extends Object
Binding-owned OAuth 2.1 resource-server (RS) configuration for a 2026-07-28 MCP endpoint — the authorization-hardening baseline.

Off by default. isEnabled() is false unless enabled, so an existing MCP endpoint that does not opt in behaves exactly as before (no bearer requirement, no well-known route). When enabled, the endpoint:

  • Requires a valid RFC 6750 bearer token on the MCP POST endpoint, establishing an authenticated principal.
  • Serves an RFC 9728 Protected Resource Metadata document from .well-known/oauth-protected-resource.
  • Answers a missing/invalid token with 401 + a WWW-Authenticate: Bearer ... challenge carrying the resource_metadata pointer.
  • Enforces RFC 8707 audience matching against the resource identifier.

Mutable during setup, effectively immutable once published — the same builder-less mutable-setup idiom as McpMrtrConfig / McpCacheConfig: configure it fully via the createMcpOptions() / getMcpOptions() override, then never mutate it afterward (a request-time reader sees it with no synchronization).

Token-validation mode:

The validation mode (RFC 7662 introspection vs JWKS/issuer JWT verification) is selected by which TokenValidator is supplied to setTokenValidator(TokenValidator): OAuthIntrospectionValidator (from juneau-rest-server-auth-oauth) for opaque tokens, or JwtTokenValidator (from juneau-rest-server-auth-jwt) for JWT access tokens.

Since:
10.0.0

  • Field Details

  • Constructor Details

  • Method Details

    • isEnabled

      public boolean isEnabled()
      Whether RS authentication is enabled for this binding.
      Returns:
      true if enabled. Defaults to false.

    • setEnabled

      public McpResourceServerConfig setEnabled(boolean value)
      Enables or disables RS authentication.
      Parameters:
      value - The new value.
      Returns:
      This object (for method chaining).

    • getResource

      public URI getResource()
      This server's canonical resource identifier (RFC 9728 resource / RFC 8707 audience default).
      Returns:
      The resource identifier, or null if not set.

    • setResource

      public McpResourceServerConfig setResource(URI value)
      Sets the canonical resource identifier.
      Parameters:
      value - The new value. Can be null to unset (but is required when enabled).
      Returns:
      This object (for method chaining).

    • getAudience

      public String getAudience()
      The RFC 8707 audience this server accepts.
      Returns:
      The explicit audience, or (when unset) the resource identifier as a string, or null if neither is set.

    • setAudience

      public McpResourceServerConfig setAudience(String value)
      Sets an explicit RFC 8707 audience, overriding the resource-identifier default.
      Parameters:
      value - The new value. Can be null to fall back to the resource identifier.
      Returns:
      This object (for method chaining).

    • getRealm

      public String getRealm()
      The WWW-Authenticate: Bearer realm="..." challenge realm.
      Returns:
      The realm. Never null; defaults to "mcp".

    • setRealm

      public McpResourceServerConfig setRealm(String value)
      Sets the challenge realm.
      Parameters:
      value - The new value. Must not be null or blank.
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If value is null or blank.

    • isRequireAudienceClaim

      public boolean isRequireAudienceClaim()
      Whether a validated token must expose audience claims for RFC 8707 audience enforcement to apply.

      When true (the default), a validator that returns a bare Principal carrying no claims is rejected (401 invalid_token) rather than silently passing the confused-deputy defense. Set to false only when the token validator itself enforces the audience internally (e.g. a JwtTokenValidator configured to verify aud) so a claims-less principal is a deliberate, trusted signal — pairs with introspection-mode validators that legitimately omit aud.

      Returns:
      true if a claims-less principal is rejected (the default).

    • setRequireAudienceClaim

      public McpResourceServerConfig setRequireAudienceClaim(boolean value)
      Sets whether a validated token must expose audience claims for audience enforcement to apply.
      Parameters:
      value - The new value. Defaults to true (fail-closed).
      Returns:
      This object (for method chaining).

    • getTokenValidator

      public TokenValidator getTokenValidator()
      The token validator that verifies presented bearer tokens.
      Returns:
      The validator, or null if not set (required when enabled).

    • setTokenValidator

      public McpResourceServerConfig setTokenValidator(TokenValidator value)
      Sets the token validator (selects introspection vs JWT validation mode).
      Parameters:
      value - The new value. Can be null to unset (but is required when enabled).
      Returns:
      This object (for method chaining).

    • getAuthorizationServers

      public List<URI> getAuthorizationServers()
      The advertised authorization_servers (RFC 9728).
      Returns:
      A live, mutable list. Never null.

    • addAuthorizationServer

      public McpResourceServerConfig addAuthorizationServer(URI value)
      Adds an authorization-server issuer URI.
      Parameters:
      value - The issuer URI. Must not be null.
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If value is null.

    • getScopesSupported

      public Set<String> getScopesSupported()
      The advertised scopes_supported (RFC 9728).
      Returns:
      A live, mutable set. Never null.

    • addScopeSupported

      public McpResourceServerConfig addScopeSupported(String value)
      Adds an advertised supported scope.
      Parameters:
      value - The scope. Must not be null or blank.
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If value is null or blank.

    • getRequiredScopes

      public Set<String> getRequiredScopes()
      The scopes a token must carry to access the MCP endpoint (baseline insufficient-scope enforcement).
      Returns:
      A live, mutable set. Never null; empty means no scope is required beyond a valid token.

    • addRequiredScope

      public McpResourceServerConfig addRequiredScope(String value)
      Adds a required scope (also advertised as supported).
      Parameters:
      value - The scope. Must not be null or blank.
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If value is null or blank.

    • getBearerMethodsSupported

      public Set<String> getBearerMethodsSupported()
      The advertised bearer_methods_supported (RFC 9728 / RFC 6750).
      Returns:
      A live, mutable set. Never null; defaults to [header].

    • addOperationScope

      public McpResourceServerConfig addOperationScope(String method, String name, String... scopes)
      Registers the scopes required to invoke a specific MCP operation (SEP-2350 per-operation step-up).

      Populates the default static per-operation scope map consulted by requiredScopesFor(McpOperationContext) when no explicit resolver is set. A null or blank name registers a method-wide entry matching every operation of that JSON-RPC method (e.g. every tools/call regardless of tool name); a specific name takes precedence over the method-wide entry. Each supplied scope is also advertised as supported.

      Parameters:
      method - The JSON-RPC method (e.g. tools/call). Must not be null or blank.
      name - The operation name (tool/prompt name or resource URI), or null/blank for a method-wide entry.
      scopes - The scopes required to invoke the operation. Must not be null, empty, or contain a null/blank element.
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If method is null/blank or scopes is invalid.

    • getOperationScopeResolver

      public McpOperationScopeResolver getOperationScopeResolver()
      The dynamic per-operation scope resolver, if one was installed.
      Returns:
      The resolver, or null to use the default static map.

    • setOperationScopeResolver

      public McpResourceServerConfig setOperationScopeResolver(McpOperationScopeResolver value)
      Installs a dynamic per-operation scope resolver, overriding the default static map.

      The seam for a future dynamic resolver; not built for 10.0. When set, it fully replaces the static map for requiredScopesFor(McpOperationContext).

      Parameters:
      value - The resolver, or null to revert to the static map.
      Returns:
      This object (for method chaining).

    • requiredScopesFor

      public Set<String> requiredScopesFor(McpOperationContext ctx)
      Resolves the scopes required to invoke the given operation.

      Consults the resolver when installed; otherwise the static map, preferring a name-specific entry over the method-wide "*" entry. An empty return means "no per-operation requirement beyond the endpoint-wide baseline".

      Parameters:
      ctx - The resolved operation. Must not be null.
      Returns:
      The required scopes (never null; possibly empty).

    • validateEnabled

      public void validateEnabled()
      Validates that this config is internally consistent for the enabled state.

      A no-op when disabled. When enabled, requires a resource identifier (absolute, with scheme + authority) and a token validator.

      Throws:
      IllegalStateException - If enabled but misconfigured.