As of May 31, 2026, the local CloudBees Unify MCP Server (stdio transport) is deprecated.
This guide walks you through migrating to the remote CloudBees Unify MCP Server at https://mcp.cloudbees.io/v1/mcp.
Allow approximately 10 minutes for each AI client.
Before you begin
Confirm you have the following resources:
-
An active CloudBees Unify account.
-
An AI client that currently uses a local CloudBees Unify MCP Server (stdio transport).
-
Access to your AI client’s configuration file or settings.
Read Connect AI agents to CloudBees Unify for an overview of the remote CloudBees Unify MCP Server.
What’s changing
| Aspect | Local server (deprecated) | Remote server (current) |
|---|---|---|
Where it runs |
Locally on each developer machine |
Hosted by CloudBees |
Authentication |
Local configuration files |
OAuth (same sign-in as CloudBees Unify web interface) |
Switching organizations |
Edit configuration file |
Reauthenticate to select different organization |
Installation |
Binary or Docker image per machine |
No installation, configure your AI client |
Updates |
Manual, per machine |
Managed by CloudBees |
Status |
Planned deprecation |
Current |
Why migrate
This migration changes the following two things:
-
Hosting model: You move from a local binary or Docker image to a CloudBees-hosted remote server.
-
Authentication method: You replace your
<CLOUDBEES_PERSONAL_ACCESS_TOKEN>with an OAuth sign-in flow (the same credentials you use for the CloudBees Unify web interface). After migrating, you no longer need to manage API tokens.
The remote CloudBees Unify MCP Server provides several advantages over the local server:
-
Zero-install: No binary or Docker image to keep up to date on each machine.
-
Consistent versions: Every client uses the same tool catalog.
-
OAuth authentication: Sign in with the same credentials as the CloudBees Unify web interface. No API tokens to generate, rotate, or revoke.
-
Easy organization switching: Reauthenticate to switch Root Organizations without editing configuration files.
-
Required going forward: The local server is deprecated; new capabilities are only available through the remote server.
Migration steps
Perform the following steps to migrate to the remote CloudBees Unify MCP Server:
Step 1: Inventory your existing local server configurations
List every AI client on every machine using a local CloudBees Unify MCP Server.
Look for entries named unify, cloudbees-unify-mcp, or similar in:
-
Claude Code:
~/.claude.json -
Claude Desktop: Select Settings, Developer, MCP Servers
-
Claude.ai: Select Settings, Connectors
Note which clients are using a local server.
Step 2: Update your AI client configuration
Update each client to use the remote server. The exact configuration depends on your AI client.
Refer to the client-specific connection guides:
The key differences in your configuration:
{ "mcpServers": { "unify-mcp-server": { "type": "stdio", "command": "docker", "args": [ "run", "--rm", "-i", "--env", "CLOUDBEES_PERSONAL_ACCESS_TOKEN", "cloudbees/unify-mcp-server:latest", "stdio", "--mode=unify", "--organization-id=XX" ], "env": { "CLOUDBEES_PERSONAL_ACCESS_TOKEN": "XX" } } } }
{ "mcpServers": { "unify-mcp-server": { "type": "http", "url": "https://mcp.cloudbees.io/v1/mcp", "oauth": { "clientId": "public-mcp-client" } } } }
| With the remote server, authentication happens through the OAuth flow when you first connect, not through configuration files. |
Step 3: Authenticate with OAuth
When you first connect your AI client:
-
The OAuth flow opens in your web browser.
-
Sign in using Google, GitHub, or SSO.
-
Select your Root Organization.
-
Your AI client stores your credentials securely.
This is a one-time setup per client.
Step 4: Verify the connection
In your AI client, ask a simple question:
You should see a list of components within a few seconds.
If your AI client reports that it doesn’t have the tool available, or that it cannot reach CloudBees Unify, refer to Troubleshooting.
| Your existing conversations in Claude Code or Claude Desktop will continue to work. Conversations are not tied to a specific connection; once the new configuration is active, new tool calls use the remote server. Consider starting a new conversation after migrating to avoid mixing contexts. |
Step 5: Remove the local CloudBees Unify MCP Server
Once you’ve confirmed the remote server works:
-
Remove the local server binary or Docker image:
-
Binary (macOS / Linux):
rm /usr/local/bin/cloudbees-unify-mcp-server -
Docker:
docker image rm cloudbees/unify-mcp-server
-
-
Remove any environment variables,
launchdunits, orsystemdunits that started the local server. -
Delete any legacy API tokens from the Unify UI to reduce the token footprint if it is only meant for MCP usage.
Can I run both servers side-by-side?
Technically yes, but CloudBees does not recommend it.
If both are configured, AI clients may route identical tool calls to either connection, which makes results inconsistent and harder to debug. Select one connection per client and use it consistently.
If you need a brief overlap period while rolling out the change across a team, keep the local server only on machines that haven’t migrated yet, and move each machine fully to the remote server as soon as possible.
Troubleshooting
| Symptom | Likely root cause | Solution |
|---|---|---|
"Server not reachable" |
Network or TLS issue |
|
"Unauthorized" on every tool call. |
Authentication failed or expired. |
Disconnect and reconnect to trigger a new OAuth flow. Check that you selected the correct organization. |
Tool calls fail with permission errors. |
Your Unify role lacks permissions to access specific resources. |
All tools are visible, but RBAC is enforced at the resource level. Ask an admin to grant access to the resources you need, or verify you selected the correct organization during OAuth. |
Tool calls intermittently fail. |
Client is load-balancing between local and remote servers. |
Remove the local server configuration entirely and restart the client. |
If problems persist, refer to Troubleshooting or contact CloudBees Support.