Mcp Server Plugin

MCP Server Plugin for Jenkins

The MCP (Model Context Protocol) Server Plugin for Jenkins implements the server-side component of the Model Context Protocol. This plugin enables Jenkins to act as an MCP server, providing context, tools, and capabilities to MCP clients, such as LLM-powered applications or IDEs.

Features

• MCP Server Implementation: Implements the server-side of the Model Context Protocol.
• Jenkins Integration: Exposes Jenkins functionalities as MCP tools and resources.
• Extensible Architecture: Allows easy extension of MCP capabilities through the McpServerExtension interface.

Key Components

1. Endpoint: The main entry point for MCP communication, handling MCP transport connections and message routing.
2. DefaultMcpServer: Implements McpServerExtension, providing default tools for interacting with Jenkins jobs and builds.
3. McpToolWrapper: Wraps Java methods as MCP tools, handling parameter parsing and result formatting.
4. McpServerExtension: Interface for extending MCP server capabilities.

MCP SDK Version

This MCP Server is based on the MCP Java SDK version 0.17.2, which implements the MCP specification version 2025-06-18.

Getting Started

Prerequisites

• Jenkins (version 2.533 or higher)

Configuration

The MCP Server plugin automatically sets up necessary endpoints and tools upon installation, requiring no additional configuration.

System properties

The following system properties can be used to configure the MCP Server plugin:

• hard limit on max number of log lines to return with io.jenkins.plugins.mcp.server.extensions.BuildLogsExtension.limit.max=10000 (default 10000)
• disable stateless endpoint with io.jenkins.plugins.mcp.server.Endpoint.disableMcpStateless=true (default false)
• disable SSE endpoint with io.jenkins.plugins.mcp.server.Endpoint.disableMcpSse=true (default false)
• disable streamable HTTP endpoint with io.jenkins.plugins.mcp.server.Endpoint.disableMcpStreamable=true (default false)

Origin header validation

The MCP specification mark as MUST validate the Origin header of incoming requests. By default, the MCP Server plugin does not enforce this validation to facilitate usage by AI Agent not providing the header. You can enable different levels of validation, if the header is available with the request you can enforce his validation using the system property io.jenkins.plugins.mcp.server.Endpoint.requireOriginMatch=true When enforcing the validation, the header value must match the configured Jenkins root url.

If receiving the header is mandatory the system property io.jenkins.plugins.mcp.server.Endpoint.requireOriginHeader=true will make it mandatory as well.

Connection Resilience

The MCP Server plugin includes several features to improve connection reliability:

Keep-Alive Messages

The server sends periodic keep-alive messages to detect broken connections. By default, keep-alive messages are sent every 30 seconds.

You can configure this interval with the system property:

io.jenkins.plugins.mcp.server.Endpoint.keepAliveInterval=30

Set to 0 to disable keep-alive messages (not recommended).

Health Endpoint

A lightweight MCP-specific health endpoint is available for connection monitoring at:

/mcp-health

This endpoint:

• Returns MCP server status and active connection counts
• Requires no authentication for maximum accessibility
• Returns immediately without MCP protocol overhead
• Returns HTTP 200 when healthy, HTTP 503 during shutdown
• Includes Retry-After header during shutdown

Response format:

{
  "mcpServerStatus": "ok",
  "activeConnections": 5,
  "shuttingDown": false,
  "timestamp": "2025-01-28T10:30:00Z"
}

Recommended client usage:

• Poll the health endpoint periodically (e.g., every 10-30 seconds)
• When the endpoint returns 503 or becomes unreachable, prepare for reconnection
• Use the Retry-After header value when available

Metrics Endpoint

A metrics endpoint is available for monitoring connection statistics at:

/mcp-server/metrics

This endpoint requires authentication (standard Jenkins permissions) and provides:

{
  "sseConnectionsTotal": 42,
  "sseConnectionsActive": 3,
  "streamableRequestsTotal": 150,
  "connectionErrorsTotal": 2,
  "uptimeSeconds": 3600,
  "startTime": "2025-01-28T10:00:00Z"
}

Graceful Shutdown

When Jenkins shuts down, the health endpoint will return 503 Service Unavailable with a brief grace period before full termination. This allows clients to detect the shutdown and prepare for reconnection.

Transport Recommendation

For better connection reliability, we recommend using Streamable HTTP (/mcp-server/mcp) instead of SSE (/mcp-server/sse). Streamable HTTP handles connection issues more gracefully and is the preferred transport for most MCP clients.

Production Deployment

When deploying behind a reverse proxy or in production environments, configure these timeout settings to prevent premature connection drops:

Jenkins/Jetty Configuration

Jenkins uses Winstone (embedded Jetty) which defaults httpKeepAliveTimeout to 30 seconds. Since MCP keep-alive pings are also sent every 30 seconds, this creates a race condition where Jetty may close the connection before the next ping arrives.

