Class Endpoint

java.lang.Object
hudson.security.csrf.CrumbExclusion
io.jenkins.plugins.mcp.server.Endpoint
All Implemented Interfaces:
ExtensionPoint, Action, ModelObject, RootAction, UnprotectedRootAction

@Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class) @Extension public class Endpoint extends CrumbExclusion implements UnprotectedRootAction
MCP HTTP endpoint.

Requests are served by Stapler (doDynamic(org.kohsuke.stapler.StaplerRequest2, org.kohsuke.stapler.StaplerResponse2)), which runs only after every PluginServletFilter has had a chance to run. This class deliberately does not implement HttpServletFilter: that extension is installed at the front of PluginServletFilter and, if it handles the request, returns before authentication filters registered later (OpenShift Login bearer tokens, Blue Ocean JWT, and anything added after startup) can establish a user. Tool calls would then run as anonymous.

The URL is an UnprotectedRootAction so anonymous callers without Overall/Read still reach the MCP layer, matching the previous filter-based behavior. Every tool invocation, including programmatic McpServerExtension.getSyncTools() handlers, restores the caller captured on the request and requires Overall/Read.

  • Field Details

    • MCP_SERVER

      public static final String MCP_SERVER
      See Also:
    • SSE_ENDPOINT

      public static final String SSE_ENDPOINT
      See Also:
    • MCP_SERVER_SSE

      public static final String MCP_SERVER_SSE
      See Also:
    • STREAMABLE_ENDPOINT

      public static final String STREAMABLE_ENDPOINT
      See Also:
    • MCP_SERVER_STREAMABLE

      public static final String MCP_SERVER_STREAMABLE
      See Also:
    • STATELESS_ENDPOINT

      public static final String STATELESS_ENDPOINT
      See Also:
    • MCP_SERVER_STATELESS

      public static final String MCP_SERVER_STATELESS
      See Also:
    • MCP_SERVER_MESSAGE

      public static final String MCP_SERVER_MESSAGE
      See Also:
    • HEALTH_ENDPOINT

      public static final String HEALTH_ENDPOINT
      The endpoint path for health checks
      See Also:
    • MCP_SERVER_HEALTH

      public static final String MCP_SERVER_HEALTH
      See Also:
    • METRICS_ENDPOINT

      public static final String METRICS_ENDPOINT
      The endpoint path for metrics
      See Also:
    • MCP_SERVER_METRICS

      public static final String MCP_SERVER_METRICS
      See Also:
    • AUTHENTICATION

      public static final String AUTHENTICATION
    • HTTP_SERVLET_REQUEST

      public static final String HTTP_SERVLET_REQUEST
    • SESSION_SWEEP_INTERVAL

      public static int SESSION_SWEEP_INTERVAL
      How often, in seconds, idle streamable HTTP sessions are dropped. A session with no open stream that has gone this long without a request is closed: that is a client that went away without sending DELETE. Default is 1800 (30 minutes), same as the SDK. Set to 0 to keep sessions forever, which is how the plugin used to run out of file descriptors. It's not static final on purpose to allow dynamic configuration via script console.
    • REQUIRE_ORIGIN_HEADER

      public static boolean REQUIRE_ORIGIN_HEADER
      Whether to require the Origin header in requests. Default is false, can be overridden by setting the system property io.jenkins.plugins.mcp.server.Endpoint.requireOriginHeader=true.
    • REQUIRE_ORIGIN_MATCH

      public static boolean REQUIRE_ORIGIN_MATCH
      Whether to require the Origin header to match the Jenkins root URL. Default is true, can be overridden by setting the system property io.jenkins.plugins.mcp.server.Endpoint.requireOriginMatch=false. The header will be validated only if present.
    • DISABLE_MCP_STATELESS

      public static boolean DISABLE_MCP_STATELESS
      Whether to disable the stateless MCP endpoint. Default is false (enabled). The stateless endpoint is available at /mcp-server/stateless
    • DISABLE_MCP_SSE

      public static boolean DISABLE_MCP_SSE
      Whether to disable the SSE MCP endpoint. Default is false (enabled). The SSE endpoint is available at /mcp-server/sse
    • DISABLE_MCP_STREAMABLE

      public static boolean DISABLE_MCP_STREAMABLE
      Whether to disable the streamable HTTP MCP endpoint. Default is false (enabled). The streamable endpoint is available at /mcp-server/mcp
    • SSE_MESSAGE_TIMEOUT_SECONDS

      public static int SSE_MESSAGE_TIMEOUT_SECONDS
      Maximum time in seconds to wait for an SSE message to be processed before releasing the Jetty handler thread. The MCP Java SDK's HttpServletSseServerTransportProvider.doPost() calls Mono.block() without a timeout, which can permanently leak Jetty threads if the reactive publisher never completes (e.g., due to unclean SSE client disconnects). Set to 0 to disable the timeout (not recommended).
    • SSE_MESSAGE_MAX_THREADS

      public static int SSE_MESSAGE_MAX_THREADS
      Maximum number of threads dedicated to processing SSE messages. This bounds the impact of hung Mono.block() calls to this pool rather than the Jetty thread pool.
    • ALLOW_UNAUTHENTICATED_MCP

      public static boolean ALLOW_UNAUTHENTICATED_MCP
      Whether anonymous MCP POSTs (no Authorization header) may skip the CSRF crumb. Default is false. Requests that send Authorization stay exempt, because a cross-site page cannot set that header. Set io.jenkins.plugins.mcp.server.Endpoint.allowUnauthenticatedMcp=true only when anonymous agents must call MCP without a crumb. That weakens CSRF protection: the Origin check allows a missing Origin, and does nothing when the Jenkins root URL is unset. mvn hpi:run sets the property so a local controller can be called without a crumb.
  • Constructor Details

    • Endpoint

      public Endpoint()
  • Method Details

    • getRequestedResourcePath

      public static String getRequestedResourcePath(jakarta.servlet.http.HttpServletRequest httpServletRequest)
    • process

      public boolean process(jakarta.servlet.http.HttpServletRequest request, jakarta.servlet.http.HttpServletResponse response, jakarta.servlet.FilterChain chain) throws IOException, jakarta.servlet.ServletException
      Exempts MCP POSTs from CSRF crumbs without serving them.

      CrumbFilter runs before PluginServletFilter. Returning true without calling chain.doFilter would swallow the request there, so authentication filters registered later would never see it. Continuing the chain lets those filters run; Stapler then dispatches to doDynamic(org.kohsuke.stapler.StaplerRequest2, org.kohsuke.stapler.StaplerResponse2).

      The path comes from HttpServletRequest.getPathInfo(). For POST requests CrumbFilter wraps the request so that value is the canonical path (SECURITY-1774). A raw URI such as /mcp-server/mcp/../../script is therefore seen as /script and keeps its crumb check.

      Overrides:
      process in class CrumbExclusion
      Throws:
      IOException
      jakarta.servlet.ServletException
    • init

      protected void init() throws jakarta.servlet.ServletException
      Builds the MCP transports once. The unsynchronized read of initialized avoids taking the lock on every request; the second check runs while holding the monitor.
      Throws:
      jakarta.servlet.ServletException
    • doDynamic

      public void doDynamic(org.kohsuke.stapler.StaplerRequest2 req, org.kohsuke.stapler.StaplerResponse2 rsp) throws IOException, jakarta.servlet.ServletException
      Stapler entry point for /mcp-server/**. Invoked only after the servlet filter chain, including every PluginServletFilter, has completed.

      @RequirePOST cannot be used: MCP clients are not browsers, and the SSE and streamable endpoints must accept GET. POST requests are exempted from crumbs by process(jakarta.servlet.http.HttpServletRequest, jakarta.servlet.http.HttpServletResponse, jakarta.servlet.FilterChain). Each tool and the metrics endpoint check permissions themselves.

      Throws:
      IOException
      jakarta.servlet.ServletException
    • getIconFileName

      public String getIconFileName()
      Specified by:
      getIconFileName in interface Action
    • getDisplayName

      public String getDisplayName()
      Specified by:
      getDisplayName in interface Action
      Specified by:
      getDisplayName in interface ModelObject
    • getUrlName

      public String getUrlName()
      Specified by:
      getUrlName in interface Action