MCP Tools Reference: capacityplanner.googleapis.com

Tool: query_usage_forecasts

Returns forecasted future usage time series for resources like Compute Engine (vCPUs, RAM, Local SSD, Persistent Disk, GPUs, and TPUs) in a project, folder, or organization. Each forecast includes median, lower-bound, and upper-bound series for 50% or 90% prediction intervals. Use this tool to anticipate future demand. Requires parent (for example, 'projects/{project}/locations/{location}', 'folders/{folder}/locations/{location}', or 'organizations/{organization}/locations/{location}') and cloudResourceType.

The following code sample shows how to use curl to call the query_usage_forecasts MCP tool.

Curl Request 
curl --location 'https://capacityplanner.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "query_usage_forecasts",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Input Schema

The QueryForecasts request.

QueryForecastsRequest

JSON representation 
{
  "parent": string,
  "machineFamily": string,
  "machineShape": {
    object (MachineShape)
  },
  "diskType": string,
  "confidentialMode": boolean,
  "gpuType": string,
  "tpuType": string,
  "cloudResourceType": string,
  "forecastType": enum (ForecastType),
  "predictionInterval": enum (PredictionInterval),
  "aggregationMethod": enum (AggregationMethod),
  "startDate": {
    object (Date)
  },
  "endDate": {
    object (Date)
  },
  "generationDate": {
    object (Date)
  }
}
Fields
parent

string

Required. The project, folder, or organization and location for the time series values to return. The format is:

projects/{project}/locations/{location} or organizations/{organization}/locations/{location} or folders/{folder}/locations/{location}
machineFamily

string

Optional. The machine family to use to select the Forecast values to return. Possible values include "n1", and "n2d". Empty machine_family will return results matching all machine families.
machineShape

object (MachineShape)

Optional. The machine shape for the time series values to return.
diskType

string

Optional. The disk_type for the Forecast values to return with request persistent-disk cloud_resource_type. Empty disk_type will return results matching all disk types.
confidentialMode

boolean

Optional. Whether the persistent disk is in confidential mode.
gpuType

string

Optional. The GPU type for the Forecast values to return. Sample values are "nvidia-tesla-t4", and "nvidia-tesla-a100". See https://cloud.google.com/compute/docs/gpus for a list. Empty gpu_type will return results matching all GPUs.
tpuType

string

Optional. The TPU type for the Forecast values to return. Empty tpu_type will return results matching all TPUs.
cloudResourceType

string

Required. The resource for the Forecast values to return. Possible values include "gce-vcpus", "gce-ram", "gce-local-ssd", "gce-persistent-disk", "gce-gpu" and "gce-tpu".
forecastType

enum (ForecastType)

Optional. The type of forecast to use to select the Forecast values to return. FORECAST_TYPE_UNSPECIFIED will return results matching all the forecast types.
predictionInterval

enum (PredictionInterval)

Optional. The prediction interval to use to select the Forecast values to return. PREDICTION_INTERVAL_UNSPECIFIED will return results matching all prediction intervals.
aggregationMethod

enum (AggregationMethod)

Optional. Aggregation Method of the historical usage for which the forecast is generated
startDate

object (Date)

Optional. The start date from which you want the Forecast records to be returned (inclusive).
endDate

object (Date)

Optional. The last date until which you want the Forecast records to be returned (inclusive).
generationDate

object (Date)

Optional. If specified, this field returns the Forecast data from the latest run on or after the provided generationDate. If not specified, this field returns the most recently generated forecast.

MachineShape

JSON representation 
{
  "machineFamily": string,
  "machineType": string,
  "machineShape": string,
  "cpuCores": number,
  "gpuType": string,
  "gpuComputeType": string,
  "gpuCores": string,
  "localSsdPartitions": string,
  "localSsdGb": number,
  "memoryGb": number,
  "localSsdInterface": string,
  "minCpuPlatform": string
}
Fields
machineFamily

string

Optional. The VM family.
machineType

string

