Adding mcp server to claude causes "error: missing required argument 'commandOrUrl'"

[jMyles]

Jenkins and plugins versions report

Environment

Jenkins: 2.528.2
OS: Linux - 6.8.0-71-generic
Java: 17.0.17 - Eclipse Adoptium (OpenJDK 64-Bit Server VM)
---
antisamy-markup-formatter:173.v680e3a_b_69ff3
apache-httpcomponents-client-4-api:4.5.14-269.vfa_2321039a_83
asm-api:9.9-185.va_6c6b_3348b_c3
bootstrap5-api:5.3.8-895.v4d0d8e47fea_d
bouncycastle-api:2.30.1.82-277.v70ca_0b_877184
branch-api:2.1259.v45c101731c76
build-name-setter:2.5.1
caffeine-api:3.2.3-194.v31a_b_f7a_b_5a_81
checks-api:373.vfe7645102093
cloudbees-folder:6.1073.va_7888eb_dd514
commons-compress-api:1.28.0-1
commons-lang3-api:3.19.0-104.v12125f33a_255
commons-text-api:1.14.0-194.v804a_dc3a_1b_d8
configuration-as-code:2006.v001a_2ca_6b_574
credentials:1447.v4cb_b_539b_5321
credentials-binding:702.vfe613e537e88
dark-theme:574.va_19f05d54df5
display-url-api:2.217.va_6b_de84cc74b_
durable-task:635.v3733cef34b_5e
echarts-api:6.0.0-1165.vd1283a_3e37d4
font-awesome-api:7.1.0-882.v1dfb_771e3278
git:5.8.0
git-client:6.4.0
github:1.45.0
github-api:1.330-492.v3941a_032db_2a_
github-branch-source:1917.v9ee8a_39b_3d0d
gson-api:2.13.2-173.va_a_092315913c
instance-identity:203.v15e81a_1b_7a_38
ionicons-api:94.vcc3065403257
jackson2-api:2.20.1-423.v13951f6b_6532
jakarta-activation-api:2.1.3-2
jakarta-mail-api:2.1.3-3
jakarta-xml-bind-api:4.0.5-3.v3d5b_a_73965b_9
javax-activation-api:1.2.0-8
jaxb:2.3.9-133.vb_ec76a_73f706
jjwt-api:0.11.5-120.v0268cf544b_89
job-dsl:1.93
joda-time-api:2.14.0-149.v1c3ce991d1b_9
jquery3-api:3.7.1-619.vdb_10e002501a_
json-api:20250517-173.v596efb_962a_31
json-path-api:2.10.0-202.va_9cc16c1e476
junit:1369.v15da_00283f06
mailer:522.va_995fa_cfb_8b_d
mask-passwords:212.v4967a_a_73b_506
matrix-auth:3.2.8
matrix-project:870.v9db_fcfc2f45b_
mcp-server:0.116.v335308141e4e
metrics:4.2.37-489.vb_6db_69b_ce753
mina-sshd-api-common:2.16.0-167.va_269f38cc024
mina-sshd-api-core:2.16.0-167.va_269f38cc024
okhttp-api:4.12.0-195.vc02552c04ffd
pipeline-build-step:571.v08a_fffd4b_0ce
pipeline-github:2.8-162.382498405fdc
pipeline-graph-analysis:245.v88f03631a_b_21
pipeline-graph-view:661.v6003f4542123
pipeline-groovy-lib:787.ve2fef0efdca_6
pipeline-input-step:540.v14b_100d754dd
pipeline-milestone-step:138.v78ca_76831a_43
pipeline-model-api:2.2277.v00573e73ddf1
pipeline-model-definition:2.2277.v00573e73ddf1
pipeline-model-extensions:2.2277.v00573e73ddf1
pipeline-rest-api:2.38
pipeline-stage-step:322.vecffa_99f371c
pipeline-stage-tags-metadata:2.2277.v00573e73ddf1
pipeline-stage-view:2.38
pipeline-utility-steps:2.20.0
plain-credentials:199.v9f8e1f741799
plugin-util-api:6.1192.v30fe6e2837ff
prism-api:1.30.0-630.va_e19d17f83b_0
scm-api:712.v8846fdd68c88
script-security:1385.v7d2d9ec4d909
snakeyaml-api:2.5-143.v93b_c004f89de
ssh-credentials:361.vb_f6760818e8c
structs:362.va_b_695ef4fdf9
theme-manager:327.v780d7096ec29
token-macro:477.vd4f0dc3cb_cf1
variant:70.va_d9f17f859e0
workflow-aggregator:608.v67378e9d3db_1
workflow-api:1384.vdc05a_48f535f
workflow-basic-steps:1098.v808b_fd7f8cf4
workflow-cps:4218.vff679a_5c0f3a_
workflow-durable-task-step:1464.v2d3f5c68f84c
workflow-job:1559.va_a_533730b_ea_d
workflow-multibranch:821.vc3b_4ea_780798
workflow-scm-step:466.va_d69e602552b_
workflow-step-api:710.v3e456cc85233
workflow-support:1004.veee3a_d67cdb_9