Add this argument to your Jenkins startup command:

--httpKeepAliveTimeout=600000

For Docker deployments, add to your docker-compose.yml:

services:
  jenkins:
    image: jenkins/jenkins:lts
    command: ["--httpKeepAliveTimeout=600000"]

Reverse Proxy Configuration (Nginx)

For Nginx, extend timeouts for MCP endpoints:

location ~ ^/(mcp-server|mcp-health)/ {
    proxy_pass http://jenkins;
    proxy_http_version 1.1;
    proxy_request_buffering off;
    proxy_buffering off;
    proxy_set_header Connection "";
    proxy_read_timeout 600s;
    proxy_send_timeout 600s;
}

Transport Endpoints

The MCP Server plugin provides three transport endpoints, all enabled by default:

| Transport | Endpoint | Description | |-----------|----------|-------------| | SSE | /mcp-server/sse + /mcp-server/message | Server-Sent Events transport with session management | | Streamable HTTP | /mcp-server/mcp | Streamable HTTP transport with session management | | Stateless | /mcp-server/stateless | Stateless HTTP transport without session management |

Each transport can be disabled independently using system properties:

-Dio.jenkins.plugins.mcp.server.Endpoint.disableMcpSse=true
-Dio.jenkins.plugins.mcp.server.Endpoint.disableMcpStreamable=true
-Dio.jenkins.plugins.mcp.server.Endpoint.disableMcpStateless=true

When to use Stateless transport

The stateless endpoint (/mcp-server/stateless) is useful for:

• Simple deployments where session management overhead is not needed
• Environments where clients make independent requests without maintaining a persistent connection
• Testing and debugging scenarios
• Clients that don't support session-based protocols

Usage

Connecting to the MCP Server

MCP clients can connect to the server using:

• Streamable HTTP Endpoint: /mcp-server/mcp
• SSE Endpoint: /mcp-server/sse
• Message Endpoint: /mcp-server/message
• Stateless Endpoint: /mcp-server/stateless

Authentication and Credentials

The MCP Server Plugin requires the same credentials as the Jenkins instance it's running on. To authenticate your MCP queries:

1. Jenkins API Token: Generate an API token from your Jenkins user account.
2. Basic Authentication: Use the API token in the HTTP Basic Authentication header.

Generate a personal access token

To generate a personal access token:

• Sign in to Jenkins.
• Select your user icon in the upper-right corner, and then select Security.
• Select Add new token.
• Enter a name to distinguish the token, and then select Generate.
• Copy the token and store it in a secure location for later use.

> [!WARNING] > Once you leave the page, you cannot view or copy the token again.

• Select Done to add the token.
• Select Save to save your changes.

Encode credentials for HTTP basic authentication

Use basic HTTP authentication with the MCP agent by encoding it with the personal access token.

To encode credentials on Linux, macOS, or Windows:

Open a terminal and run the following command, replacing ` and ` with your actual username and the personal access token you generated in Jenkins

• Linux or macOS

echo -n ":" | base64

• Windows (PowerShell)

[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(":"))

if successful, the Base64-encoded credential is output, similar to the following:

dXNlcm5hbWU6dG9rZW4=

Store the encoded credential in a secure location for later use.

> [!NOTE] > Base64 encoding is not encryption. > Anyone with access to the encoded string can decode it and obtain your credentials. > Always protect the encoded credentials as if they are the original username and token.

Example Client Configurations

Cline Configuration

{
  "mcpServers": {
    "jenkins": {
      "autoApprove": [
        
      ],
      "disabled": false,
      "timeout": 60,
      "type": "streamableHttp",
      "url": "https://jenkins-host/mcp-server/mcp",
      "headers": {
        "Authorization": "Basic "
      }
    }
  }
}

Copilot Configuration

Copilot doesn't work well with the Streamable transport as of now, and I'm still investigating the issues. Please continue to use the SSE endpoint.

{
  "mcp": {
    "servers": {
      "jenkins": {
        "type": "sse",
        "url": "https://jenkins-host/mcp-server/sse",
        "headers": {
          "Authorization": "Basic "
        }
      }
    }
  }
}

Streamable example:

{
  "servers": {
    "jenkins": {
      "type": "http",
      "url": "http://jenkins-host/mcp-server/mcp",
      "requestInit": {
        "headers": {
          "Authorization": "Basic "
        }
      }
    }
  }
}

Windsurf Configuration

{
  "servers": {
    "jenkins": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://jenkins-host/mcp-server/mcp",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "Basic "
      }
    }
  }
}

Cursor Configuration

{
  "mcpServers": {
    "jenkins": {
      "type": "http",
      "url": "https://jenkins-host/mcp-server/mcp",
      "headers": {
        "Authorization": "Basic "
      }
    }
  }
}