Optional. The characteristics of the sampled VM expressed as a string.
machineShape

string

Optional. The customer visible string representing the type of VM.
cpuCores

number

Optional. Number of CPU cores per VM.
gpuType

string

Optional. The type of GPU with the VM.
gpuComputeType

string

Optional. The GPU name recognized by Compute Engine APIs.
gpuCores

string (int64 format)

Optional. The number of GPU cores per VM.
localSsdPartitions

string (int64 format)

Optional. The number of local SSD partitions per VM.
localSsdGb

number

Optional. Total amount of local SSD storage.
memoryGb

number

Optional. Total amount of memory with the VM.
localSsdInterface

string

Optional. The local SSD interface used such as nvme or scsi
minCpuPlatform

string

Optional. The minimum CPU platform used, such as icelake.

Date

JSON representation 
{
  "year": integer,
  "month": integer,
  "day": integer
}
Fields
year

integer

Year of the date. Must be from 1 to 9999, or 0 to specify a date without a year.
month

integer

Month of a year. Must be from 1 to 12, or 0 to specify a year without a month and day.
day

integer

Day of a month. Must be from 1 to 31 and valid for the year and month, or 0 to specify a year by itself or a year and month where the day isn't significant.

ForecastType

The type of the forecast. This describes the method that was used to produce future time series values from historical time series values.

Enums
FORECAST_TYPE_UNSPECIFIED No forecast type is specified.
STATISTICAL Statistical forecast.
STATISTICAL_WITH_BFCM Statistical forecast that attempts to predict the seasonal effects of Black Friday and Cyber Monday.
YEARLY_SEASONALITY Yearly Seasonality model provides generic seasonality beyond BFCM.

PredictionInterval

The prediction interval represented by a forecast.

Enums
PREDICTION_INTERVAL_UNSPECIFIED No prediction interval is specified.
PREDICTION_INTERVAL_90 This represents a prediction interval that has 90% confidence. For example, for a symmetric prediction interval, a PredictionInterval of PREDICTION_INTERVAL_90 means that the UPPER_BOUND will represent the 95th percentile.
PREDICTION_INTERVAL_50 This represents a prediction interval that has 50% confidence. For example, for a symmetric prediction interval, a PredictionInterval of PREDICTION_INTERVAL_50 means that the UPPER_BOUND will represent the 75th percentile.

AggregationMethod

Methods for converting sampled data to time series values.

Enums
AGGREGATION_METHOD_UNSPECIFIED No aggregation method is specified.
MEDIAN Deprecated: Use P50 instead.
PEAK Deprecated: Use P99 instead.
P50 Time series values represent the 50th(median) percentile of the sampled values.
P75 Time series values represent the 75th percentile of the sampled values.
P99 Time series values represent the 99th percentile of the sampled values.
P100 Time series values represent the max of the sampled values.

Output Schema

The QueryForecasts response.

QueryForecastsResponse

JSON representation 
{
  "forecasts": [
    {
      object (Forecast)
    }
  ]
}
Fields
forecasts[]

object (Forecast)

The forecasts that match the request.

Forecast

JSON representation 
{
  "name": string,
  "timeSeries": {
    object (TimeSeries)
  },
  "forecastType": enum (ForecastType),
  "bounds": enum (Bounds),
  "predictionInterval": enum (PredictionInterval),
  "aggregationMethod": enum (AggregationMethod)
}
Fields
name

string

Identifier. The resource name of the forecast in the form of: projects/{project_id}/locations/{location_id}/forecasts/{forecast_id} or organizations/{organization_id}/locations/{location_id}/forecasts/{forecast_id} or folders/{folder_id}/locations/{location_id}/forecasts/{forecast_id}
timeSeries

object (TimeSeries)

The collection of data points that represent the predicted values. Note that some of these values may be in the past (if, for example, the forecast was created in the past and predicted values for the present day).
forecastType

enum (ForecastType)

The type of forecast.
bounds

enum (Bounds)

