MCP Server Configuration

Use this guide to configure MCP Server (AI) settings and connection parameters.

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.

note

You can use your own Google BigQuery project or a Cloudaware-managed BigQuery project for the export.

If you use your own project, provide the project name to your dedicated Technical Account Manager at tam@cloudaware.com for export setup.
If you use a Cloudaware-managed project, contact your dedicated Technical Account Manager at tam@cloudaware.com to get the project name required for setup.

Interface: JSON-RPC Tools

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

Metadata Discovery

AI agents use metadata discovery tools to understand CMDB schemas before querying data:

Tool	Description
`search_types`	Searches for object types by keywords to identify API names and table IDs.
`search_fields`	Retrieves field metadata for a specific type, including labels, types, and descriptions.
`get_relationship_graph`	Gets a graph of relationships and join paths between objects.
`analyze_field`	Gets extensive data about the values stored in a specific field.

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

SQL Execution

AI agents use SQL execution for custom reporting, inventory analysis, relationship exploration, and dependency mapping:

Tool	Description
`execute_query`	Runs custom BigQuery SQL queries on your dataset.

Requirements

To use MCP in your environment, ensure that you have:

A Cloudaware Export Project in Google BigQuery, with the 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 or JSON-RPC over stdio or HTTP, such as Claude Code, Gemini CLI, or LM Studio.

tip

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

Transport Modes

Local Mode (stdio)

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

Launch MCP with:

repo-manager mcp cloudaware

Local mode:

Uses repo-manager auth to automatically detect the Export Project and SObjects dataset.
Uses gcloud authentication for BigQuery access.
Works with AI tools that support stdio, including Claude Code, Gemini CLI, and LM Studio with plugins.

note

Both repo-manager and gcloud authentication must be configured.

Local HTTP Server

Use local HTTP mode to run 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)

Remote HTTP mode is used for cloud-hosted AI tools such as Claude.ai, Gemini, and LibreChat.

Server URL: https://inbound.prod.cloudaware.com/mcp
Authentication: Google OAuth 2.0

Required headers:

Header	Description
`X-CA-ExportProject`	Your Export Project ID.
`X-CA-SObjectsDataset`	Your SObjects dataset name.

note

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. Use search_types, search_fields, and get_relationship_graph.
Plan queries. Understand joins, fields, and object structure.
Generate SQL. Build correct queries using discovered metadata.
Execute SQL. Run queries through 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 Server can be connected to any AI tool that supports MCP over either stdio or HTTP transport.

note

The exportProject and sObjectsDataset values used in the configuration URL depend on how the BigQuery export is configured:

If you use your own Google BigQuery project, contact your dedicated technical manager at tam@cloudaware.com to provide the project name and request export setup.
If you use a Cloudaware-managed BigQuery project, contact your dedicated technical manager at tam@cloudaware.com to obtain the required exportProject and sObjectsDataset values. Typical values are cloudaware-{yourcompanyname} and sobjects.

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 actual values.

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

Claude.ai

Add Cloudaware MCP through Settings > Connectors > Add custom connector using the following configuration:

Field	Value
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 your-export-project-id and your-sobjects-dataset-name with actual values.

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 configuration 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"
      }
    }
  }
}

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

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

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

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.
Configure the application. Use the following settings:

Field	Value
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 actual values.

How MCP Server Works​

Data Sources​

Interface: JSON-RPC Tools​

Metadata Discovery​

SQL Execution​

Requirements​

Transport Modes​

Local Mode (stdio)​

Local HTTP Server​

Remote HTTP Mode (OAuth 2.0)​

AI Processing Flow​

Supported AI Tools and Integrations​

Claude Code (stdio Mode)​

Claude Code (HTTP Mode with OAuth)​

Claude.ai​

Gemini CLI (stdio Mode)​

Gemini CLI (HTTP Mode)​

LM Studio​

LibreChat​

ChatGPT​

How MCP Server Works

Data Sources

Interface: JSON-RPC Tools

Metadata Discovery

SQL Execution

Requirements

Transport Modes

Local Mode (stdio)

Local HTTP Server

Remote HTTP Mode (OAuth 2.0)

AI Processing Flow

Supported AI Tools and Integrations

Claude Code (stdio Mode)

Claude Code (HTTP Mode with OAuth)

Claude.ai

Gemini CLI (stdio Mode)

Gemini CLI (HTTP Mode)

LM Studio

LibreChat

ChatGPT