MCP Tools Reference: maintenance.googleapis.com

Tool: list_resource_maintenances

Lists resource maintenances for a given project and location.

Parameters

  • parent (string, Required): The parent of the resource maintenance, in the format projects/{project}/locations/{location}.
  • page_size (integer, Optional): The maximum number of resource maintenances to send per page.
  • page_token (string, Optional): A page token, received from a previous ListResourceMaintenances call.
  • filter (string, Optional): Filter the list as specified in https://google.aip.dev/160.
  • order_by (string, Optional): Order results as specified in https://google.aip.dev/132.

Return Value

The method returns a ListResourceMaintenancesResponse object, which contains:

  • resource_maintenances: A list of resource maintenances matching the request criteria.
  • next_page_token: A token that can be sent as page_token in a subsequent request to retrieve the next page of results.

Notes

  • Use '-' as location for a global view across all regions.

The following sample demonstrate how to use curl to invoke the list_resource_maintenances MCP tool.

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

Input Schema

The request structure for the ListResourceMaintenances method.

ListResourceMaintenancesRequest

JSON representation 
{
  "parent": string,
  "pageSize": integer,
  "pageToken": string,
  "filter": string,
  "orderBy": string
}
Fields
parent

string

Required. The parent of the resource maintenance.
pageSize

integer

The maximum number of resource maintenances to send per page.
pageToken

string

The page token: If the next_page_token from a previous response is provided, this request will send the subsequent page.
filter

string

Filter the list as specified in https://google.aip.dev/160.
orderBy

string

Order results as specified in https://google.aip.dev/132.

Output Schema

The response structure for the ListResourceMaintenances method.

ListResourceMaintenancesResponse

JSON representation 
{
  "resourceMaintenances": [
    {
      object (ResourceMaintenance)
    }
  ],
  "nextPageToken": string,
  "unreachable": [
    string
  ]
}
Fields
resourceMaintenances[]

object (ResourceMaintenance)

The resulting resource maintenances.
nextPageToken

string

If present, the next page token can be provided to a subsequent ListResourceMaintenances call to list the next page. If empty, there are no more pages.
unreachable[]

string

Locations that could not be reached.

ResourceMaintenance

JSON representation 
{
  "name": string,
  "resource": {
    object (Resource)
  },
  "maintenance": {
    object (Maintenance)
  },
  "state": enum (State),
  "createTime": string,
  "updateTime": string,
  "maintenanceStartTime": string,
  "maintenanceEndTime": string,
  "maintenanceCancelTime": string,
  "maintenanceScheduledStartTime": string,
  "maintenanceScheduledEndTime": string,
  "userControllable": boolean,
  "controls": [
    {
      object (MaintenanceControl)
    }
  ],
  "labels": {
    string: string,
    ...
  },
  "annotations": {
    string: string,
    ...
  },
  "uid": string,
  "etag": string
}
Fields
name

string

Identifier. The name of the resource_maintenance resource. Format: "projects/{project}/locations/{location}/resourceMaintenance/{resource-maintenance-id}"
resource

object (Resource)

Output only. The resource spec of the resource maintenance.
maintenance

object (Maintenance)

Output only. The details of the maintenance.
state

enum (State)

Output only. The state of the resource maintenance.
createTime

string (Timestamp format)

Output only. The create time of the resource maintenance.

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".
updateTime

string (Timestamp format)

Output only. The update time of the resource maintenance.

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".
maintenanceStartTime

string (Timestamp format)

Output only. The time when the resource maintenance has started.

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".
maintenanceEndTime

string (Timestamp format)

Output only. The time when the resource maintenance has completed.

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".
maintenanceCancelTime

string (Timestamp format)

Output only. The time when the resource maintenance was cancelled.

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".
maintenanceScheduledStartTime

string (Timestamp format)

Output only. The time when the maintenance on the resource was scheduled to start.

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".
maintenanceScheduledEndTime

string (Timestamp format)

Output only. The time when the maintenance on the resource was scheduled to end.

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".
userControllable

boolean

