Cloudaware MCP Server Configuration

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.

You can connect to the Cloudaware remote server over HTTP, or run the server locally through repo-manager. Most teams use the remote server: it requires no installation and works with both web-based and desktop AI tools. This guide covers both options, including the connection parameters and authentication methods each one requires.

Choose a Connection Method

Connection	Server location	Transport	Authentication	Use when
Cloudaware remote	`https://inbound.prod.cloudaware.com/mcp`	Streamable HTTP	Browser sign-in (Cloudaware Launcher or Google OAuth 2.0) or Cloudaware API key	You use a web or cloud-hosted AI tool (Claude.ai, ChatGPT, n8n.cloud, LibreChat), or you do not want to install anything locally.
Local — stdio	Your machine	stdio	`repo-manager` + `gcloud` profiles	You use an IDE or a CLI-based AI assistant and already have `repo-manager` installed.
Local — Streamable HTTP	Your machine (`http://localhost:8888/mcp`)	Streamable HTTP	`repo-manager` + `gcloud` profiles	Your AI tool requires an HTTP endpoint but you want the server to stay on your machine.

note

Remote connections require you to pass the Export Project and SObjects Dataset explicitly. Local connections resolve them automatically. See Connection Parameters.

Prerequisites

Export Project and SObjects Dataset

The MCP server requires two parameters to operate:

Parameter	Description
Export Project	The GCP project ID where your Cloudaware BigQuery Export lives.
SObjects Dataset	The BigQuery dataset name, within the Export Project, that holds your CMDB metadata: object types, fields, labels, and relationships.

tip

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.

Required Permissions

Ensure that the identity used by the server — the account you sign in with, or the identity behind your API key — has:

Access to the Cloudaware Export Project in Google BigQuery, with the BigQuery Data Viewer and BigQuery Job User roles assigned.
Access to the SObjects Dataset configured for your CMDB metadata.

For local runs, you also need:

Valid Google Cloud credentials (gcloud) with access to the project and dataset.
A configured repo-manager authentication profile.

MCP does not introduce additional privileges: if an identity cannot read a dataset in BigQuery, MCP will not expose it to AI tools.

Connection Parameters

Parameter	Cloudaware remote	Local (stdio / HTTP)
Server URL	`https://inbound.prod.cloudaware.com/mcp`	`http://localhost:8888/mcp` (HTTP mode only)
Export Project ID	`exportProject` query parameter or `X-CA-ExportProject` header	Resolved automatically by `repo-manager`
SObjects Dataset name	`sObjectsDataset` query parameter or `X-CA-SObjectsDataset` header	Resolved automatically by `repo-manager`
Authentication	Browser sign-in or API key	`repo-manager auth` + `gcloud`

Tools

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

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: start with type and field searches before querying data. Detailed tool descriptions, inputs, and outputs are available in the API reference, accessible via the server's endpoint.

Connect to the Cloudaware Remote MCP Server

The remote server is available at https://inbound.prod.cloudaware.com/mcp and uses Streamable HTTP transport. Unlike the local server, it requires you to pass the Export Project and SObjects Dataset explicitly.

Parameter	Query parameter	HTTP header
Export Project ID	`exportProject`	`X-CA-ExportProject`
SObjects Dataset name	`sObjectsDataset`	`X-CA-SObjectsDataset`

Use whichever form your AI tool supports. A fully specified endpoint URL looks like this:

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 in all examples below.

Authentication

The remote server supports two categories of authentication: interactive browser sign-in and API keys.

Method	How it works	Use when
Cloudaware Launcher	Chosen on the Cloudaware sign-in page during the browser flow.	You sign in to Cloudaware with Cloudaware Launcher.
Google OAuth 2.0	Chosen on the Cloudaware sign-in page during the browser flow. Requests run under the permissions of the authenticated Google user.	Your AI tool supports interactive OAuth (Claude Code, Claude.ai, Antigravity CLI, ChatGPT, n8n.cloud).
Cloudaware API key	A long-lived key is sent with every request.	Your AI tool does not support interactive sign-in, or you need unattended or automated access.

Browser sign-in applies to the remote server only. A locally run server authenticates through your repo-manager and gcloud profiles instead, with no sign-in page involved.

When you click Connect (or run the equivalent authentication command) in your AI tool, you are redirected to the Cloudaware sign-in page, where you choose how to authenticate. No extra client configuration is needed for either option — the choice is made on the page.

Cloudaware Launcher. If your organization signs in to Cloudaware with Cloudaware Launcher, select this option and authenticate as usual. It works out of the box.
Google OAuth 2.0. Sign in with the Google account that has access to your Export Project and SObjects Dataset.

note

If your organization uses its own SSO to sign in to Cloudaware and you do not have a Google account available for authentication, you can still authenticate to the MCP server using either Cloudaware Launcher or a Cloudaware API key. Using Cloudaware Launcher in this case requires additional configuration. Contact your dedicated Technical Account Manager at tam@cloudaware.com for assistance.

Create an API Key

In Cloudaware, go to Admin → API CREDENTIALS → API Keys.
Click + CREATE API KEY. Create a new API key.
Copy the key value and store it securely. Treat it like a password: anyone holding it can query your CMDB data with the key's permissions.

