Cloudaware MCP - Configuration

This guide explains how to configure and connect Cloudaware MCP server to supported AI tools.

How MCP Server Works

Cloudaware MCP Server acts as a proxy between AI tools and Cloudaware datasets stored in Google BigQuery. The Export Project and SObjects dataset serve as authoritative data sources.

Data Sources

Export Project – customer BigQuery export containing resource, configuration, cost, and usage tables
SObjects Dataset – metadata describing CMDB object types, fields, labels, and relationships

All access is governed by existing BigQuery IAM permissions.

Interface: JSON-RPC Tools

The MCP server exposes a set of tools via JSON-RPC interface for metadata discovery and data querying. These tools are designed to be used in a step-by-step manner:

Metadata Discovery

Used by AI agents to understand CMDB schemas before querying data:

search_types: search for object types by keywords to identify API names and table IDs
search_fields: retrieve field metadata for a specific type, including labels, types, and descriptions
get_relationship_graph: get a graph of relationships and join paths between objects
analyze_field: get extensive data about the values stored in the specific field

AI agents should follow a discovery-first approach, identifying types and fields before executing queries. Detailed tool specifications are available in the API reference.

SQL Execution

Used for custom reporting, inventory analysis, relationship exploration, and dependency mapping:

execute_query: run custom BigQuery SQL queries on your dataset

Requirements

To use MCP in your environment, ensure to have:

A Cloudaware Export Project in Google BigQuery
An SObjects dataset configured for your CMDB metadata
Valid Google Cloud credentials with access to the project and dataset
An AI tool that supports MCP/JSON-RPC over stdio or HTTP (e.g., Claude Code, Gemini CLI, LM Studio, etc.)

To verify whether an Export Project is already configured, contact support@cloudaware.com or your Technical Account Manager.

Transport Modes

Local Mode (stdio)

This mode is best for engineers using IDEs or CLI-based AI assistants.

MCP is launched via: repo-manager mcp cloudaware
Uses repo-manager auth to automatically detect Export Project + SObjects dataset.
Uses gcloud authentication for BigQuery access.
Works with AI tools that support stdio (Claude Code, Gemini CLI, LM Studio with plugins).

Both repo-manager and gcloud authentication must be configured.

Local HTTP Server

This mode is for running MCP as a local HTTP server:

CODE

repo-manager mcp cloudaware --port 8888

This starts MCP at http://localhost:8888/mcp for tools requiring HTTP access.

Remote HTTP Mode (OAuth 2.0)

This mode is used for cloud-hosted AI tools (Claude.ai, Gemini, LibreChat).

Server URL: https://inbound.prod.cloudaware.com/mcp
Required Headers:
- X-CA-ExportProject – your Export Project ID
- X-CA-SObjectsDataset – your SObjects dataset name
Authentication: Google OAuth 2.0

Only users with BigQuery access to the specified datasets can retrieve data.

AI Processing Flow

A typical AI agent connected to MCP follows this sequence:

Discover schema (search_types → search_fields → get_relationship_graph).
Plan queries. Understand joins, fields, and object structure.
Generate SQL. Build correct queries using discovered metadata.
Execute SQL. Run via execute_query with results streamed back to the AI tool.
Interpret results. Produce summaries, resource lists, or code.

Supported AI Tools and Integrations

Cloudaware MCP integrates with multiple AI environments using either stdio transport or HTTP transport.

Claude Code (stdio mode)

Add Cloudaware MCP by running the following command:

CODE

claude mcp add --transport stdio cloudaware-mcp -- java -jar ~/.ca/repo-manager.jar mcp cloudaware

This assumes repo-manager is installed at ~/.ca/repo-manager.jar. If it is installed elsewhere, update the path to your repo-manager.jar file accordingly.

After adding the MCP server, start Claude Code and use the /mcp command to authenticate.

Claude Code (HTTP mode with OAuth)

Add Cloudaware MCP by running the following command:

CODE

claude mcp add --transport http cloudaware-mcp "https://inbound.prod.cloudaware.com/mcp?exportProject=your-export-project-id&sObjectsDataset=your-sobjects-dataset-name"

Replace your-export-project-id and your-sobjects-dataset-name with your actual values.

After adding the MCP server, start Claude Code and use the /mcp command to authenticate.

Claude.ai

Add Cloudaware MCP via Settings → Connectors → Add custom connector, using the following configuration:

Name: cloudaware-mcp
URL:

CODE

https://inbound.prod.cloudaware.com/mcp?exportProject=your-export-project-id&sObjectsDataset=your-sobjects-dataset-name

Advanced Settings → OAuth Client ID: leave blank
Advanced Settings → OAuth Client Secret: leave blank

Replace the placeholder values with your actual Export Project ID and SObjects dataset name.

Gemini CLI (stdio mode)

Add the following configuration to ~/.gemini/settings.json:

CODE

{
  "mcpServers": {
    "cloudaware-mcp": {
      "command": "repo-manager",
      "args": ["mcp", "cloudaware"]
    }
  }
}

If you have not created an alias for repo-manager, use:

CODE

{
  "mcpServers": {
    "cloudaware-mcp": {
      "command": "java",
      "args": ["-jar", "path/to/your/repo-manager.jar", "mcp", "cloudaware"]
    }
  }
}

Gemini CLI (HTTP mode)

Add the following to ~/.gemini/settings.json:

CODE

{
  "mcpServers": {
    "cloudaware-mcp": {
      "httpUrl": "https://inbound.prod.cloudaware.com/mcp",
      "headers": {
        "X-CA-ExportProject": "your-export-project-id",
        "X-CA-SObjectsDataset": "your-sobjects-dataset-name"
      }
    }
  }
}

Start Gemini CLI and authenticate using:

CODE

/mcp auth cloudaware-mcp

LM Studio

Run MCP locally using stdio or HTTP transport:

CODE

repo-manager mcp cloudaware --port 8888

This starts the server on port 8888.

Edit mcp.json and add:

CODE

{
  "mcpServers": {
    "cloudaware-mcp": {
      "url": "http://localhost:8888/mcp"
    }
  }
}

LibreChat

Add the following configuration to librechat.yaml:

CODE

mcpServers:
  cloudaware-mcp:
    type: streamable-http
    url: https://inbound.prod.cloudaware.com/mcp?exportProject=your-export-project-id&sObjectsDataset=your-sobjects-dataset-name
    timeout: 30000
    serverInstructions: true