MCP Server for Platform Management¶

This MCP server lets you manage and observe your platform resources (warehouses, tenant entitlements, usage, events, and telemetry) from an AI client using natural language. It implements the Model Context Protocol (MCP), an open standard for connecting AI clients to external tools and data.

After the server is connected to an MCP-aware client, such as Claude Desktop, Claude Code, or the MCP Inspector, you can ask questions such as "list my warehouses" or "show usage for warehouse wh-123 last week", and the client calls the matching tool on the server.

This page covers warehouse management operations. For access to the data inside a warehouse, see MCP Server for Warehouse Data Access.

Server Capabilities¶

The server speaks MCP over HTTP streamable transport at the path /mcp, and exposes 12 tools across six domains.

The server does not publish MCP resources or prompts. Its surface is tools only. If your client has a resources or prompts panel, it is empty for this server. That is expected; use the tool catalog instead.

Service Endpoints¶

Connecting MCP Client¶

The server is a full OAuth 2.0 protected resource. A client that supports remote MCP servers drives the authorization flow itself, opening a browser, signing you in, and attaching the result to every request, so you do not manage any credentials by hand.

Every client needs the same two things to add the server.

No client secret is needed. Leave that field blank if your client asks for one.

Claude also needs a local callback port, the port on your machine that it temporarily listens on to receive the OAuth redirect during login. This is fixed at 3118; it is registered as part of the client ID's redirect URI and is not a value you choose yourself.

claude mcp add aap-mcp \
  --transport http \
  https://<mcp-host>/mcp \
  --client-id <CLIENT_ID> \
  --callback-port 3118

{
  "servers": {
    "aap-mcp": {
      "type": "http",
      "url": "https://<mcp-host>/mcp"
    }
  }
}

Verifying Connection¶

Once your client is connected, ask it to call the server_status tool (see Utility Tools), for example, "is the MCP server working?" It confirms the server is reachable and that your authentication is active.

Scopes¶

Each tool requires one of these scopes, granted based on your account's permissions:

If your account does not have a scope a tool needs, that tool call fails with an authorization error. See Troubleshooting.

Tool Conventions¶

These conventions apply to every tool:

• Tools resolve your identity automatically once your client is connected. You never pass tokens, user names, or tenant IDs as tool parameters.
• Tools marked read-only do not change state.
• Dates are ISO 8601 strings. In a date range, from_date must be strictly earlier than to_date.
• Invalid input is returned as a structured error that names the offending field.

Warehouse Tools¶

list_warehouses¶

Lists the warehouses visible to you. Read-only. Scope: read:warehouses. No parameters.

Example prompt:

"List all my warehouses."

Response shape:

{
  "resources": [
    { "id": "wh-abc-123" }
  ],
  "count": 1
}

Only id is guaranteed on each resource. Additional fields returned by the platform, such as name, status, or region, are passed through unchanged.

get_warehouse¶

Gets the full details of a single warehouse. Read-only. Scope: read:warehouses.

Example prompt:

"Show me details for warehouse wh-abc-123."

Example tool call:

{ "warehouse_id": "wh-abc-123" }

As with list_warehouses, only id is guaranteed; other fields are passed through.

start_warehouse¶

Starts a stopped warehouse. Scope: write:warehouses.

Example prompt:

"Start warehouse wh-abc-123."

Example response:

{
  "operation_status": "in_progress",
  "warehouse_id": "wh-abc-123",
  "warehouse_status": "starting"
}

operation_status is one of in_progress, succeeded, rejected, or failed. Starting is asynchronous. Poll get_warehouse to confirm the warehouse has reached the state you want.

stop_warehouse¶

Stops a running warehouse. Scope: write:warehouses.

Example prompt:

"Stop warehouse wh-abc-123."

scale_warehouse¶

Scales a warehouse to a target number of Actian Units (AUs). Scope: write:warehouses.

Example prompt:

"Scale warehouse wh-abc-123 to 8 units."

Example tool call:

{ "warehouse_id": "wh-abc-123", "avalanche_units": 8 }

update_warehouse_allow_list¶

Updates a warehouse's IP allow list by adding entries, removing entries, or relabeling existing entries. Scope: write:warehouses.

At least one of additions, removals, or changeLabel must be non-empty.

A LabeledCIDR has this shape:

{ "allowListIp": "10.1.0.0/24", "label": "Corporate Network" }

allowListIp is required and must be a valid IP address or CIDR block. label is optional for additions and removals, and is expected for changeLabel, whose purpose is to set a new label.

Example prompt:

"Add 10.1.0.0/24, labeled Corporate Network, to the allow list of warehouse wh-abc-123."

