Cloudaware MCP - Configuration

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 (with BigQuery Data Viewer and BigQuery Job User roles assigned)

• 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.)

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

Local HTTP Server

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

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

AI Processing Flow

A typical AI agent connected to MCP follows this sequence:

1. Discover schema (search_types → search_fields → get_relationship_graph).

2. Plan queries. Understand joins, fields, and object structure.

3. Generate SQL. Build correct queries using discovered metadata.

4. Execute SQL. Run via execute_query with results streamed back to the AI tool.

5. Interpret results. Produce summaries, resource lists, or code.

Supported AI Tools and Integrations

The Cloudaware MCP Server can be connected to any AI tool that supports MCP over either stdio or HTTP transport

Claude Code (stdio mode)

Add Cloudaware MCP by running the following command:

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:

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:

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:

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

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

{
  "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:

{
  "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:

/mcp auth cloudaware-mcp

LM Studio

Run MCP locally using stdio or HTTP transport:

repo-manager mcp cloudaware --port 8888

This starts the server on port 8888.

Edit mcp.json and add:

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

LibreChat

Add the following configuration to librechat.yaml:

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

ChatGPT

You can create an app that uses Cloudaware MCP, available with a Plus subscription.

• Enable Developer Mode: Go to Settings → Apps → Advanced Settings → Developer Mode.

• Create an Application: Click Create App next to Advanced Settings.

Use the following settings:

• Name: cloudaware-mcp

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

• Authentication: OAuth

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