Use an API Key

Pass the API key in one of three ways, depending on what your AI tool supports:

Method	Format	Notes
Tool-native field	—	If a tool supports API key authentication, paste the key into the field the tool provides.
`Authorization` header	`Authorization: Bearer <api-key>`	Standard bearer token. Preferred when the tool allows custom headers.
`X-CA-ApiKey` header	`X-CA-ApiKey: <api-key>`	Use when the tool reserves the `Authorization` header for its own purposes.
URL query parameter*	`?apiKey=<api-key>`	Use when the tool accepts only a URL. Combine with the other query parameters using `&`.

A URL with all parameters, including the key:

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

warning

*API keys embedded in a URL may be written to browser history, proxy logs, and tool configuration files. Prefer header-based authentication whenever your tool supports custom headers.

Claude Code

With browser sign-in:

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

After adding the MCP server, start Claude Code and use the /mcp command to authenticate. You are redirected to the Cloudaware sign-in page, where you choose Cloudaware Launcher or Google OAuth 2.0.

With an API key:

claude mcp add --transport http cloudaware-mcp "https://inbound.prod.cloudaware.com/mcp" \
  --header "Authorization: Bearer your-api-key" \
  --header "X-CA-ExportProject: your-export-project-id" \
  --header "X-CA-SObjectsDataset: your-sobjects-dataset-name"

No /mcp authentication step is needed when using an API key.

Claude.ai

Pro and Max Plan

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.

Then click Connect. You are redirected to the Cloudaware sign-in page, where you choose Cloudaware Launcher or Google OAuth 2.0.

To use an API key instead of browser sign-in, append &apiKey=your-api-key to the URL.

Team and Enterprise Plan

An Owner or Primary Owner must first add Cloudaware MCP to the organization:

Go to Organization settings → Connectors.
Click Add.
Select Custom → Web.
Enter the Cloudaware MCP URL.
Leave OAuth Client ID and OAuth Client Secret blank.
Click Add.

After the connector is available in the organization, each user must:

Go to Settings → Customize → Connectors.
Find cloudaware-mcp.
Click Connect and complete authentication on the Cloudaware sign-in page, choosing Cloudaware Launcher or Google OAuth 2.0.

Antigravity CLI

Add the following configuration to ~/.gemini/config/mcp_config.json (global) or .agents/mcp_config.json (workspace). Remote servers use the serverUrl key.

With browser sign-in:

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

Cloudaware MCP Server supports dynamic client registration, so no OAuth client ID or secret is needed. To authenticate, open Agent Settings with Cmd+, (macOS) or Ctrl+, (Windows and Linux), go to Customizations, and click Authenticate next to cloudaware-mcp. You are redirected to the Cloudaware sign-in page, where you choose Cloudaware Launcher or Google OAuth 2.0.

Tokens are stored and refreshed automatically in ~/.gemini/antigravity/mcp_oauth_tokens.json.

With an API key:

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

No Authenticate step is needed when using an API key.

Gemini CLI (legacy)

Gemini CLI reached end of life on June 18, 2026 for free, Pro, and Ultra tiers and for individual Gemini Code Assist subscribers. It remains available to Gemini Code Assist Standard and Enterprise licensees and to paid API key users.

If you still use it, the configuration goes in ~/.gemini/settings.json and the remote server key is httpUrl rather than serverUrl:

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

Authenticate with /mcp auth cloudaware-mcp. For API key authentication, add the Authorization header as shown above.

LibreChat

Add the following configuration to librechat.yaml.

With an API key in headers:

mcpServers:
  cloudaware-mcp:
    type: streamable-http
    url: https://inbound.prod.cloudaware.com/mcp
    headers:
      Authorization: "Bearer your-api-key"
      X-CA-ExportProject: "your-export-project-id"
      X-CA-SObjectsDataset: "your-sobjects-dataset-name"
    timeout: 30000
    serverInstructions: true

With all parameters in the URL:

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

n8n.cloud

You can connect to Cloudaware MCP Server using the MCP Client node directly, or via the Tools section of the AI Agent node.

With browser sign-in. To set up credentials, go to Personal → Credentials in your n8n dashboard. Click Create Credentials → MCP OAuth2 API. Use the following parameters:

Parameter	Value
Use dynamic client registration	Leave turned on.
Server URL	`https://inbound.prod.cloudaware.com/mcp`

Then use the following parameters in the MCP Client node settings:

Parameter	Value
Server Transport	`HTTP Streamable`
MCP Endpoint URL	`https://inbound.prod.cloudaware.com/mcp?exportProject=your-export-project-id&sObjectsDataset=your-sobjects-dataset-name`
Authentication	`MCP OAuth2`
Credential for MCP OAuth2 API	Credential created in the previous step.

When you connect the credential, you are redirected to the Cloudaware sign-in page, where you choose Cloudaware Launcher or Google OAuth 2.0.

With an API key. Create a Header Auth credential with the name Authorization and the value Bearer your-api-key, then use the following parameters in the MCP Client node settings:

Parameter	Value
Server Transport	`HTTP Streamable`
MCP Endpoint URL	`https://inbound.prod.cloudaware.com/mcp?exportProject=your-export-project-id&sObjectsDataset=your-sobjects-dataset-name`
Authentication	`Header Auth`
Credential for Header Auth	Credential created in the previous step.

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`

On first use you are redirected to the Cloudaware sign-in page, where you choose Cloudaware Launcher or Google OAuth 2.0.

To use an API key instead, set Authentication to API key (or Custom headers, depending on the ChatGPT version) and provide the key as Authorization: Bearer your-api-key.

Connect to a Local MCP Server

Run the server locally when you want it on your own machine rather than reaching the Cloudaware remote endpoint — for example, in an IDE or CLI-based assistant on a workstation that already has repo-manager configured. The local server resolves the Export Project and SObjects Dataset for you, so no connection parameters or API keys are needed.

The local server is run through the repo-manager tool:

repo-manager mcp cloudaware

This setup uses:

repo-manager auth to automatically detect your Export Project and SObjects Dataset.
gcloud authentication to access your Cloudaware CMDB data in Google BigQuery.

note

Both authentication profiles (repo-manager and gcloud) must be configured before using the server.

The examples below assume repo-manager is available as a command alias. If it is not, replace the command with java -jar path/to/your/repo-manager.jar and keep the same arguments.

stdio

Claude Code (stdio)

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 run /mcp to verify the connection.

Antigravity CLI (stdio)

Add the following configuration to ~/.gemini/config/mcp_config.json (global) or .agents/mcp_config.json (workspace):

{
  "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 (legacy)

If you still use it, place the same mcpServers block in ~/.gemini/settings.json. The stdio configuration format is unchanged.

Kilo Code

Configuration uses the same mcpServers format shown for the Antigravity CLI. The configuration file is usually located in .kilocode/mcp.json in your working directory.

OpenCode

Add the following configuration to your opencode.json:

{
  "mcp": {
    "cloudaware-mcp": {
      "type": "local",
      "command": ["repo-manager", "mcp", "cloudaware"],
      "enabled": true
    }
  }
}

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

{
  "mcp": {
    "cloudaware-mcp": {
      "type": "local",
      "command": ["java", "-jar", "path/to/your/repo-manager.jar", "mcp", "cloudaware"],
      "enabled": true
    }
  }
}

Streamable HTTP

Start the Local HTTP Server

Run the server with an explicit port:

repo-manager mcp cloudaware --port 8888

The server becomes available at http://localhost:8888/mcp for tools that require HTTP access. Authentication is handled by your local repo-manager and gcloud profiles, so no token or API key is needed in the client configuration.

LM Studio

Edit mcp.json and add:

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

Troubleshooting

Symptom	Likely cause	Resolution
`401 Unauthorized`	Missing, expired, or revoked credentials.	Re-run the browser sign-in, or verify the API key in Cloudaware's Admin → API CREDENTIALS → API Keys.
Sign-in page offers no option that matches your login	Your organization signs in to Cloudaware with its own SSO.	Contact your Technical Account Manager at `tam@cloudaware.com` to have MCP authentication configured for your identity provider, or use an API key.
`403 Forbidden` on queries	The identity lacks BigQuery access.	Assign BigQuery Data Viewer and BigQuery Job User on the Export Project.
Server starts but exposes no data	Export Project or SObjects Dataset not resolved.	For remote connections, verify the `exportProject` and `sObjectsDataset` values. For local, re-run `repo-manager auth` and `gcloud auth login`.
Local server fails to start	`repo-manager` or `gcloud` profile not configured.	Configure both authentication profiles, then retry.

Refer to MCP Server Overview for concepts, capabilities, and use cases.

Choose a Connection Method​

Prerequisites​

Export Project and SObjects Dataset​

Required Permissions​

Connection Parameters​

Tools​

Connect to the Cloudaware Remote MCP Server​

Authentication​

Sign In Through the Browser​

Create an API Key​

Use an API Key​

Claude Code​

Claude.ai​

Pro and Max Plan​

Team and Enterprise Plan​

Antigravity CLI​

LibreChat​

n8n.cloud​

ChatGPT​

Connect to a Local MCP Server​

stdio​

Claude Code (stdio)​

Antigravity CLI (stdio)​

Kilo Code​

OpenCode​

Streamable HTTP​

Start the Local HTTP Server​

LM Studio​

Troubleshooting​

Related​

Choose a Connection Method

Prerequisites

Export Project and SObjects Dataset

Required Permissions

Connection Parameters

Tools

Connect to the Cloudaware Remote MCP Server

Authentication

Sign In Through the Browser

Create an API Key

Use an API Key

Claude Code

Claude.ai

Pro and Max Plan

Team and Enterprise Plan

Antigravity CLI

LibreChat

n8n.cloud

ChatGPT

Connect to a Local MCP Server

stdio

Claude Code (stdio)

Antigravity CLI (stdio)

Kilo Code

OpenCode

Streamable HTTP

Start the Local HTTP Server

LM Studio

Troubleshooting

Related