The bounds represented by this forecast time series.
predictionInterval

enum (PredictionInterval)

The prediction interval represented by the time series.
aggregationMethod

enum (AggregationMethod)

Aggregation Method of the historical usage for which the forecast is generated

TimeSeries

JSON representation 
{
  "locationType": enum (LocationType),
  "location": string,
  "isSpot": boolean,
  "machineFamily": string,
  "diskType": string,
  "confidentialMode": boolean,
  "gpuType": string,
  "tpuType": string,
  "machineShape": {
    object (MachineShape)
  },
  "gcsBucketTraffic": {
    object (GcsBucketTraffic)
  },
  "cloudResourceType": string,
  "points": [
    {
      object (Point)
    }
  ],
  "unit": string
}
Fields
locationType

enum (LocationType)

Required. The type of location that the time series is summarizing.
location

string

Optional. The location of the usage data in time series.
isSpot

boolean

Optional. Whether the time series represents usage of Spot (preemptible) resources.
machineFamily

string

The machine family for the time series values to return. Possible values include "n1" and "n2d".
diskType

string

The disk type for the time series values to return.
confidentialMode

boolean

Optional. The confidential mode for disk.
gpuType

string

The GPU type of the time series.
tpuType

string

The TPU type of the time series.
machineShape

object (MachineShape)

The machine shape of the time series.
gcsBucketTraffic

object (GcsBucketTraffic)

Output only. The Cloud Storage bucket traffic resource for usage time series.
cloudResourceType

string

The resource for the time series values to return. Possible values include "gce-vcpus", "gce-ram", "gce-local-ssd", "gce-persistent-disk", "gce-gpu", "gce-tpu" and "gce-vm".
points[]

object (Point)

The data points of this time series. When listing time series, points are returned in chronological order.
unit

string

The units in which the values are reported.

MachineShape

JSON representation 
{
  "machineFamily": string,
  "machineType": string,
  "machineShape": string,
  "cpuCores": number,
  "gpuType": string,
  "gpuComputeType": string,
  "gpuCores": string,
  "localSsdPartitions": string,
  "localSsdGb": number,
  "memoryGb": number,
  "localSsdInterface": string,
  "minCpuPlatform": string
}
Fields
machineFamily

string

Optional. The VM family.
machineType

string

Optional. The characteristics of the sampled VM expressed as a string.
machineShape

string

Optional. The customer visible string representing the type of VM.
cpuCores

number

Optional. Number of CPU cores per VM.
gpuType

string

Optional. The type of GPU with the VM.
gpuComputeType

string

Optional. The GPU name recognized by Compute Engine APIs.
gpuCores

string (int64 format)

Optional. The number of GPU cores per VM.
localSsdPartitions

string (int64 format)

Optional. The number of local SSD partitions per VM.
localSsdGb

number

Optional. Total amount of local SSD storage.
memoryGb

number

Optional. Total amount of memory with the VM.
localSsdInterface

string

Optional. The local SSD interface used such as nvme or scsi
minCpuPlatform

string

Optional. The minimum CPU platform used, such as icelake.

GcsBucketTraffic

JSON representation 
{
  "trafficPath": enum (TrafficPath),
  "bucketLocationType": enum (LocationType),
  "bucketLocation": string
}
Fields
trafficPath

enum (TrafficPath)

Optional. Path type for the Cloud Storage bucket traffic.
bucketLocationType

enum (LocationType)

Optional. Location type of the Cloud Storage bucket.
bucketLocation

string

Optional. Location of the Cloud Storage bucket e.g. us-central1 (single region), us (multi region) and eur4 - europe-north1 and europe-west4 (dual region).

Point

JSON representation 
{
  "eventTime": string,
  "value": number
}
Fields
eventTime

string (Timestamp format)

The time which the data point applies.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
value

number

The value of the data point.

Timestamp

JSON representation 
{
  "seconds": string,
  "nanos": integer
}
Fields
seconds

