Getting Started
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)
- allow anonymous MCP clients to skip the CSRF crumb with
io.jenkins.plugins.mcp.server.Endpoint.allowUnauthenticatedMcp=true (default false)
[!WARNING]
io.jenkins.plugins.mcp.server.Endpoint.allowUnauthenticatedMcp=true weakens CSRF protection. MCP POSTs that send an Authorization header are exempt from the crumb, because a page on another site cannot add that header. Anonymous and session-cookie clients are not exempt unless this property is set. With it on, those POSTs rely on the Origin check, which allows a missing Origin and does nothing when the Jenkins root URL is unset. Leave the property false on any controller that browsers or anonymous users can reach. mvn hpi:run sets it so a local development controller accepts an MCP client without a crumb.
Origin header validation
The MCP specification marks validating the Origin header of incoming requests as a MUST.
By default, when an Origin header is present it is validated against the configured Jenkins root URL
(io.jenkins.plugins.mcp.server.Endpoint.requireOriginMatch defaults to true). Requests that do not send
an Origin header are still allowed, so AI agents that omit it keep working
(io.jenkins.plugins.mcp.server.Endpoint.requireOriginHeader defaults to false).
- To also reject requests that omit the
Origin header, set
io.jenkins.plugins.mcp.server.Endpoint.requireOriginHeader=true.
- To disable Origin matching entirely (not recommended), set
io.jenkins.plugins.mcp.server.Endpoint.requireOriginMatch=false.
Connection Resilience
The MCP Server plugin includes several features to improve connection reliability.
The keep-alive and timeout tuning described below primarily concern the SSE transport (/mcp-server/sse), which holds a single long-lived server→client connection open and is therefore sensitive to idle timeouts in Jenkins, proxies, and load balancers. If you use Streamable HTTP (/mcp-server/mcp) with the usual request/response pattern, you are unlikely to need any of it (see Transport Recommendation). The health, metrics, and graceful-shutdown features apply to all transports.
Keep-Alive Messages
For the SSE transport, the server sends periodic keep-alive pings over the open connection to detect broken connections and to stop idle timeouts (in Jenkins, proxies, or load balancers) from closing it. By default, pings 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 for SSE).
[!NOTE]
A ping is only delivered when there is an open server→client stream. SSE always has one. Streamable HTTP only has one while the client keeps a long-lived GET stream open; for a plain POST request/response client there is no stream to ping, so this setting has no effect.
Health Endpoint
A lightweight MCP-specific health endpoint is available for connection monitoring at:
<jenkins-url>/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:
<jenkins-url>/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 the SSE transport behind a reverse proxy or in production environments, configure the timeout settings below so the long-lived connection is not dropped prematurely. Streamable HTTP users generally don't need this (see the note at the end of this section).
Jenkins/Jetty Configuration (SSE)
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 SSE 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 the MCP endpoints. This keeps SSE connections from being closed while idle:
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;
}
[!NOTE]
The one timeout that can also affect Streamable HTTP is proxy_read_timeout: a single long-running tool call (for example a slow triggerBuild) can exceed a short default and return 504 Gateway Timeout. Raising proxy_read_timeout as shown above prevents that regardless of transport. The httpKeepAliveTimeout race condition above is SSE-only.
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:
<jenkins-url>/mcp-server/mcp
- SSE Endpoint:
<jenkins-url>/mcp-server/sse
- Message Endpoint:
<jenkins-url>/mcp-server/message
- Stateless Endpoint:
<jenkins-url>/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:
- Jenkins API Token: Generate an API token from your Jenkins user account.
- 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 <username> and <token> with your actual username and the personal access token you generated in Jenkins
echo -n "<username>:<token>" | base64
[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("<username>:<token>"))
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 <user:token base64>"
}
}
}
}
Copilot Configuration
I tested GitHub Copilot Chat in VS Code with the Streamable HTTP endpoint, and it successfully called the Jenkins getStatus tool. The Copilot CLI and desktop app have not been tested.
{
"mcp": {
"servers": {
"jenkins": {
"type": "http",
"url": "https://jenkins-host/mcp-server/mcp",
"headers": {
"Authorization": "Basic <user:token base64>"
}
}
}
}
}
Streamable example:
{
"servers":{
"jenkins":{
"type":"http",
"url":"http://jenkins-host/mcp-server/mcp",
"requestInit":{
"headers":{
"Authorization":"Basic <user:token base64>"
}
}
}
}
}
Windsurf Configuration
{
"servers": {
"jenkins": {
"command": "npx",
"args": [
"mcp-remote",
"http://jenkins-host/mcp-server/mcp",
"--header",
"Authorization: Bearer ${AUTH_TOKEN}"
],
"env": {
"AUTH_TOKEN": "Basic <user:token base64>"
}
}
}
}
Cursor Configuration
{
"mcpServers": {
"jenkins": {
"type": "http",
"url": "https://jenkins-host/mcp-server/mcp",
"headers": {
"Authorization": "Basic <user:token base64>"
}
}
}
}