{"firstRelease":"2025-06-18T07:18:27.67Z","wikiUrl":"https://github.com/jenkinsci/mcp-server-plugin","buildDate":"2026-11-06","categories":[],"dependencies":[{"name":"commons-lang3-api","title":"commons-lang3 v3.x Jenkins API","optional":false,"version":"3.20.0-109.ve43756e2d2b_4","implied":false},{"name":"jackson3-api","title":"Jackson 3 API","optional":false,"version":"3.2.1-92.vd25c2e23c180","implied":false},{"name":"workflow-cps","title":"Pipeline: Groovy","optional":true,"version":"4360.v2020e8819a_d6","implied":false},{"name":"workflow-job","title":"Pipeline: Job","optional":true,"version":"1571.1580.v18e46842c125","implied":false},{"name":"git","title":"Git","optional":true,"version":"5.10.1","implied":false},{"name":"junit","title":"JUnit","optional":true,"version":"1403.vd9d1413fd205","implied":false}],"maintainers":[{"id":"topikachu","name":"Yi Gong","email":null},{"id":"olamy","name":"Olivier Lamy","email":null}],"excerpt":"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.","gav":"io.jenkins.plugins:mcp-server:0.225.vea_39b_6ff2a_16","labels":["ai","mcp"],"name":"mcp-server","previousTimestamp":"2026-10-28T00:08:29.00Z","previousVersion":"0.222.v9d40a_8d624e4","releaseTimestamp":"2026-11-06T11:35:56.00Z","requiredCore":"2.541.3","scm":{"issues":null,"link":"https://github.com/jenkinsci/mcp-server-plugin","inLatestRelease":null,"sinceLatestRelease":null,"pullRequests":null},"sha1":"E+Gfv77i/NgFyZWAmhNYkfbaTIA=","stats":{"installations":[{"timestamp":1748736000000,"total":32},{"timestamp":1751328000000,"total":128},{"timestamp":1754006400000,"total":307},{"timestamp":1756684800000,"total":420},{"timestamp":1759276800000,"total":508},{"timestamp":1761955200000,"total":647},{"timestamp":1764547200000,"total":751},{"timestamp":1767225600000,"total":972},{"timestamp":1769904000000,"total":1240}],"installationsPercentage":[{"timestamp":1748736000000,"percentage":0.011836508},{"timestamp":1751328000000,"percentage":0.048103843},{"timestamp":1754006400000,"percentage":0.113375336},{"timestamp":1756684800000,"percentage":0.15666673},{"timestamp":1759276800000,"percentage":0.20002362},{"timestamp":1761955200000,"percentage":0.2554586},{"timestamp":1764547200000,"percentage":0.31248438},{"timestamp":1767225600000,"percentage":0.3720389},{"timestamp":1769904000000,"percentage":0.499732}],"installationsPerVersion":[{"version":"0.102.vf677b_eb_da_e4f","total":29},{"version":"0.104.v935c459ca_ee2","total":10},{"version":"0.109.vea_d3ec3083f1","total":4},{"version":"0.116.v335308141e4e","total":479},{"version":"0.119.v479294b_419a_7","total":18},{"version":"0.130.v7837b_2a_5447e","total":21},{"version":"0.138.v7c6a_22ee9160","total":25},{"version":"0.148.v6b_c057f27738","total":1},{"version":"0.149.ve5cd2f59de01","total":426},{"version":"0.158.v8e18e64dd93c","total":26},{"version":"0.16.vc9132432728d","total":4},{"version":"0.17.v941ed9da_c023","total":8},{"version":"0.25.v59ca_c2d5ffc5","total":4},{"version":"0.26.v4a_0d810a_7f71","total":1},{"version":"0.27.v4034b_d4c4cb_5","total":4},{"version":"0.33.vecd845512255","total":6},{"version":"0.37.v5d2d8c089e8b_","total":10},{"version":"0.46.v43ff45cf7fe5","total":15},{"version":"0.57.vc17d46a_5d10b_","total":113},{"version":"0.77.veb_c7b_a_b_f0445","total":7},{"version":"0.86.v7d3355e6a_a_18","total":2},{"version":"0.88.vde1b_2e64212c","total":3},{"version":"0.90.v46fb_a_0b_0e4a_3","total":3},{"version":"0.92.v575c7c143c44","total":10},{"version":"0.95.vb_c1a_8b_ca_216f","total":11}],"installationsPercentagePerVersion":[{"version":"0.102.vf677b_eb_da_e4f","percentage":0.011687281},{"version":"0.104.v935c459ca_ee2","percentage":0.004030097},{"version":"0.109.vea_d3ec3083f1","percentage":0.0016120387},{"version":"0.116.v335308141e4e","percentage":0.19304164},{"version":"0.119.v479294b_419a_7","percentage":0.007254174},{"version":"0.130.v7837b_2a_5447e","percentage":0.008463203},{"version":"0.138.v7c6a_22ee9160","percentage":0.010075242},{"version":"0.148.v6b_c057f27738","percentage":4.0300968E-4},{"version":"0.149.ve5cd2f59de01","percentage":0.17168212},{"version":"0.158.v8e18e64dd93c","percentage":0.010478252},{"version":"0.16.vc9132432728d","percentage":0.0016120387},{"version":"0.17.v941ed9da_c023","percentage":0.0032240774},{"version":"0.25.v59ca_c2d5ffc5","percentage":0.0016120387},{"version":"0.26.v4a_0d810a_7f71","percentage":4.0300968E-4},{"version":"0.27.v4034b_d4c4cb_5","percentage":0.0016120387},{"version":"0.33.vecd845512255","percentage":0.002418058},{"version":"0.37.v5d2d8c089e8b_","percentage":0.004030097},{"version":"0.46.v43ff45cf7fe5","percentage":0.006045145},{"version":"0.57.vc17d46a_5d10b_","percentage":0.045540094},{"version":"0.77.veb_c7b_a_b_f0445","percentage":0.0028210678},{"version":"0.86.v7d3355e6a_a_18","percentage":8.0601935E-4},{"version":"0.88.vde1b_2e64212c","percentage":0.001209029},{"version":"0.90.v46fb_a_0b_0e4a_3","percentage":0.001209029},{"version":"0.92.v575c7c143c44","percentage":0.004030097},{"version":"0.95.vb_c1a_8b_ca_216f","percentage":0.0044331066}],"currentInstalls":1240,"trend":1276},"title":"MCP Server","url":"https://updates.jenkins.io/download/plugins/mcp-server/0.225.vea_39b_6ff2a_16/mcp-server.hpi","version":"0.225.vea_39b_6ff2a_16","securityWarnings":[{"versions":[{"firstVersion":null,"lastVersion":"0.84.v50ca_24ef83f2"}],"id":"SECURITY-3622","message":"Missing permission checks","url":"https://www.jenkins.io/security/advisory/2025-10-29/#SECURITY-3622","active":false},{"versions":[{"firstVersion":null,"lastVersion":"0.177.v629fdb_2557fe"}],"id":"SECURITY-3759","message":"Missing permission check allows reading Pipeline replay scripts","url":"https://www.jenkins.io/security/advisory/2026-06-24/#SECURITY-3759","active":false}],"wiki":{"content":"
\n
\n
\n \n \n \n \n
\n

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.

\n
\n

Features

\n \n \n \n \n
\n \n
\n

Key Components

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

MCP SDK Version

\n \n \n \n \n
\n

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

\n
\n

Getting Started

\n \n \n \n \n
\n
\n

Configuration

\n \n \n \n \n
\n

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

\n
\n

System properties

\n \n \n \n \n
\n

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

\n \n
\n

\n \n \n Warning

\n

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.

\n
\n
\n

Search pattern cost

\n \n \n \n \n
\n

searchBuildLog runs your regular expression against every line of a build log, and some patterns cost far more than their length suggests, because Java's regex engine backtracks.

\n

Each match therefore gets a budget of character reads, and a search that runs past it stops with an error instead of carrying on. The budget is generous on purpose, so you are unlikely to meet it. If you do, simplify the pattern or search for plain text with useRegex=false, which has no budget.

\n
\n

Origin header validation

\n \n \n \n \n
\n

The MCP specification marks validating the Origin header of incoming requests as a MUST.

\n

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).

\n \n
\n

Connection Resilience

\n \n \n \n \n
\n

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

\n

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.

\n
\n

Keep-Alive Messages

\n \n \n \n \n
\n

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.

\n

You can configure this interval with the system property:

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

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

\n
\n

\n \n \n Note

\n

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. Those clients are covered by Idle Session Cleanup instead.

\n
\n
\n

Idle Session Cleanup

\n \n \n \n \n
\n

A Streamable HTTP session outlives the connection it was created on, because the protocol lets a client reconnect to a session it was disconnected from. A client that disappears without sending DELETE /mcp-server/mcp therefore leaves its session behind, along with the socket and servlet async context behind it. Left alone, those pile up until the controller runs out of file descriptors.

\n

The server reclaims them: a session with no open stream that has gone a full interval without a request is closed and dropped. The interval defaults to 30 minutes, so a stranded session lives for 30 to 60 minutes.

\n

You can configure it with the system property:

\n
\n 
io.jenkins.plugins.mcp.server.Endpoint.sessionSweepInterval=1800\n
\n
\n

Set to 0 to keep sessions until the client deletes them or Jenkins restarts. That is the old behaviour, and it leaks.

\n

A client whose session was reclaimed gets 404 on its next request and should start a new one with initialize, which is what the protocol asks of it. To watch the cleanup, add a Jenkins log recorder at DEBUG on io.modelcontextprotocol.server.transport.HttpServletStreamableServerTransportProvider and look for Evicting idle session, or read streamableSessionsActive from the metrics endpoint.

\n
\n

Health Endpoint

\n \n \n \n \n
\n

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

\n
/mcp-health\">\n 
<jenkins-url>/mcp-health\n
\n
\n

This endpoint:

\n \n

Response format:

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

Recommended client usage:

\n \n
\n

Metrics Endpoint

\n \n \n \n \n
\n

A metrics endpoint is available for monitoring connection statistics at:

\n
/mcp-server/metrics\">\n 
<jenkins-url>/mcp-server/metrics\n
\n
\n

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

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

streamableSessionsActive is the number of Streamable HTTP sessions the server is currently holding. It is left out when the streamable endpoint is disabled or has not served a request yet.

\n
\n

Graceful Shutdown

\n \n \n \n \n
\n

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.

\n
\n

Transport Recommendation

\n \n \n \n \n
\n

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.

\n
\n

Production Deployment

\n \n \n \n \n
\n

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).