string (int64 format)

Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be between -62135596800 and 253402300799 inclusive (which corresponds to 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z).
nanos

integer

Non-negative fractions of a second at nanosecond resolution. This field is the nanosecond portion of the duration, not an alternative to seconds. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be between 0 and 999,999,999 inclusive.

LocationType

The type of location that the time series is summarizing.

Enums
LOCATION_TYPE_UNSPECIFIED No location type was specified.
REGIONAL Time series values represent usage aggregated at the region level.
ZONAL Time series values represent usage aggregated at the zone level.

TrafficPath

Path type for the Cloud Storage bucket traffic.

Enums
TRAFFIC_PATH_UNSPECIFIED Unspecified traffic path.
TRAFFIC_PATH_GOOGLE Traffic path through Google's network.
TRAFFIC_PATH_INTERNET Traffic path through the internet.

LocationType

Location type/level of the Cloud Storage bucket.

Enums
LOCATION_TYPE_UNSPECIFIED Unspecified location type.
LOCATION_TYPE_SINGLE_REGION Single region location type.
LOCATION_TYPE_DUAL_REGION Dual region location type.
LOCATION_TYPE_MULTI_REGION Multi region location type.

ForecastType

The type of the forecast. This describes the method that was used to produce future time series values from historical time series values.

Enums
FORECAST_TYPE_UNSPECIFIED No forecast type is specified.
STATISTICAL Statistical forecast.
STATISTICAL_WITH_BFCM Statistical forecast that attempts to predict the seasonal effects of Black Friday and Cyber Monday.
YEARLY_SEASONALITY Yearly Seasonality model provides generic seasonality beyond BFCM.

Bounds

The bounds of the forecast time series.

Enums
BOUNDS_UNSPECIFIED No bounds is specified.
LOWER_BOUND The time series represents the lower bound of the forecast.
MEDIAN The time series represents the median expected forecast value.
UPPER_BOUND The time series represents the upper bound of the forecast.

PredictionInterval

The prediction interval represented by a forecast.

Enums
PREDICTION_INTERVAL_UNSPECIFIED No prediction interval is specified.
PREDICTION_INTERVAL_90 This represents a prediction interval that has 90% confidence. For example, for a symmetric prediction interval, a PredictionInterval of PREDICTION_INTERVAL_90 means that the UPPER_BOUND will represent the 95th percentile.
PREDICTION_INTERVAL_50 This represents a prediction interval that has 50% confidence. For example, for a symmetric prediction interval, a PredictionInterval of PREDICTION_INTERVAL_50 means that the UPPER_BOUND will represent the 75th percentile.

AggregationMethod

Methods for converting sampled data to time series values.

Enums
AGGREGATION_METHOD_UNSPECIFIED No aggregation method is specified.
MEDIAN Deprecated: Use P50 instead.
PEAK Deprecated: Use P99 instead.
P50 Time series values represent the 50th(median) percentile of the sampled values.
P75 Time series values represent the 75th percentile of the sampled values.
P99 Time series values represent the 99th percentile of the sampled values.
P100 Time series values represent the max of the sampled values.

Tool Annotations

Tool annotations are sent to MCP clients to describe the basic risk of a given tool. Most clients treat these hints as untrusted, but they can be used to decide when a confirmation prompt might be sent to a user.

Along with the title string, the following boolean hints are defined as follows:

  • readOnlyHint: If true, the tool doesn't modify its environment. Default: false.
  • destructiveHint: If true, then the tool can perform destructive actions. If false, then the tool can only perform additive actions. Default: true.
  • idempotentHint: If true, then calling the tool repeatedly with the same arguments will have no additional effect on its environment. Default: false.
  • openWorldHint: If true, then the tool can interact with an 'open world' of external entities. If false, then the tool can only interact with internal entities. For example, a web search tool would be open world, while a memory tool would not be open world.

Destructive Hint: ❌ | Idempotent Hint: ✅ | Read Only Hint: ✅ | Open World Hint: ❌