Troubleshoot common issues with the CloudBees Unify MCP Server

This guide helps you diagnose and resolve common issues with the CloudBees Unify MCP Server.

Connection issues

Use the following to resolve network and connectivity issues.

Server not reachable

Symptom: Your AI client reports "server not reachable", "cannot connect", or times out when trying to connect.

Likely causes:

Network connectivity issue.
Corporate firewall or proxy blocking the connection.
TLS/SSL certificate validation failure.

Solutions:

Test basic connectivity:
```
curl https://mcp.cloudbees.io/v1/mcp▼
```
If this fails, the problem is network-related, not MCP-specific.
Check corporate proxy settings:
- Verify that mcp.cloudbees.io is allowed through your corporate proxy.
- Configure proxy environment variables if needed:
  export HTTPS_PROXY=http://proxy.example.com:8080 export HTTP_PROXY=http://proxy.example.com:8080
  ▼
Verify DNS resolution:
```
nslookup mcp.cloudbees.io▼
```
Check firewall rules:
- Ensure outbound HTTPS (port 443) to mcp.cloudbees.io is allowed.
- No inbound firewall rules are required.

Test TLS certificate validation:

openssl s_client -connect mcp.cloudbees.io:443 -servername mcp.cloudbees.io▼

If problems persist, contact your network administrator or CloudBees Support.

Browser doesn’t open during authentication

Symptom: When you try to authenticate, the OAuth browser window doesn’t open.

Likely causes:

Browser permissions not granted to your AI client.
Default browser not set correctly.
Pop-up blocker preventing the window.

Solutions:

Grant browser permissions:
- macOS: System Settings → Privacy & Security → Automation → Grant permission to your AI client.
- Windows: Check that your AI client is allowed to launch applications.
Verify default browser:
- Ensure you have a default browser set.
- The OAuth flow uses your system’s default browser.
Disable pop-up blockers temporarily:
- Some browser extensions may block OAuth windows.
- Try disabling pop-up blockers and retry authentication.
Try manual authentication:
- Some AI clients provide a manual authentication option.
- Copy the OAuth URL and paste it into your browser manually.

Timeout during authentication

Symptom: The OAuth browser window opens but times out before you can complete sign-in.

Solutions:

Complete authentication promptly:
- The OAuth flow has a time limit.
- Ensure you’re ready to sign in before starting the process.
Check for browser extensions interfering:
- Password managers may slow down the sign-in process.
- Try using an incognito/private browsing window.
Clear browser cookies and cache:
- Stale authentication cookies may cause issues.
- Clear cookies for cloudbees.io and retry.

Authentication issues

Use the following to resolve authentication and authorization issues.

"Unauthorized" or "Authentication failed"

Symptom: Every tool call returns "unauthorized", "authentication failed", or "invalid token" errors.

Likely causes:

Authentication expired.
Authentication never completed successfully.
Organization access was revoked after authentication.
User account lacks necessary permissions.

Solutions:

Reauthenticate:
- Disconnect from the CloudBees Unify MCP Server in your AI client.
- Reconnect to trigger a new OAuth flow.
- Carefully select the correct organization (you only see organizations you have access to).
Verify you completed the OAuth flow:
- The browser should show "Authentication successful".
- If it showed an error instead, note the error and try again.
Check your Unify account status:
- Sign in to CloudBees Unify directly at https://cloudbees.io.
- Verify your account is active and has access to the organization.
Review your roles:
- In CloudBees Unify, check your user profile to see assigned roles.
- Contact your admin if you lack necessary permissions.

Cannot see expected data after authentication

Symptom: You authenticated successfully but can’t see your expected components, workflows, or data.

Causes:

You selected a different organization than intended during the OAuth flow.
Your access to the organization was revoked by an administrator after you authenticated.

Solution:

Disconnect from the CloudBees Unify MCP Server in your AI client.
Reconnect to trigger a new OAuth flow.
At the organization selection screen, carefully choose the correct organization.
Complete authentication.

You only see organizations you have access to.

Authentication expired

Symptom: MCP worked previously but now returns authentication errors.

Cause: Your authentication has a limited lifetime and expires after a period of inactivity.

Solution:

Reauthenticate your AI client:

The AI client will typically prompt you when authentication expires.
Follow the OAuth flow again to reauthenticate.
You’ll need to select your organization again.

This is normal behavior and should happen infrequently.

Tool and data issues

Use the following to resolve tool access and data retrieval issues.

Tool calls return permission errors

Symptom: Tool calls fail with "access denied" or "permission denied" errors.

Cause:

Your Unify role lacks permissions to access the specific resource (component, workflow, etc.). All tools are visible regardless of role, but RBAC is enforced at the resource level.

Solutions:

Verify your organization:

Ask your AI agent:

Who am I in CloudBees Unify?

Confirm the organization name matches your expectation.
Check your roles:
- Sign in to CloudBees Unify.
- Go to your user profile.
- Review assigned roles for the organization.
Request additional permissions:
- Contact your CloudBees admin.
- Specify which resources or capabilities you need access to.
- The admin can grant additional roles to your account.
Verify team membership:
- All tools are visible, but they can only access resources you have permission to use.
- Ensure you’re a member of teams that own the components or workflows you need to access.

