How to configure the CloudBees CI MCP Router endpoint for backward compatibility

Last Reviewed:2026-04-29()
3 minute readKnowledge base

Issue

Older versions of MCP Server plugin (prior to version 0.148.v6b_c057f27738) do not support the /mcp-server/stateless endpoint, which the CloudBees CI MCP Router uses by default to communicate with Jenkins instances. This endpoint provides improved performance and reliability through stateless HTTP connections instead of streamable connections that require a Mcp-Session-Id header or Server-Sent Events (SSE). This incompatibility can cause:

  • Connection errors in CloudBees CI MCP Router logs, such as: Unable to connect to [Jenkins URL] mcp endpoint (HTTP 404), is the mcp-server plugin installed and the endpoint accessible?

  • MCP tools not appearing or being unavailable in AI clients (for example, GitHub Copilot, Claude, or Amazon Q).

  • CloudBees CI MCP Router initialization failures or timeouts.

To work around this, you can configure the CloudBees CI MCP Router to use the legacy /mcp-server/mcp endpoint.

Environment

Resolution

To resolve this issue, choose one of the following options. Upgrading MCP Server plugin is the recommended long-term solution. If you cannot upgrade immediately, you can override the endpoint as a temporary workaround.

Prerequisites

  • CloudBees CI MCP Router (development version after 2026-04-20)

  • Jenkins instance with the MCP Server plugin installed

  • Administrative access to the CloudBees CI MCP Router configuration

Option 1: Upgrade the MCP Server plugin (recommended)

Upgrade MCP Server plugin to version 0.148.v6b_c057f27738 or later to take advantage of the improved stateless endpoint.

  1. Navigate to Manage Jenkins  Plugins.

  2. Go to the Available plugins or Installed plugins tab.

  3. Search for MCP Server plugin.

  4. Select and install or update to the latest version.

  5. Restart Jenkins when prompted.

  6. Restart the CloudBees CI MCP Router to detect the new endpoint.

  7. Verify the CloudBees CI MCP Router connects successfully by checking the CloudBees CI MCP Router logs for successful connection messages.

Option 2: Override endpoint configuration (temporary workaround)

If you cannot immediately upgrade the MCP Server plugin, override the CloudBees CI MCP Router’s default endpoint to use the legacy /mcp-server/mcp path.

The legacy /mcp-server/mcp endpoint is a temporary workaround. Plan to upgrade MCP Server plugin to version 0.148.v6b_c057f27738 or later to use the stateless endpoint.

Select one of the following methods to override the endpoint:

Method 1: Environment variable

Set the JENKINS_ENDPOINT_MCP environment variable before starting the CloudBees CI MCP Router:

docker run -e JENKINS_ENDPOINT_MCP=/mcp-server/mcp \
  -e JENKINS_HOSTS=http://jenkins.example.com:8080 \
  cloudbees/cloudbees-ci-mcp-router
▼

Method 2: Kubernetes or OpenShift

For containerized deployments, add the environment variable to your deployment configuration:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: cloudbees-ci-mcp-router
spec:
  template:
    spec:
      containers:
      - name: mcp-router
        image: cloudbees/cloudbees-ci-mcp-router:latest
        env:
        - name: JENKINS_ENDPOINT_MCP
          value: "/mcp-server/mcp"
        - name: JENKINS_HOSTS
          value: "http://jenkins.example.com:8080"
▼

Verify the endpoint override

After applying the configuration override:

  1. Check the CloudBees CI MCP Router logs for successful connection messages:

    INFO  [com.cloudbees.jenkins.mcp.MCPConnectionHolder] Successfully connected to Jenkins at http://jenkins.example.com:8080/mcp-server/mcp
    ▼

  2. Verify the CloudBees CI MCP Router discovers and registers MCP tools from Jenkins in the logs.

  3. Test MCP tool access from your AI client (for example, GitHub Copilot, Claude, or Amazon Q) to confirm connectivity.

Override examples by deployment type

The following examples show how to apply the endpoint override in common deployment scenarios.

Example 1: Docker Compose configuration

For Docker Compose deployments, add the environment variable to your docker-compose.yml:

version: '3.8'
services:
  mcp-router:
    image: cloudbees/cloudbees-ci-mcp-router:latest
    environment:
      - JENKINS_ENDPOINT_MCP=/mcp-server/mcp
      - JENKINS_HOSTS=http://jenkins.example.com:8080
    ports:
      - "9000:9000"
▼

Example 2: Multiple Jenkins instances

When connecting to multiple Jenkins instances with mixed plugin versions:

docker run -e JENKINS_ENDPOINT_MCP=/mcp-server/mcp \
  -e JENKINS_HOSTS=http://jenkins1.example.com:8080,http://jenkins2.example.com:8080 \
  cloudbees/cloudbees-ci-mcp-router
▼

This configuration uses the legacy endpoint for all Jenkins instances. After upgrading all instances to the newer plugin version, remove the override to use the default stateless endpoint.

Example 3: Operations center mode

When using the operations center mode instead of direct Jenkins hosts:

docker run -e JENKINS_ENDPOINT_MCP=/mcp-server/mcp \
  -e OC_URL=https://operations-center.example.com \
  cloudbees/cloudbees-ci-mcp-router
▼

Additional CloudBees CI MCP Router configuration properties

The CloudBees CI MCP Router supports several related configuration options that can be overridden using the same methods (environment variables, system properties, or a configuration file):

Property Default Description

jenkins.endpoint.mcp

/mcp-server/stateless

MCP endpoint path on each Jenkins instance.

mcp.client.initialization.timeout

60s

Timeout for initial connection to Jenkins.

mcp.client.request.timeout

120s

Timeout for individual MCP tool requests.

mcp.client.initialization.retry.number

0

Number of retries for hibernating controllers.

mcp.client.initialization.retry.delay

5s

Delay between retry attempts.

All properties can be overridden using environment variables (convert to uppercase, replace . with _) or system properties.

References

This article is part of our Knowledge Base and is provided for guidance-based purposes only. The solutions or workarounds described here are not officially supported by CloudBees and may not be applicable in all environments. Use at your own discretion, and test changes in a safe environment before applying them to production systems.