Introduction
Understanding organizationsUnderstanding componentsManage organizationsManage componentsManage component Jira integrations
Set up your first organizationUnderstanding users and teamsUnderstanding role-based access controlManage usersManage teamsConfigure role-based access controlRBAC permissions reference
Understanding authentication in CloudBees UnifySet up multifactor authenticationConfigure SAML single sign-onConfigure OIDC authenticationConfigure network security policiesNetwork security reference
Understanding platform configurationUnderstanding environmentsManage properties and secretsManage environmentsTrack environment inventoryConfigure containersSet up preconfigured actionsConfigure notifications
Accessibility policy referenceShared responsibility model referenceSubscription and services agreementSupport policiesSupported browsers and external tools
Introduction
Understanding feature managementUnderstanding Configuration as CodeGet started with feature managementCreate and manage feature flagsConfigure feature flag targetingOrganize feature flagsImplement feature flag governanceConfiguration as Code reference
Understanding flag impressions and activity statusUnderstanding flag healthUnderstanding code referencesReview and clean up feature flagsSet up code references
Understanding Jira integration for feature flagsSet up the Jira integrationLink Jira tickets to feature flags
Understanding multiple SDK keysBuild your first mobile app with feature flagsBuild your first feature-flagged web applicationBuild your first feature-flagged backend serviceInstall client-side SDKsInstall server-side SDKsConfigure multiple SDK keysMobile SDK referenceWeb SDK referenceBackend SDK referenceClient SDK referenceFlag implementation reference
Introduction
Understanding CI workflowsCreate a build workflowCreate and manage workflowsCreate reusable workflowsTest and validate containers in workflowsCheck out source codeTrigger workflows remotelyWorkflow syntax referenceJobs syntax referenceSteps syntax referenceServices syntax reference
Monitor workflow runsView test results in runsView evidence in runsView deployments in runsManage workflow artifactsPublish test resultsPublish evidence itemsGenerate a software bill of materialsManage ServiceNow change requests
Configure workflow credentialsConfigure AWS credentialsConfigure container registry credentialsConfigure Git credentialsIntegrate external secret providers
Understanding GitHub Actions integrationSet up GitHub Actions integrationDisplay GitHub Actions workflows and runsRegister GHA build artifactsPublish GHA deployed artifactsPublish GHA test resultsPublish GHA evidence itemsTrigger CloudBees workflows from GitHub ActionsScan with GitHub Actions
Understanding CloudBees CI and Jenkins® integrationConnect CI and Jenkins controllersMonitor CI and Jenkins buildsRegister CI build artifactsRegister CI deployed artifactsPublish CI test resultsConfigure CI security scanningCI and Jenkins integration reference
Build and publish container imagesUnderstanding external CI/CD integrationsRun external CI/CD jobsExternal CI/CD action reference
Introduction
Understanding release orchestrationManage applicationsCreate deployer workflowsCreate staged workflowsCreate and manage releasesOrchestrate multi-workflow releasesRelease management reference
Understanding artifact managementRegister and track artifactsStore and retrieve artifactsPromote artifactsGenerate a software bill of materialsArtifact management reference
Deploy with HelmDeploy to KubernetesContainer deployment reference
Deploy to AWSAWS deployment reference
Deploy with enterprise platformsExecute remote deployment commandsEnterprise deployment reference
Verify deployments with New RelicDeployment verification reference

Migrate to the remote CloudBees Unify MCP Server

3 minute read

Migrate each AI client from the deprecated local CloudBees Unify MCP Server (stdio transport) to the CloudBees-hosted remote server at https://mcp.cloudbees.io/v1/mcp. For background on the remote server and what changed, refer to Understanding the CloudBees Unify MCP Server.

Allow approximately 10 minutes per AI client.

Before you begin

  • Have an active CloudBees Unify account.

  • Have an AI client currently configured to use a local CloudBees Unify MCP Server (stdio transport).

  • Have access to your AI client’s configuration file or settings.

Inventory your existing local server configurations

Identify every AI client using a local server before making any configuration changes.

  1. List every AI client on every machine that uses 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

  2. Note which clients are using a local server.

Update your AI client configuration

Update each client to point at the remote server using the HTTP transport.

  1. For each client, replace the stdio transport configuration with the HTTP transport configuration:

    Before (stdio transport)
    After (HTTP transport)
    {
  "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.

  2. For client-specific configuration steps, refer to:

CloudBees does not recommend running the local and remote servers in parallel. If both are configured, AI clients may route identical tool calls to either connection, making results inconsistent and harder to debug. Move each machine fully to the remote server before configuring the next.

Authenticate with OAuth

When you first connect your AI client after updating the configuration, the OAuth flow runs automatically.

  1. The OAuth flow opens in your web browser.

  2. Sign in using Google, GitHub, or SSO.

  3. Select your Root Organization.

  4. Your AI client stores your credentials securely.

This is a one-time setup per client.

Verify the connection

Confirm the remote server is reachable and responding before removing the local server.

  1. In your AI client, ask the following question:

    "List the CloudBees Unify components I have access to."

  2. Confirm that a list of components appears within a few seconds.

  3. If your AI client reports that the tool is unavailable or cannot reach CloudBees Unify, refer to Troubleshoot CloudBees Unify MCP Server issues.

Your existing conversations in Claude Code or Claude Desktop 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.

Remove the local CloudBees Unify MCP Server

Once you confirm the remote server works, clean up the local server to avoid routing conflicts.

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

  2. Remove any environment variables, launchd units, or systemd units that started the local server.

  3. Delete any legacy API tokens from the CloudBees Unify UI to reduce the token footprint if they were only used for MCP access.

Communicate the change to your team

If your team shares MCP configurations, update shared sources so new machines start with the remote configuration.

  1. Update any internal setup scripts or dotfiles repos to use the remote configuration.

  2. Add a note in your team wiki that the local server is no longer supported.

Troubleshooting

The following table covers common issues encountered during migration.

Symptom Likely root cause Solution

"Server not reachable"

Network or TLS issue

Run curl https://mcp.cloudbees.io/v1/mcp from the same machine. Check corporate proxy settings.

"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 CloudBees 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 Troubleshoot CloudBees Unify MCP Server issues or contact CloudBees Support.

Connect Gemini
Secure your MCP connection