Tool calls return "not found" or "access denied"

Symptom: A specific tool call fails with "not found", "access denied", or "permission denied".

Causes:

You don’t have permission to access the specific resource (component, workflow, etc.).
The resource ID or name is incorrect.
The resource was deleted.

Solutions:

Verify the resource exists:
- Sign in to CloudBees Unify.
- Check that the component, workflow, or other resource exists.
- Confirm the name or ID matches what you’re requesting.
Check resource-level permissions:
- Some resources have specific access controls.
- Verify you have permission to access the specific resource.
Try listing all resources:

Ask your AI agent to list all components or workflows to see what you have access to.

"No default team found" when listing users

Symptom: When attempting to list users, the tool returns "no default team found" or asks you to specify a team name.

Cause: Some organizations may not have a default "all users team" configured.

Solutions:

Specify the team name explicitly:

Ask your AI agent: "List users from the [team-name] team".
List available teams first:

Ask your AI agent: "What teams are available in my organization?"
Contact your admin:

Ask your CloudBees Unify administrator which teams exist and whether a default team should be configured.

Data looks stale or outdated

Symptom: Tool calls succeed but return data that appears outdated.

Causes:

Caching in the Unify backend.
Recent changes haven’t propagated yet.
Looking at archived or historical data.

Solutions:

Wait briefly and retry:
- Unify data updates asynchronously after events.
- Retry after 1–2 minutes.
Verify you’re looking at current data:
- Ask for the most recent build, workflow run, etc.
- Be specific about time ranges if querying historical data.
Refresh the source in Unify:
- Open the resource in the Unify UI.
- Force a refresh if the UI has a refresh button.

Slow responses

Symptom: Tool calls work but responses are slower than expected.

Cause: First connection or cache warming.

Solution:

The first tool call after connecting may take a few seconds while the connection initializes. Subsequent calls should be faster.

If all calls remain consistently slow, check your network connection or refer to the rate limiting section below.

Rate limit errors

Symptom: Tool calls fail with "rate limit exceeded" or "too many requests".

Cause: Too many concurrent tool calls from one user.

Solutions:

Reduce request rate:
- Ask simpler questions that require fewer tool calls.
- Avoid rapid-fire questions in quick succession.
Wait and retry:
- Rate limits typically reset after a short period (seconds to minutes).
- Wait a minute and try again.
Split complex questions:
- Instead of "analyze all my workflows", ask about specific workflows one at a time.
If issues persist:
- Contact CloudBees Support.
- Rate limits may need adjustment for your use case.

AI client-specific issues

Use the following to resolve configuration and client-specific issues.

Claude Code: Configuration not loading

Symptom: Claude Code doesn’t recognize the CloudBees Unify MCP Server you added to the config file.

Solutions:

Verify JSON syntax:
```
cat ~/.claude.json | python3 -m json.tool▼
```
This checks for JSON formatting errors.
Verify file location:
- macOS/Linux: ~/.claude.json
- Windows: %USERPROFILE%\.claude.json
Restart Claude Code completely:
- Close all Claude Code windows.
- Quit the application.
- Restart Claude Code.
Check Claude Code logs:
- Look for MCP-related error messages.
- Logs location varies by platform.

Claude Code: MCP panel shows "disconnected"

Symptom: The CloudBees Unify MCP Server appears in the list but shows as disconnected.

Solutions:

Select "Connect" or "Authenticate" in the MCP panel.
If that fails, remove and re-add the server configuration.
Check for authentication errors in Claude Code’s console.

Gemini: Server not appearing in extensions

Symptom: You added the CloudBees Unify MCP Server but it doesn’t appear in Gemini’s extensions or MCP list.

Solutions:

Verify you’re using a version of Gemini with MCP support.
Refresh Gemini settings.
Try removing and re-adding the server.
Check Gemini’s documentation for MCP configuration requirements.

Diagnostic information for support

If you need to contact CloudBees Support, gather this information:

AI client name and version: Claude Code 1.x, Gemini, etc.
Operating system: macOS 13.x, Windows 11, Ubuntu 22.04, etc.
Error messages: Exact error text from your AI client.
Network configuration: Corporate proxy, firewall rules, etc.
Timeline: When did the problem start? Did it ever work?
Reproduction steps: Exact steps to reproduce the issue.

Include your MCP configuration (with any sensitive tokens removed):

{
  "mcpServers": {
    "unify-mcp-server": {
      "type": "http",
      "url": "https://mcp.cloudbees.io/v1/mcp",
      "oauth": {
        "clientId": "public-mcp-client"
      }
    }
  }
}▼

Getting help

Use these resources for additional help and information.

Refer to Connect AI agents to CloudBees Unify for architecture and concepts.
Review Secure your MCP connection for authentication issues.
Refer to Privacy and data handling for data-related questions.
Contact CloudBees Support for persistent issues.