MCP Tools Reference: chronicle.googleapis.com

Tool: list_integration_instances

Lists all configured instances for a given SOAR Integration. You can also list instances across all integrations by passing "-" as the integration_id. Each instance returned contains a name field which is its resource name (e.g., projects/.../integrations/.../instances/{instance_guid}). The {instance_guid} at the end of this name is the IntegrationInstance GUID required by the execute_manual_action tool when running script-based actions.

Retrieves a paginated list of all configured integration instances, which are specific configurations of an integration. This is useful for discovering the specific instances of an integration that are available for use in playbooks and manual actions.

Workflow Integration: - Used to populate a UI with a list of available integration instances for an analyst to choose from. - Enables automated systems to discover and verify that required integration instances are present before executing a playbook that depends on them. - Essential for auditing and managing the inventory of all third-party connections in the SOAR platform.

Use Cases: - A security analyst lists available integration instances to find the correct instance to use for a specific task. - A SOAR engineer reviews the list of all integration instances to identify any that need to be updated, configured, or retired. - An automated script queries for a specific integration instance by name to ensure it is installed before running a playbook that uses its actions.

Args: project_id (str): Google Cloud project ID (required). customer_id (str): Chronicle customer ID (required). region (str): Chronicle region (e.g., "us", "europe") (required). integration_id (str): The ID of the integration to list instances for (required). If "-" is provided, instances for all integrations will be listed. page_size (int, optional): The maximum number of integration instances to return in a single response. If unspecified, the server will use a default page size. page_token (str, optional): A token for fetching a specific page of results, obtained from a previous call. filter (str, optional): A filter string to apply to the list of integration instances. order_by (str, optional): A comma-separated list of fields to sort the results by.

Returns: ListIntegrationInstancesResponse: A response object containing a list of IntegrationInstance objects and a next_page_token if more results are available. Each IntegrationInstance object contains the following key fields: - Name (str): The full resource name of the integration instance, ending with the IntegrationInstance GUID. - Identifier (str): The unique script identifier for the integration (e.g., "SiemplifyUtilities"). - DisplayName (str): The user-friendly name of the integration instance. - Version (str): The version of the integration. - Description (str): A summary of the integration's purpose. - Type (str): The type of integration (e.g., "SDK", "SCRIPT"). - Custom (bool): Whether the integration is custom. - Certified (bool): Whether the integration is certified. - UpdateAvailable (bool): Indicates if a newer version of the integration is available. - LatestVersion (str): The latest available version string. Returns an error message if the parent instance is not found or the request is invalid.

Example Usage: # List all integration instances for a specific integration list_integration_instances(project_id='123', region='us', customer_id='abc', integration_id='my-integration')

# List all integration instances across all integrations by using integration_id="-"
        list_integration_instances(project_id='123', region='us', customer_id='abc', integration_id='-')

Next Steps (using MCP-enabled tools): - Use the GUID from the name field of an instance as the IntegrationInstance value in the properties dictionary when calling execute_manual_action for script-based actions.

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

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

Input Schema

Request message for ListIntegrationInstances.

ListIntegrationInstancesRequest

JSON representation 
{
  "projectId": string,
  "customerId": string,
  "region": string,
  "integrationId": string,
  "pageSize": integer,
  "pageToken": string,
  "filter": string,
  "orderBy": string
}
Fields
projectId

string

Project ID of the customer.
customerId

string

Customer ID of the customer.
region

string

Region of the customer.
integrationId

string

Integration ID.
pageSize

integer

The maximum number of integration instances to return.
pageToken

string

A token for fetching the next page of results.
filter

string

A filter to apply to the list of integration instances.
orderBy

string

The field to order the results by.

Output Schema

Response message for ListIntegrationInstances.

ListIntegrationInstancesResponse

JSON representation 
{
  "integrationInstances": [
    {
      object (IntegrationInstance)
    }
  ],
  "nextPageToken": string,
  "totalSize": integer
}
Fields
integrationInstances[]

object (IntegrationInstance)

The list of IntegrationInstances.
nextPageToken

string

Optional. A token, which can be sent as page_token to retrieve the next page. If this field is omitted, there are no subsequent pages.
totalSize

integer

The total number of IntegrationInstances.

IntegrationInstance

JSON representation 
{
  "name": string,
  "environment": string,
  "displayName": string,
  "parameters": [
    {
      object (IntegrationInstanceParameter)
    }
  ],
  "integrationIdentifier": string,
  "identifier": string,

  // Union field _description can be only one of the following:
  "description": string
  // End of list of possible types for union field _description.

  // Union field _configured can be only one of the following:
  "configured": boolean
  // End of list of possible types for union field _configured.

  // Union field _remote can be only one of the following:
  "remote": boolean
  // End of list of possible types for union field _remote.

  // Union field _agent can be only one of the following:
  "agent": string
  // End of list of possible types for union field _agent.

  // Union field _system_default can be only one of the following:
  "systemDefault": boolean
  // End of list of possible types for union field _system_default.
}
Fields
name

string

Identifier. The unique name of the integration instance. Format: projects/{project}/locations/{location}/instances/{instance}/integrations/{integration}/integrationInstances/{instance}
environment

string

Required. The integration instance environment.
displayName

string

Optional. The display name of the integration instance. Automatically generated if not assigned. Limited to 110 characters.
parameters[]

object (IntegrationInstanceParameter)

Optional. Integration's parameters.
integrationIdentifier

string

Output only. The integration identifier.
identifier

string

Output only. The integration instance identifier.

Union field _description.

_description can be only one of the following:
description

string

Optional. The integration instance description. Limited to 1500 characters.

Union field _configured.

_configured can be only one of the following:
configured

boolean

Output only. Determines whether the integration instance is configured.

Union field _remote.

_remote can be only one of the following:
remote

boolean

Output only. True if the integration instance is a remote instance. Instance is created with remote = false by default.

Union field _agent.

_agent can be only one of the following:
agent

string

Optional. The agent identifier for a remote integration instance

Union field _system_default.

_system_default can be only one of the following:
systemDefault

boolean

Output only. Indicates whether the integration instance is the system default.

IntegrationInstanceParameter

JSON representation 
{
  "id": string,
  "displayName": string,
  "type": enum (IntegrationParameterType),

  // Union field _description can be only one of the following:
  "description": string
  // End of list of possible types for union field _description.

  // Union field _property_name can be only one of the following:
  "propertyName": string
  // End of list of possible types for union field _property_name.

  // Union field _mandatory can be only one of the following:
  "mandatory": boolean
  // End of list of possible types for union field _mandatory.

  // Union field _value can be only one of the following:
  "value": string
  // End of list of possible types for union field _value.
}
Fields
id

string (int64 format)

Output only. The unique id of the integration instance parameter.
displayName

string

Output only. The integration instance parameter display name.
type

enum (IntegrationParameterType)

Output only. The integration instance parameter type.

Union field _description.

_description can be only one of the following:
description

string

Output only. The integration instance parameter description.

Union field _property_name.

_property_name can be only one of the following:
propertyName

string

Output only. The integration instance parameter property name.

Union field _mandatory.

_mandatory can be only one of the following:
mandatory

boolean

Output only. Indicates if the parameter is required when configuring the integration instance.

Union field _value.

_value can be only one of the following:
value

string

Optional. The parameter's value.

Tool Annotations

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