\n

Jenkins/Jetty Configuration (SSE)

\n

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.

\n

Add this argument to your Jenkins startup command:

\n
\n 
--httpKeepAliveTimeout=600000\n
\n
\n

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

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

Reverse Proxy Configuration (Nginx)

\n

For Nginx, extend timeouts for the MCP endpoints. This keeps SSE connections from being closed while idle:

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

\n \n \n Note

\n

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.

\n
\n
\n

Transport Endpoints

\n \n \n \n \n
\n

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

\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
TransportEndpointDescription
SSE/mcp-server/sse + /mcp-server/messageServer-Sent Events transport with session management
Streamable HTTP/mcp-server/mcpStreamable HTTP transport with session management
Stateless/mcp-server/statelessStateless HTTP transport without session management
\n \n

Each transport can be disabled independently using system properties:

\n
\n 
-Dio.jenkins.plugins.mcp.server.Endpoint.disableMcpSse=true\n-Dio.jenkins.plugins.mcp.server.Endpoint.disableMcpStreamable=true\n-Dio.jenkins.plugins.mcp.server.Endpoint.disableMcpStateless=true\n
\n
\n
\n
When to use Stateless transport
\n \n \n \n \n
\n

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

\n \n
\n

Usage

\n \n \n \n \n
\n
\n

