Troubleshooting

GUI Apps Don't Inherit Shell Environment (macOS)

Problem: MCP servers fail to start in Windsurf, Claude Desktop, or other GUI apps with errors like:

• kubectl not found in PATH
• invalid peer certificate: UnknownIssuer (TLS/proxy issues)
• Package installation failures from corporate PyPI mirrors

Cause: macOS GUI applications launch from launchd with a minimal environment, not from your shell. They don't inherit PATH or other environment variables from ~/.zshrc or ~/.bashrc.

Solution: Add the env block to your MCP configuration:

{
  "mcpServers": {
    "unblu": {
      "command": "unblu-mcp",
      "args": ["--provider", "k8s", "--environment", "dev"],
      "env": {
        "PATH": "/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin"
      }
    }
  }
}

Add any directories containing tools your setup needs (e.g., kubectl, docker) to the PATH.

uvx Blocks uv Cache Cleaning

Problem: If you're using uvx unblu-mcp instead of the recommended uv tool install, tools like topgrade or uv cache prune will hang with:

Cache is currently in-use, waiting for other uv processes to finish

Cause: This is a known uv limitation affecting all long-running uvx processes.

Solution: Follow the recommended installation method using uv tool install unblu-mcp.

Corporate Proxy/PyPI Mirror Issues

Problem: When installing with uv tool install, you get TLS certificate errors or timeouts connecting to corporate PyPI mirrors.

Solution: Use --no-config to bypass uv.toml settings and --native-tls to use system certificates:

uv tool install --no-config --native-tls unblu-mcp

Finding MCP Server Logs

Different clients store logs in different locations:

Client	Log Location
Windsurf	Check Output panel → select "MCP" or "Windsurf"
Claude Desktop	~/Library/Logs/Claude/ (macOS)
Warp	~/Library/Group Containers/2BBY89MBSN.dev.warp/Library/Application Support/dev.warp.Warp-Stable/mcp/*.log

The unblu-mcp server also writes its own logs to ~/.unblu-mcp/logs/. See Logging & Observability for details.

Testing the Server Locally

To debug without an MCP client, use the included test script:

# Test with K8s provider
uv run scripts/test_client.py --provider k8s --environment dev

# Test with default provider (requires UNBLU_BASE_URL)
UNBLU_BASE_URL=https://your-instance.unblu.cloud/app/rest/v4 \
UNBLU_API_KEY=your-key \
uv run scripts/test_client.py

Common Error Messages

ConfigurationError: kubectl not found in PATH

kubectl is not installed or not in the PATH visible to the MCP client.

Solution: Install kubectl and add its directory to the env.PATH in your MCP config.

ConfigurationError: kubectl is not authenticated

Your kubectl context is not authenticated to the cluster.

Solution: Authenticate to your cluster using your provider's authentication method (e.g., gcloud auth login, aws eks update-kubeconfig, az aks get-credentials) or configure your kubeconfig.

ConfigurationError: Port-forward timed out

The port-forward process started but the port never became available.

Possible causes:

1. The service doesn't exist in the namespace
2. Network connectivity issues
3. The service is not responding

Debug:

# Check if service exists
kubectl get svc -n your-namespace

# Try manual port-forward to see errors
kubectl port-forward -n your-namespace svc/your-service 8084:8080

ToolError: Operation 'xyz' not found

The operation ID doesn't exist in the OpenAPI spec.

Solution: Use search_operations("keyword") to find valid operation IDs.

Feedback