Output only. Indicates whether the user has some control over that maintenance, either proactively before maintenance was scheduled with maintenance policy or with reactive controls after it was scheduled (see controls field)
controls[]

object (MaintenanceControl)

Output only. The controls of the maintenance.
labels

map (key: string, value: string)

Optional. The labels on the resource, which can be used for categorization. similar to Kubernetes resource labels.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
annotations

map (key: string, value: string)

Optional. Annotations is an unstructured key-value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata. They are not queryable and should be preserved when modifying objects.

More info: https://kubernetes.io/docs/user-guide/annotations

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
uid

string

Output only. The unique identifier of the resource. UID is unique in the time and space for this resource within the scope of the service. It is typically generated by the server on successful creation of a resource and must not be changed. UID is used to uniquely identify resources with resource name reuses. This should be a UUID4.
etag

string

Output only. An opaque value that uniquely identifies a version or generation of a resource. It can be used to confirm that the client and server agree on the ordering of a resource being written.

Resource

JSON representation 
{
  "resourceName": string,
  "location": string,
  "type": string
}
Fields
resourceName

string

Output only. Name is the reference to the consumer resource affected by the maintenance. Available values can be found here: https://cloud.google.com/asset-inventory/docs/asset-names
location

string

Output only. The location of the resource. Format: us-central1
type

string

Output only. The type of the resource. Available values can be found here: https://cloud.google.com/asset-inventory/docs/asset-types#supported_resource_types Please note that not all the resource types will have their maintenances reported.

Maintenance

JSON representation 
{
  "maintenanceName": string,
  "title": string,
  "description": string,
  "category": enum (MaintenanceCategory)
}
Fields
maintenanceName

string

Maintenance is the name of the corresponding maintenance resource following the standard naming scheme: "{maintenance-id}"
title

string

Output only. The title of the maintenance.
description

string

Output only. The description of the maintenance.
category

enum (MaintenanceCategory)

Output only. The category of the maintenance.

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.

MaintenanceControl

JSON representation 
{
  "control": enum (Control),
  "isCustom": boolean,
  "documentation": string
}
Fields
control

enum (Control)

The control of the resource maintenance.
isCustom

boolean

Indicates whether the control is available only in Service Producer API (not through Unified Maintenance).
documentation

string

Link to Service Producer documentation about maintenance control. Provided only when isCustom is true.

LabelsEntry

JSON representation 
{
  "key": string,
  "value": string
}
Fields
key

string
value

string

AnnotationsEntry

JSON representation 
{
  "key": string,
  "value": string
}
Fields
key

string
value

string

MaintenanceCategory

The Category of the maintenance.

Enums
MAINTENANCE_CATEGORY_UNSPECIFIED Unspecified category.
INFRASTRUCTURE Infrastructure maintenance events are times that Google Cloud performs regular maintenance on network equipment e.g. Google Cloud Interconnect These events are usually scheduled in advance and we provide notification, when possible, so that users can plan for the infrastructure maintenance event and prevent downtime. Infrastructure maintenance events don't have a set interval between occurrences, but generally occur several times a year.
SERVICE_UPDATE Updates that can include bug fixes, changes, or new features that are backward compatible with existing versions (including patches). Some SPs allow users to control the scheduling of these maintenance events using maintenance windows and/or deny maintenance features.

State

State is the state of a resource maintenance.

Enums
STATE_UNSPECIFIED Unspecified state.
SCHEDULED Scheduled for a particular window. For disruptive maintenance it should respect maintenance policy, i.e. its available windows, exclusions and notification period.
RUNNING Maintenance is ongoing.
CANCELLED No longer planned, typically when other maintenance (e.g. upgrade to newer version) already happened, or the user skipped the maintenance.
SUCCEEDED Successfully completed.

Control

Sets the type of control supported. comment (as in logs).

Enums
CONTROL_UNSPECIFIED Unspecified control.
APPLY Apply control.
MANAGE_POLICY Manage policy control.
RESCHEDULE Reschedule control.

Tool Annotations

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