Connecting to the MCP Server

\n \n \n \n \n
\n

MCP clients can connect to the server using:

\n \n
\n

Authentication and Credentials

\n \n \n \n \n
\n

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

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

Generate a personal access token

\n \n \n \n \n
\n

To generate a personal access token:

\n \n
\n

\n \n \n Warning

\n

Once you leave the page, you cannot view or copy the token again.

\n
\n \n
\n

Encode credentials for HTTP basic authentication

\n \n \n \n \n
\n

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

\n

To encode credentials on Linux, macOS, or Windows:

\n

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

\n \n
:" | base64\">\n 
echo -n \"<username>:<token>\" | base64
\n
\n \n
:"))\">\n 
[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(\"<username>:<token>\"))
\n
\n

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

\n
\n 
dXNlcm5hbWU6dG9rZW4=
\n
\n

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

\n
\n

\n \n \n Note

\n

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.

\n
\n
\n

Example Client Configurations

\n \n \n \n \n
\n
\n

Cline Configuration

\n \n \n \n \n
\n
"\n }\n }\n }\n}\">\n 
{\n  \"mcpServers\": {\n    \"jenkins\": {\n      \"autoApprove\": [\n        \n      ],\n      \"disabled\": false,\n      \"timeout\": 60,\n      \"type\": \"streamableHttp\",\n      \"url\": \"https://jenkins-host/mcp-server/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Basic <user:token base64>\"\n      }\n    }\n  }\n}
\n
\n
\n

Copilot Configuration

\n \n \n \n \n
\n

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.

\n
"\n }\n }\n }\n }\n}\">\n 
{\n  \"mcp\": {\n    \"servers\": {\n      \"jenkins\": {\n        \"type\": \"http\",\n        \"url\": \"https://jenkins-host/mcp-server/mcp\",\n        \"headers\": {\n          \"Authorization\": \"Basic <user:token base64>\"\n        }\n      }\n    }\n  }\n}
\n
\n

Streamable example:

\n
"\n }\n }\n }\n }\n}\">\n 
{\n  \"servers\":{\n    \"jenkins\":{\n      \"type\":\"http\",\n      \"url\":\"http://jenkins-host/mcp-server/mcp\",\n      \"requestInit\":{\n        \"headers\":{\n          \"Authorization\":\"Basic <user:token base64>\"\n        }\n      }\n    }\n  }\n}
\n
\n
\n

Windsurf Configuration

\n \n \n \n \n
\n
"\n }\n }\n }\n}\">\n 
{\n  \"servers\": {\n    \"jenkins\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"mcp-remote\",\n        \"http://jenkins-host/mcp-server/mcp\",\n        \"--header\",\n        \"Authorization: Bearer ${AUTH_TOKEN}\"\n      ],\n      \"env\": {\n        \"AUTH_TOKEN\": \"Basic <user:token base64>\"\n      }\n    }\n  }\n}
\n
\n
\n

Cursor Configuration

\n \n \n \n \n
\n
"\n }\n }\n }\n}\">\n 
{\n  \"mcpServers\": {\n    \"jenkins\": {\n      \"type\": \"http\",\n      \"url\": \"https://jenkins-host/mcp-server/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Basic <user:token base64>\"\n      }\n    }\n  }\n}
\n
\n
\n

Claude

\n \n \n \n \n
\n
"\">\n 
claude mcp add jenkins http://jenkins-host/mcp-server/mcp --transport http --header \"Authorization: Basic <user:token base64>\"
\n
\n
\n

Stateless Configuration Example

\n \n \n \n \n
\n

For clients that prefer stateless communication without session management:

\n
"\n }\n }\n }\n }\n}\">\n 
{\n  \"servers\": {\n    \"jenkins\": {\n      \"type\": \"http\",\n      \"url\": \"http://jenkins-host/mcp-server/stateless\",\n      \"requestInit\": {\n        \"headers\": {\n          \"Authorization\": \"Basic <user:token base64>\"\n        }\n      }\n    }\n  }\n}
\n
\n
\n

Goose

\n \n \n \n \n
\n \n
\n

Available Tools

\n \n \n \n \n
\n

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

\n
\n

Job Management

\n \n \n \n \n
\n \n
\n

Build Information

\n \n \n \n \n
\n \n
\n

SCM Integration

\n \n \n \n \n
\n \n
\n

Management Information

\n \n \n \n \n
\n \n

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.

\n

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

\n
\n

Enhanced Parameter Support

\n \n \n \n \n
\n

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

\n
\n

Supported Parameter Types

\n \n \n \n \n
\n \n
\n

Parameter Handling Features

\n \n \n \n \n
\n \n
\n

Example Usage

\n \n \n \n \n
\n
\n 
{\n  \"jobFullName\": \"my-parameterized-job\",\n  \"parameters\": {\n    \"BRANCH\": \"main\",\n    \"DEBUG_MODE\": true,\n    \"ENVIRONMENT\": \"production\",\n    \"FEATURES\": [\"feature1\", \"feature2\"],\n    \"NOTES\": \"Build triggered via MCP\"\n  }\n}
\n
\n
\n

Extending MCP Capabilities

\n \n \n \n \n
\n

To add new MCP tools or functionalities:

\n
    \n
  1. Create a class implementing McpServerExtension.
    2. \n
  2. Use @Tool to expose methods as MCP tools.
    3. \n
  3. Use @ToolParam to define and describe tool parameters.
    4. \n
\n

Example:

\n
\n 
@Extension\npublic class MyCustomMcpExtension implements McpServerExtension {\n\t@Tool(description = \"My custom tool\")\n\tpublic String myCustomTool(@ToolParam(description = \"Input parameter\") String input) {\n\t\t// Tool implementation\n\t}\n}
\n
\n
\n

Constraining parameter values

\n \n \n \n \n
\n

For an object-shaped parameter (typically a Map), you can advertise a JSON Schema constraint on the values while keeping the keys open, using @ToolParam(additionalProperties = \"<json>\"). The value is a raw JSON sub-schema — a JSON object or a boolean — emitted verbatim as the parameter's additionalProperties:

\n
options) {\n // Tool implementation\n}\">\n 
@Tool(description = \"My custom tool\")\npublic String myCustomTool(\n        @ToolParam(\n                description = \"Extra options\",\n                required = false,\n                additionalProperties = \"{\\\"type\\\":[\\\"string\\\",\\\"boolean\\\",\\\"integer\\\",\\\"number\\\",\\\"array\\\"]}\")\n        Map<String, Object> options) {\n    // Tool implementation\n}
\n
\n

Invalid JSON, or a value that isn't a JSON object or boolean, fails fast when the tool is registered.

\n
\n

Restricting a tool by permission

\n \n \n \n \n
\n

Add permissions to @Tool to require the caller to hold a Jenkins permission. List one or more permission ids (as returned by Permission.getId(), for example hudson.model.Hudson.SystemRead):

\n
\n 
@Tool(\n        description = \"Read the Jenkins system log\",\n        permissions = {\"hudson.model.Hudson.SystemRead\"})\npublic SystemLog readSystemLog() {\n    // ...\n}
\n
\n

The caller must hold at least one of the listed permissions. A tool that fails the check is hidden from tools/list and rejected on tools/call. When Jenkins security is disabled, every tool is available. Permission ids are resolved when the server starts, so a typo fails fast. For a sensitive operation, still call Jenkins.get().checkPermission(...) inside the method as defence in depth.

\n

Overall permissions only. The check runs against the Jenkins root, so permissions is for global permissions such as Overall/SystemRead or Overall/Administer. It cannot express item-scoped permissions like Item.READ on a particular folder or job — a tool has no item context. Enforce those inside the method against the specific item (for example job.checkPermission(Item.READ)).

\n
\n

Overriding a Built-in Tool

\n \n \n \n \n
\n

You can replace a built-in tool (or any tool contributed by another plugin) with your own implementation from a separate plugin. Declare a @Tool with the same name and set override = true:

\n
\n 
@Extension\npublic class MyBuildLogExtension implements McpServerExtension {\n\t@Tool(name = \"getBuildLog\", description = \"My own getBuildLog\", override = true)\n\tpublic MyResponse getBuildLog(@ToolParam(description = \"Job full name\") String jobFullName) {\n\t\t// Your implementation replaces the built-in getBuildLog\n\t}\n}
\n
\n

Rules:

\n \n
\n

Result Handling

\n \n \n \n \n
\n

The MCP Server Plugin handles various result types with the following approach:

\n \n

For serialization to text content:

\n \n
\n

Field selection with tree and per-tool defaults

\n \n \n \n \n
\n

Tools returning @ExportedBean objects accept an optional tree parameter using the Jenkins Remote REST API tree syntax (for example tree=name,url,lastBuild[number,result]) to limit which fields are returned.

\n

A tool may also declare a default tree (@Tool(defaultTree = \"...\")), applied only when the caller does not pass tree. The built-in getBuild, getJob and getJobs tools use such compact defaults: without an explicit tree they return the identity/status essentials rather than the full exported model, which keeps responses small for LLM context windows. Pass your own tree expression to request any other fields — an explicit tree always takes precedence over the default, and passing tree=\"*\" returns the full exported object (pruning disabled), bypassing the default entirely. Tools without a declared default keep returning the full exported object.

\n

This approach ensures flexible and efficient handling of different result types, accommodating both Jenkins-specific exported objects and standard Java objects. This flexible approach ensures that tool results are consistently and accurately represented in the MCP response, regardless of their complexity.

\n
\n

Integration with GitHub Copilot

\n \n \n \n \n
\n

The MCP Server Plugin seamlessly integrates with GitHub Copilot, enhancing your development experience by providing direct access to Jenkins information within your IDE. This integration allows you to interact with Jenkins jobs and builds using natural language queries. \"GitHub

\n

As shown in the screenshot:

\n
    \n
  1. You can ask Copilot about Jenkins jobs using natural language, e.g., \"list jenkins job under root\".
    2. \n
  2. Copilot uses the MCP Server to fetch and display information about Jenkins jobs, listing the jobs under the root directory.
    3. \n
  3. You can also request specific information, such as \"get the last build status of job a\", and Copilot will provide the relevant details including build number, status, and URL.
    4. \n
\n

This integration streamlines your workflow by allowing you to access Jenkins information without leaving your development environment.

\n
\n

Further Information

\n \n \n \n \n
\n

For more details on the Model Context Protocol and its Java SDK:

\n \n
\n

Contributing

\n \n \n \n \n
\n

Contributions to the MCP Server plugin are welcome. Please refer to the Jenkins contribution guidelines for more information.

\n
\n

License

\n \n \n \n \n
\n

This project is licensed under the MIT License - see the LICENSE file for details.

\n
\n
","url":"https://github.com/jenkinsci/mcp-server-plugin"},"defaultBranch":"main"}