What Operating System are you using (both controller, and any agents involved in the problem)?

It is of course possible that this is a claude code bug, but I can't find any reference to "commandOrURL" among their issues. Happy to dig further as needed. Thanks so much for this plugin!

Reproduction steps

1. Be using claude code 2.0.42
2. Run the example command provided in the plugin documented (claude mcp add http://jenkins-host/mcp-server/mcp --transport http --header "Authorization: Basic <user:token base64>")
3. See the error

Expected Results

For the MCP server to be installed.

Actual Results

error: missing required argument 'commandOrUrl'

Anything else?

No response

Are you interested in contributing a fix?

No response

[olamy]

using this command?
https://github.com/jenkinsci/mcp-server-plugin?tab=readme-ov-file#claude

[adrianrobinsondev]

I got the same error trying to add the Jenkins MCP to Claude Code. Had to modify the command syntax a bit to get the mcp server added.

Move the transport flag earlier and add a mcp name (e.g. 'jenkins').

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

That got the mcp server added, but failed to authenticate.

Claude Code says: "Error: The socket connection was closed unexpectedly."

jenkinsmcpbug95.txt

I did verify that my Base64 token worked against the Jenkins MCP using curl:

curl -H "Authorization: Basic <user:token base64>" http://jenkins-host/mcp-server/mcp

Resulted in a huge response that I think was complaining that a Session ID is missing. I changed 1 character in the token to test and got a clear Error 401 Unauthorized so I know the first attempt at least authenticated successfully.

The authenticated response ended with:

{"classLoaderName":null,"moduleName":"java.base","moduleVersion":"21","methodName":"run","fileName":"Thread.java","lineNumber":1583,"className":"java.lang.Thread","nativeMethod":false}],"jsonRpcError":null,"message":"text/event-stream required in Accept header; Session ID required in mcp-session-id header","suppressed":[],"localizedMessage":"text/event-stream required in Accept header; Session ID required in mcp-session-id header"}

Guessing that Claude Code is closing the socket due to the missing session id mentioned in the response?

Full output attached.

[olamy]

is oauth mandatory now to connect to MCP with Claude?

[topikachu]

I got the same error trying to add the Jenkins MCP to Claude Code. Had to modify the command syntax a bit to get the mcp server added.

Move the transport flag earlier and add a mcp name (e.g. 'jenkins').

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

That got the mcp server added, but failed to authenticate.

Claude Code says: "Error: The socket connection was closed unexpectedly."

jenkinsmcpbug95.txt

I did verify that my Base64 token worked against the Jenkins MCP using curl:

curl -H "Authorization: Basic <user:token base64>" http://jenkins-host/mcp-server/mcp

Resulted in a huge response that I think was complaining that a Session ID is missing. I changed 1 character in the token to test and got a clear Error 401 Unauthorized so I know the first attempt at least authenticated successfully.

The authenticated response ended with:

{"classLoaderName":null,"moduleName":"java.base","moduleVersion":"21","methodName":"run","fileName":"Thread.java","lineNumber":1583,"className":"java.lang.Thread","nativeMethod":false}],"jsonRpcError":null,"message":"text/event-stream required in Accept header; Session ID required in mcp-session-id header","suppressed":[],"localizedMessage":"text/event-stream required in Accept header; Session ID required in mcp-session-id header"}

Guessing that Claude Code is closing the socket due to the missing session id mentioned in the response?

Full output attached.

It seems Claude doesn't send mcp-session-id in the header. Could you try the new plugin with /mcp-server/stateless endpoint?

[adrianrobinsondev]

Got the mcp updated with latest release, confirmed /stateless endpoint is alive, and updated claude config with new endpoint, but still no luck. Here's the debug output from Claude Code:

