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

Interface McpEndpoint

All Superinterfaces:
McpEndpointMixin
All Known Implementing Classes:
SpringExampleMcpServer, SpringMcpRestServlet
public interface McpEndpoint extends McpEndpointMixin
Mixin interface that exposes a 2026-07-28 MCP endpoint at POST /mcp on any Juneau REST resource.

The mixin path and the servlet-subclass path (McpRestServlet) are at parity: both bind the revision at compile time and both read the same McpOptions shape for behavior configuration (capabilities/instructions/cache/mrtr/subscriptions/broker) via a single override.

Example:











    


  • 

    

    Method Details
    

      

    • 

      

      revision
      

      default McpRevision revision()
      

      Description copied from interface: McpEndpointMixin
      

      The MCP protocol revision this endpoint speaks.
      

      

      Specified by:
      

      revision in interface McpEndpointMixin
      

      Returns:
      

      The bound revision. Never null.
      

      

      

      • 

    • 

      

      mcpTraceContextExtractor
      

      default TraceContextExtractor mcpTraceContextExtractor()
      

      Publishes this revision's stable TraceContextExtractor so an active TracerHook
 (via RestOpInvoker) recognizes this endpoint's resolved JsonRpcRequest argument
 and its params._meta carrier before span creation.

 
      
 A no-op when no TracerHook bean is registered — see the no-tracer fast-path
 contract documented on TracerHook.
      

      

      Returns:
      

      This revision's shared TraceContextExtractor. Never null.
      

      

      

      • 

    • 

      

      getMcpOptions
      

      default McpOptions getMcpOptions()
      

      This endpoint's behavior configuration — capabilities, instructions, cache hints, MRTR, subscriptions,
 and the subscription broker, all in one place.

 
      
 The default returns a per-binding-fresh McpOptions (all defaults; no live-state sharing across
 endpoint instances). Override to customize any of the six concepts.

 
      
 This method is invoked exactly once per endpoint instance and the result is memoized for that
 instance's lifetime by the framework internals that read it (revision(),
 subscriptionBroker(), the @Bean-published accessor) — so an override may freely
 construct and configure a fresh instance on every call, exactly as shown above; it never needs to cache the
 result itself, and returning a fresh instance per call cannot reintroduce the "must return a stable
 instance" footgun the pre-consolidation per-concept hooks warned about.
      

      

      Returns:
      

      This endpoint's options. Must not be null.
      

      

      

      • 

    • 

      

      mcpOptionsBean
      

      default McpOptions mcpOptionsBean()
      

      Publishes this endpoint's memoized McpOptions into this resource's RestContext bean store,
 the same @Bean-method mechanism already used by mcpTraceContextExtractor().

 
      
 This is what lets McpRevision.dispatch(...)'s subscriptions/listen branch resolve the
 real, possibly-overridden subscriptions configuration via ctx.getBean(McpOptions.class) instead of
 always falling through to that call's defensive new McpSubscriptionsConfig() default — the
 neutral core cannot add this bean itself (McpOptions is a v2 type, and the neutral module must not
 import it), so this v2-side @Bean method is the wiring's only seam.
      

      

      Returns:
      

      This endpoint's memoized options. Never null.
      

      

      

      • 

    • 

      

      subscriptionBroker
      

      default McpSubscriptionBroker subscriptionBroker()
      

      Subscription broker for this endpoint's bound revision.

 
      
 Reads getMcpOptions()'s memoized McpOptions.getSubscriptionBroker(): an explicitly
 configured broker is returned as-is; otherwise one is derived and memoized per-binding, sized from
 McpOptions.getSubscriptions()'s queue bound (see McpOptions.resolveSubscriptionBroker()).
 Because McpOptions itself is memoized once per endpoint instance (McpEndpointOptionsCache),
 two distinct endpoint instances resolve to two distinct broker registries by default — there is no
 accidental JVM-wide sharing the way the pre-consolidation mixin default had.
      

      

      Specified by:
      

      subscriptionBroker in interface McpEndpointMixin
      

      Returns:
      

      The subscription broker. Never null.
      

      

      

      • 

    • 

      

      mcpResourceServerAuth
      

      default void mcpResourceServerAuth(RestContext ctx,
 jakarta.servlet.http.HttpServletRequest req,
 jakarta.servlet.http.HttpServletResponse res)
      

      OAuth 2.1 resource-server bearer gate for the mixin's MCP POST /mcp endpoint.

 
      
 A no-op unless RS auth is enabled; when enabled, a request that
 the router resolves to the MCP POST /mcp dispatch operation must present a valid bearer token or it is
 rejected with 401 / 403 and a WWW-Authenticate: Bearer ... challenge.  The gate is scoped to
 the MCP dispatch operation (identified by resolved-operation identity, or by that operation's own router
 matchers — see McpResourceServerSupport.resolvesToMcpDispatch(org.apache.juneau.rest.server.RestContext, jakarta.servlet.http.HttpServletRequest)) so other POST operations on the
 host resource are unaffected, and it cannot drift from the router: a trailing slash, percent-encoding, a
 POST claim on any override channel (?method= or an override header), or a host-chosen @Mixin(path/paths) re-mount cannot slip past it
.  The well-known GET routes are left unauthenticated for PRM discovery.
      

      

      Parameters:
      

      ctx - The host RestContext handling this request.
      

      req - The raw HTTP request.
      

      res - The raw HTTP response (used to emit the challenge header on rejection).
      

      

      

      • 

    • 

      

      mcpProtectedResourceMetadataRoot
      

      default McpProtectedResourceMetadata mcpProtectedResourceMetadataRoot(RestRequest req)
      

      Serves the RFC 9728 Protected Resource Metadata document at the root well-known location (SEP-2351 fallback).

 
      
 This route (and its path-inserted sibling) is registered unconditionally, but returns 404 whenever RS auth
 is disabled — so a non-opted-in endpoint claims the well-known
 namespace but exposes no observable metadata.
      

      

      Parameters:
      

      req - The REST request.
      

      Returns:
      

      The PRM document.
      

      

      

      • 

    • 

      

      mcpProtectedResourceMetadataPathInserted
      

      default McpProtectedResourceMetadata mcpProtectedResourceMetadataPathInserted(RestRequest req)
      

      Serves the RFC 9728 Protected Resource Metadata document at the path-inserted well-known location (SEP-2351), but
 only when the requested suffix matches this resource's expected well-known path; otherwise 404.
      

      

      Parameters:
      

      req - The REST request.
      

      Returns:
      

      The PRM document.
      

      

      

      • 

    

    

    •