Quickstart for the CloudBees Unify MCP Server

This tutorial walks you through connecting your AI client to the CloudBees Unify MCP Server and running your first conversational commands.

By the end of this tutorial, you’ll be able to query CloudBees Unify directly from your AI client using natural language.

Approximate time to complete: 15 minutes.

Before you begin

Complete the following prerequisites before you begin:

An active CloudBees Unify account.
An MCP-compatible AI client installed (Claude Code, Claude Desktop, or Gemini).
Access to at least one component or workflow in CloudBees Unify.

Step 1: Configure your AI client

The exact configuration depends on which AI client you’re using.

Follow the configuration guide for your client, then return here to continue the tutorial.

Step 2: Authenticate with CloudBees Unify

When you first connect to the CloudBees Unify MCP Server, you need to sign in:

Your AI client opens a browser window.
The sign-in page for CloudBees Unify displays.
Sign in using Google, GitHub, or your SSO provider.
Select your Root Organization from the list. You only see organizations you have access to.
The browser displays "Authentication successful" and closes.
Your AI client confirms the connection.

You only need to authenticate once. Your AI client stores your credentials securely for future tool calls.

If you’re already signed in to CloudBees Unify in your browser, authentication may complete automatically.

Step 3: Verify the connection

In this step, run a test to ensure your AI client can reach CloudBees Unify.

In your AI client, enter:

Who am I in CloudBees Unify?

The agent should call the user_whoami tool and return your user information:

Example 1. Response

You are Sam Admin (sam.admin@example.com) in the Acme Corporation organization.

If you encounter an error message instead, refer to Troubleshooting.

Step 4: List available tools

Ask your AI agent to show what CloudBees Unify capabilities are available:

What CloudBees Unify tools do you have access to?

The agent should list the available tools organized by category:

Component management
Workflow operations
Build status and logs
Security findings
Feature flags
CI controller status
User and team management

You can also view tools in your AI client’s CloudBees Unify MCP Server settings or tool list interface.

Step 5: Try common operations

Now that you’re connected, try some common use cases.

List your components

List all CloudBees Unify components I have access to.

The agent calls the appropriate tool and returns a list of components with their names, IDs, and status.

Check build status

What’s the status of my latest build for the payment-service component?

The agent:

Finds the payment-service component.
Retrieves recent builds.
Identifies the most recent one.
Reports its status (success, failure, in progress).

View build logs

If a build failed, you can investigate immediately:

Show me the logs for build #42.

The agent fetches and displays the build logs, making it easy to diagnose issues without leaving your IDE.

Manage workflows

List all workflows for the api-gateway component.

The agent returns workflow names, trigger conditions, and current status.

Check security findings

What security vulnerabilities were found in my last build?

The agent queries security findings and summarizes any issues discovered during the build process.

Step 6: Understand tool behavior

When you ask a question in natural language:

The AI agent determines what information it needs.
It calls CloudBees Unify tools with appropriate parameters.
Results return to the AI agent.
The agent composes a natural language answer.

You don’t need to know the exact tool names or parameters, just ask in plain English.

For complex questions, the agent may call multiple tools in sequence to gather all needed information.

Step 7: Explore further

Now that you’ve completed the basics, explore more advanced capabilities:

Configure feature flags for different environments.
Trigger workflows conversationally.
Investigate CI controller reports.
Query team membership and permissions.

Refer to Tool reference for the complete list of available operations.

What’s next

Continue learning about the CloudBees Unify MCP Server with these related topics.

Troubleshooting

If you encounter issues during setup, refer to Troubleshooting.