Example tool call:

{
  "warehouse_id": "wh-abc-123",
  "allow_list_changes": {
    "additions": [
      { "allowListIp": "10.1.0.0/24", "label": "Corporate Network" }
    ]
  }
}

Tenant Tools¶

get_tenant_details¶

Gets details for your tenant, including AU quota and consumption and the enabled feature flags. Read-only. Scope: read:tenant. No parameters.

Example prompt:

"What is my tenant's AU quota, and which feature flags are enabled?"

get_tenant_entitlements¶

Gets your tenant's entitlements, grouped by resource type (compute and storage), sorted by entitlement end date, along with the current entitlement phase. Read-only. Scope: read:tenant. No parameters.

The entitlement phase is one of trial, free-trial-exhausted, free-trial-expired, enterprise, or no-entitlements.

Example prompt:

"Show me my tenant's current entitlements and trial status."

Usage Tools¶

get_usage_details¶

Retrieves metered consumption for one warehouse over a date range, broken down by granularity. Results are keyed by category, for example, DWH, DWH_API, and DWH_backup, with consumption records per period. Read-only. Scope: read:warehouses.

Example prompt:

"Show me daily usage for warehouse wh-abc-123 between 2026-05-01 and 2026-05-31."

Example tool call:

{
  "warehouse_id": "wh-abc-123",
  "from_date": "2026-05-01",
  "to_date": "2026-05-31",
  "granularity": "daily"
}

Response shape:

{
  "duration": "P1D",
  "data": {
    "DWH": [
      {
        "id": "wh-abc-123",
        "consumption": {
          "2026-05-01T00:00:00Z": [
            { "ppid": "compute", "unit": "AUSeconds", "quantity": 3600 }
          ]
        }
      }
    ]
  }
}

Domain Events Tools¶

get_warehouse_domain_events¶

Retrieves Actian-formatted CloudEvents for a subject, normally a warehouse, within a date range. Read-only. Scope: retrieve:events.

Example prompt:

"Show me all warehouse events for wh-abc-123 last week."

Example tool call:

{
  "subject": "wh-abc-123",
  "from_date": "2026-05-25",
  "to_date": "2026-06-01",
  "max_count": 100
}

Returned event shape (CloudEvents 1.0):

{
  "id": "<uuid>",
  "source": "tag:actian.com,2024:event/source/<sourceId>/<custom>",
  "specversion": "1.0",
  "type": "com.actian.<...>",
  "datacontenttype": "application/json",
  "dataschema": "<url>",
  "subject": "wh-abc-123",
  "time": "2026-05-26T12:34:56Z",
  "actianeventversion": "0.1.1",
  "data": {
    "tenant": "...",
    "operator": "...",
    "operation": "...",
    "description": "...",
    "traceid": "<uuid>"
  }
}

Telemetry Tools¶

get_telemetry_metrics¶

Retrieves telemetry metrics for a resource (a warehouse, database, or job) over a time window. Read-only. Scope: retrieve:telemetry.

Example prompt:

"Get telemetry metrics for warehouse wh-abc-123 over the last 24 hours."

Example tool call:

{
  "resource_id": "wh-abc-123",
  "resource_type": ["warehouse"],
  "from_date": "2026-05-31",
  "to_date": "2026-06-01",
  "size": 50
}

Returned metric shape:

{
  "timestamp": "2026-05-31T12:00:00Z",
  "labels": { "warehouse": "wh-abc-123" },
  "metric": { "type": "cpu_utilization", "value": 0.42 }
}

Utility Tools¶

server_status¶

Confirms that the server is running and reachable, and that your authentication is propagating correctly. Read-only. No parameters. No specific scope is required; any authenticated connection can call it.

Example response:

{
  "status": "ok",
  "message": "MCP Warehouse Server is running.",
  "authenticated": true,
  "scopes": ["read:warehouses"]
}

Troubleshooting¶

Tool failures are returned as structured errors with this shape:

{
  "error_code": "authorization_error",
  "message": "Required scope 'read:warehouses' is missing"
}

The error_code value is one of authentication_error, authorization_error, validation_error, service_error, or internal_error.

Checking Server Reachability¶

curl -sS 'https://<mcp-host>/health'

Returns:

{"status":"ok"}

Checking Deployed Version¶

Useful when confirming whether a fix has been deployed:

curl -sS 'https://<mcp-host>/mcp/apiinfo'

Returns:

{
  "service": "aap-mcp-server",
  "version": "<APP_VERSION>",
  "gitCommit": "<APP_GIT_COMMIT>",
  "deploymentName": "<APP_DEPLOYMENT_NAME>"
}