Claude

claude mcp add jenkins http://jenkins-host/mcp-server/mcp --transport http --header "Authorization: Basic "

Stateless Configuration Example

For clients that prefer stateless communication without session management:

{
  "servers": {
    "jenkins": {
      "type": "http",
      "url": "http://jenkins-host/mcp-server/stateless",
      "requestInit": {
        "headers": {
          "Authorization": "Basic "
        }
      }
    }
  }
}

Goose

• Click “Add custom extension”
• Give it a meaningful name
• In the type Dropdown, select “Streamable HTTP”
• Enter the endpoint URL. This should be something like http://jenkins-host/mcp-server/mcp
• Scroll to “Request Headers”
• In the empty field, type Authorization as the name. Then in the Value field, type “Basic ”
• Click "Add"
• Click “Add Extension”

Available Tools

The plugin provides the following built-in tools for interacting with Jenkins:

Job Management

• getJob: Get a Jenkins job by its full path.
• getJobs: Get a paginated list of Jenkins jobs, sorted by name.
• triggerBuild: Trigger a build of a job.

This tool supports parameterized builds. You can provide parameters as a JSON object where each key is the parameter name. For example:

``json { "jobFullName": "my-job", "parameters": { "BRANCH": "main", "DEBUG_MODE": "true" } } `` Note on Parameters:

• Core Jenkins Parameters: Fully supported (String, Boolean, Choice, Text, Password, Run)
• Plugin Parameters: Automatically detected and handled using reflection
• File Parameters: Not supported via MCP (require file uploads)
• Multi-select Parameters: Supported as arrays or lists
• Custom Plugin Parameters: Automatically attempted using reflection-based detection
• Fallback Behavior: Unsupported parameters fall back to default values with logging

This tool returns a queue item if the job is successfully scheduled. You can use the returned queue item ID with the getQueueItem tool.

• getQueueItem: Get information about a queued item using its ID.

Build Information

• getBuild: Retrieve a specific build or the last build of a Jenkins job.
• updateBuild: Update build display name and/or description.
• getBuildLog: Retrieve log lines with pagination for a specific build or the last build. Supports forward reads, end-relative reads (negative skip/limit), and cursor pagination: every response carries a nextCursor you can pass back as cursor to keep reading without re-scanning from the top. The cursor is tied to the (job, buildNumber) it was issued for and is rejected if used against a different build. totalLines is exact for end-relative reads and -1 for forward/cursor reads (which stop as soon as they have enough lines, so the total is never computed). Reads a non-blocking snapshot, so it returns promptly even while a build is still running. If nextCursor is set but hasMoreContent is false, you've read everything written so far and the build is still going; hold onto the cursor and call again later to pick up whatever was appended in between.
• searchBuildLog: Search for log lines matching a pattern (string or regex) in build logs. Reads a non-blocking snapshot (returns promptly for in-progress builds) and stops scanning early once maxMatches is reached.
• rebuildBuild: Re-run a build with the same parameters. For Pipeline jobs with Replay support, uses the original script; for other parameterized jobs, schedules a new build with the same parameters. Optional buildNumber; defaults to the last build. Returns the queue item for the new build.
• getReplayScripts: Return the main script and loaded scripts of a replayable Pipeline build. Use this to inspect or modify script before calling replayBuild. Fails for non-Pipeline jobs. Optional buildNumber; defaults to the last build.
• replayBuild: Run a Pipeline build again with a modified script. Provide mainScript (required) and optionally loadedScripts. Optional buildNumber; defaults to the last build. Fails if the build is not replayable or replay is not allowed (e.g. permissions or sandbox).
• getTestResults: Retrieve test results of a specific build or the last build.

SCM Integration

• getJobScm: Retrieve SCM configurations of a Jenkins job.
• getBuildScm: Retrieve SCM configurations of a specific build.
• getBuildChangeSets: Retrieve change log sets of a specific build.
• findJobsWithScmUrl: Find jobs using a specific SCM (git) repository URL

Management Information

• whoAmI: Get information about the current user.
• getStatus: Checks the health and readiness status of a Jenkins instance. Use this tool to assess Jenkins instance health rather than simple up/down status.

Each tool accepts specific parameters to customize its behavior. For detailed usage instructions and parameter descriptions, refer to the API documentation or use the MCP introspection capabilities.

To use these tools, connect to the MCP server endpoint and make tool calls using your MCP client implementation.

Enhanced Parameter Support

The MCP Server Plugin now provides comprehensive support for Jenkins parameters:

Supported Parameter Types

• String Parameters: Text input with defa

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jenkinsci
• Source: jenkinsci/mcp-server-plugin
• License: MIT
• Homepage: https://plugins.jenkins.io/mcp-server/

Install and usage instructions live in the source repository linked above.