2026-02-02T13:22:39.499Z [DEBUG] MCP server "jenkins-server": Proxy options: default
2026-02-02T13:22:39.500Z [DEBUG] MCP server "jenkins-server": HTTP transport options: {"url":"http://jenkins-server:{portNum}/mcp-server/stateless","headers":{"User-Agent":"claude-code/2.1.29","Authorization":"[REDACTED]"},"hasAuthProvider":true,"timeoutMs":60000}
2026-02-02T13:22:39.500Z [DEBUG] MCP server "jenkins-server": HTTP transport created successfully
2026-02-02T13:22:39.501Z [DEBUG] MCP server "jenkins-server": Client created, setting up request handler
2026-02-02T13:22:39.502Z [DEBUG] MCP server "jenkins-server": Starting connection with timeout of 30000ms
2026-02-02T13:22:39.502Z [DEBUG] MCP server "jenkins-server": Testing basic HTTP connectivity to http://jenkins-server:{portNum}/mcp-server/stateless
2026-02-02T13:22:39.502Z [DEBUG] MCP server "jenkins-server": Parsed URL: host=jenkins-server, port={portNum}, protocol=http:
2026-02-02T13:22:39.503Z [DEBUG] [API:auth] OAuth token check complete
2026-02-02T13:22:39.506Z [DEBUG] MCP server "jenkins-server": No token data found
2026-02-02T13:22:39.535Z [DEBUG] MCP server "jenkins-server": HTTP Connection failed after 63ms: The socket connection was closed unexpectedly. For more information, pass verbose: true in the second argument to fetch() (code: ECONNRESET, errno: none)
2026-02-02T13:22:39.536Z [ERROR] MCP server "jenkins-server" Error: The socket connection was closed unexpectedly. For more information, pass verbose: true in the second argument to fetch()
2026-02-02T13:22:39.537Z [DEBUG] MCP server "jenkins-server": Connection failed after 64ms: The socket connection was closed unexpectedly. For more information, pass verbose: true in the second argument to fetch()
2026-02-02T13:22:39.537Z [ERROR] MCP server "jenkins-server" Connection failed: The socket connection was closed unexpectedly. For more information, pass verbose: true in the second argument to fetch()

How do we get the verbose fetch() info?

[sergeykad]

The correct command is:

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

The problem is that you need to take user:token and encode it using base64, which was not immediately clear from the documentation.

E.g. echo -n 'username:11679d8d843f345d7df152e39341f15d' | base64

[adrianrobinsondev]

The correct command is:

claude mcp add --transport http jenkins-mcp http://jenkins-host/mcp-server/mcp \
--header "Authorization: Basic <user:token base64>"
The problem is that you need to take user:token and encode it using base64, which was not immediately clear from the documentation.

E.g. echo -n 'username:11679d8d843f345d7df152e39341f15d' | base64

I did all of that as outlined in my earlier post. I even verified the encoded token worked with curl.

[adrianrobinsondev]

Additional troubleshooting today involved me setting up user authentication logging in a test Jenkins server upgraded to Jenkins 2.541.1 running Jenkins MCP Server 0.149.ve5cd2f59de01.

I confirmed authentication logging by authenticating via the UI with my mcp user account. I then confirmed seeing a successful authentication logged using curl with my Base64 encoded token for the mcp user. I then tried launching Claude Code in debug mode using SSE, HTTP, and Stateless configurations just to see what was logged via Claude Code and Jenkins for all 3 transports. The results were interesting.

In short, the only transport that logged an authentication attempt at all was SSE. I was only using a short host to access my Jenkins server in which case SSE complained that the endpoint origin didn't match the connection origin. This was nice to prove that some communication was occurring after a successful authentication as confirmed on the Jenkins server log.

I updated the host to include the domain in my claude.json. This resulted in another successful authentication logged by Jenkins, but still a failure to establish an MCP connection in Claude Code.

I moved on to http transport which did not show an authentication attempt at all in Jenkins, not even a failure.

Finally, I tried stateless which also did not show an authentication attempt in Jenkins.

The common Claude Code log message for all 3 transports is that the MCP server didn't supply a token.

Claude Code logging is attached with private info obfuscated and/or redacted.

jenkinsmcpbug95_2.txt

[zbynek]

Is this fixed in https://github.com/jenkinsci/mcp-server-plugin/pull/158/changes ?