Skip to main content

Google Chronicle API MCP Server

✅ RECOMMENDED API: This documentation covers the Chronicle API (v1), which is the modern, comprehensive API following Google Cloud API standards. For legacy integrations, see the Backstory API (v2) documentation.

Create a powerful Model Context Protocol (MCP) server for Google Chronicle API in minutes with our AI Gateway. This guide walks you through setting up seamless security operations integration with enterprise-grade security and instant OAuth authentication.

About Google Chronicle API (v1)​

Google Chronicle API (v1) is the modern, comprehensive API for Google Chronicle Security Operations. This API follows Google Cloud API standards with regional endpoints and full resource hierarchy management, providing enterprise-grade security analytics, threat detection, and investigation capabilities.

Google Chronicle is a cloud-native security information and event management (SIEM) platform that provides comprehensive security analytics, threat detection, and investigation capabilities. The Chronicle API enables programmatic access to security data, detection rules, threat intelligence, watchlists, reference lists, and investigation workflows.

Key Capabilities​

  • Instance Management: Multi-tenant support with instance-based isolation
  • Threat Detection: Create and manage custom YARA-L detection rules
  • Rule Management: Deploy, manage, and track detection rules with versioning
  • Retrohunts: Search historical data for threat patterns
  • Watchlists: Monitor high-risk entities (users, hosts, IPs)
  • Reference Lists: Manage threat intelligence indicators (IOCs)
  • Data Access Controls: Fine-grained access control with labels and scopes
  • Long-Running Operations: Async processing support for large operations
  • Regional Endpoints: 19 regional endpoints for optimal performance

API Features​

  • REST API: Standard Google Cloud API structure with resource hierarchy
  • Instance Management API: Create and manage Chronicle instances
  • Rules API: Create, manage, deploy, and version YARA-L detection rules
  • Rule Deployments API: Deploy and manage rule deployments
  • Retrohunts API: Run historical searches against detection rules
  • Reference Lists API: Manage threat intelligence indicators (SHA256, SHA1, MD5, IPs, domains, URLs, emails)
  • Watchlists API: Monitor and track high-risk entities
  • Data Access Labels API: Create and manage data access labels
  • Data Access Scopes API: Define access scopes with label associations
  • Operations API: Monitor and manage long-running operations
  • OAuth 2.0: Service account authentication with cloud-platform scope
  • Regional Endpoints: Location-specific endpoints for 19 regions
  • Rate Limiting: Varies by endpoint and customer tier

What You Can Do with Google Chronicle MCP Server​

The MCP server transforms Chronicle API into a natural language interface, enabling AI agents to:

Instance Management​

  • Instance Operations
    • "Get details for Chronicle instance my-instance"
    • "List all Chronicle instances in the project"
    • "Check instance status and health"
    • "Monitor instance configuration"

Threat Detection & Rules​

  • Detection Rule Management

    • "Create a YARA-L detection rule for suspicious PowerShell execution"
    • "Update the data exfiltration detection rule"
    • "List all high-priority detection rules"
    • "Disable detection rule for false positives"
    • "View rule revision history"

  • Rule Deployment

    • "Deploy the suspicious PowerShell rule to production"
    • "Undeploy a rule that's causing false positives"
    • "List all deployed rules"
    • "Check deployment status for a specific rule"

  • Retrohunts

    • "Run a retrohunt for the suspicious PowerShell rule over the last 30 days"
    • "Check retrohunt progress and results"
    • "List all retrohunts for a specific rule"
    • "Cancel a running retrohunt"

Threat Intelligence​

  • Reference Lists Management

    • "Create a reference list of known malware SHA256 hashes"
    • "Add IP addresses to the suspicious IPs reference list"
    • "Update domain indicators in the threat feed list"
    • "List all reference lists and their item counts"
    • "Get details for a specific reference list"

  • Watchlists Management

    • "Create a watchlist for high-risk users"
    • "Add compromised hosts to the watchlist"
    • "Monitor entities in the high-risk users watchlist"
    • "Update watchlist descriptions"
    • "List all active watchlists"

Data Access Control​

  • Data Access Labels

    • "Create a data access label for PII data"
    • "List all data access labels"
    • "Update label descriptions"
    • "Get label details"

  • Data Access Scopes

    • "Create a data access scope for finance team"
    • "Associate labels with a scope"
    • "List all data access scopes"
    • "Update scope configurations"

Operations Management​

  • Long-Running Operations
    • "Check status of operation operation-123"
    • "List all running operations"
    • "Cancel a long-running operation"
    • "Monitor operation progress"

Prerequisites​

  • Access to Cequence AI Gateway
  • Google Cloud Console account with Chronicle enabled
  • Chronicle Security Operations subscription
  • Administrative access to create service account credentials
  • Contact with Google Security Operations representative for API access
  • Chronicle instance ID (provided by Google Security Operations)
  • GCP project ID and location/region information

Step 1: Enable Chronicle API and Create Service Account​

Before setting up the MCP server, you need to enable the Chronicle API and create service account credentials in Google Cloud Console.

1.1 Access Google Cloud Console​

  1. Navigate to Google Cloud Console
  2. Select your project or create a new one
  3. Ensure billing is enabled for your project
  4. Important: Chronicle Security Operations requires a separate subscription and API access approval from Google

1.2 Contact Google Security Operations​

  1. Contact your Google Security Operations representative
  2. Request API access for Chronicle API (v1)
  3. Obtain approval for service account credentials
  4. Get your Chronicle instance ID and region information
  5. Note: Chronicle API access is typically restricted and requires business justification

1.3 Enable Chronicle API​

  1. Go to APIs & Services → Library
  2. Search for "Chronicle API" or "Google Security Operations API"
  3. If available, click Enable
  4. Note: The API may not appear in the library if not yet approved for your organization

1.4 Create Service Account​

  1. Navigate to IAM & Admin → Service Accounts
  2. Click + CREATE SERVICE ACCOUNT
  3. Fill in the service account details:
    • Service account name: "AI Gateway Chronicle Integration"
    • Service account ID: Auto-generated (e.g., ai-gateway-chronicle)
    • Description: "Service account for Chronicle API (v1) integration"
  4. Click CREATE AND CONTINUE

1.5 Grant Required IAM Roles​

  1. Grant the following roles to the service account:
    • Service Account Token Creator (roles/iam.serviceAccountTokenCreator)
    • Service Account User (roles/iam.serviceAccountUser)
  2. Click CONTINUE
  3. Skip optional user access (not needed for service account authentication)
  4. Click DONE

1.6 Create Service Account Key​

  1. Click on the created service account
  2. Go to KEYS tab
  3. Click ADD KEY → Create new key
  4. Select JSON format
  5. Click CREATE
  6. Important: Save the downloaded JSON key file securely
  7. Note the Service Account Email (e.g., ai-gateway-chronicle@project-id.iam.gserviceaccount.com)

1.7 Configure Chronicle API Access​

  1. Contact your Google Security Operations representative
  2. Provide the service account email
  3. Request API access with the following scope:
    • https://www.googleapis.com/auth/cloud-platform
  4. Provide your Chronicle instance ID and region
  5. Wait for access approval (may take 1-3 business days)

Step 2-4: Standard Setup​

Follow standard steps to access AI Gateway, find Google Chronicle API, and create MCP server.

Step 5: Configure API Endpoints​

  1. Base URL: Select your regional endpoint (see Regional Endpoints section below)

    • Example: https://chronicle.us.rep.googleapis.com (for US region)
    • Example: https://chronicle.eu.rep.googleapis.com (for Europe region)

  2. Regional Endpoint Selection:

    • Determine your Chronicle instance region
    • Use the corresponding endpoint from the table below
    • The endpoint format is: https://chronicle.{location}.rep.googleapis.com

  3. Select endpoints to expose:

    • Instance Management endpoints (/v1/projects/{project}/locations/{location}/instances/{instance})
    • Rules endpoints (/v1/projects/{project}/locations/{location}/instances/{instance}/rules)
    • Rule Deployments endpoints (/v1/projects/{project}/locations/{location}/instances/{instance}/rules/deployments)
    • Retrohunts endpoints (/v1/projects/{project}/locations/{location}/instances/{instance}/rules/{rule}/retrohunts)
    • Reference Lists endpoints (/v1/projects/{project}/locations/{location}/instances/{instance}/referenceLists)
    • Watchlists endpoints (/v1/projects/{project}/locations/{location}/instances/{instance}/watchlists)
    • Data Access Labels endpoints (/v1/projects/{project}/locations/{location}/instances/{instance}/dataAccessLabels)
    • Data Access Scopes endpoints (/v1/projects/{project}/locations/{location}/instances/{instance}/dataAccessScopes)
    • Operations endpoints (/v1/projects/{project}/locations/{location}/instances/{instance}/operations)

  4. Click Next

Available Regional Endpoints​

RegionEndpoint PatternExample
United Stateshttps://chronicle.us.rep.googleapis.comhttps://chronicle.us.rep.googleapis.com
Europehttps://chronicle.eu.rep.googleapis.comhttps://chronicle.eu.rep.googleapis.com
Africa Southhttps://chronicle.africa-south1.rep.googleapis.comhttps://chronicle.africa-south1.rep.googleapis.com
Asia Northeasthttps://chronicle.asia-northeast1.rep.googleapis.comhttps://chronicle.asia-northeast1.rep.googleapis.com
Asia Southhttps://chronicle.asia-south1.rep.googleapis.comhttps://chronicle.asia-south1.rep.googleapis.com
Asia Southeast 1https://chronicle.asia-southeast1.rep.googleapis.comhttps://chronicle.asia-southeast1.rep.googleapis.com
Asia Southeast 2https://chronicle.asia-southeast2.rep.googleapis.comhttps://chronicle.asia-southeast2.rep.googleapis.com
Australia Southeasthttps://chronicle.australia-southeast1.rep.googleapis.comhttps://chronicle.australia-southeast1.rep.googleapis.com
Europe Central 2https://chronicle.europe-central2.rep.googleapis.comhttps://chronicle.europe-central2.rep.googleapis.com
Europe West 12https://chronicle.europe-west12.rep.googleapis.comhttps://chronicle.europe-west12.rep.googleapis.com
Europe West 2https://chronicle.europe-west2.rep.googleapis.comhttps://chronicle.europe-west2.rep.googleapis.com
Europe West 3https://chronicle.europe-west3.rep.googleapis.comhttps://chronicle.europe-west3.rep.googleapis.com
Europe West 6https://chronicle.europe-west6.rep.googleapis.comhttps://chronicle.europe-west6.rep.googleapis.com
Europe West 9https://chronicle.europe-west9.rep.googleapis.comhttps://chronicle.europe-west9.rep.googleapis.com
Middle East Central 1https://chronicle.me-central1.rep.googleapis.comhttps://chronicle.me-central1.rep.googleapis.com
Middle East Central 2https://chronicle.me-central2.rep.googleapis.comhttps://chronicle.me-central2.rep.googleapis.com
Middle East Westhttps://chronicle.me-west1.rep.googleapis.comhttps://chronicle.me-west1.rep.googleapis.com
North America Northeasthttps://chronicle.northamerica-northeast2.rep.googleapis.comhttps://chronicle.northamerica-northeast2.rep.googleapis.com
South America Easthttps://chronicle.southamerica-east1.rep.googleapis.comhttps://chronicle.southamerica-east1.rep.googleapis.com

Step 6: MCP Server Configuration​

  1. Name: "Google Chronicle API"
  2. Description: "SIEM and threat detection platform (Chronicle API v1)"
  3. Configure production mode
  4. Click Next

Step 7: Configure Authentication​

  1. Authentication Type: OAuth 2.0 with Service Account
  2. Service Account Key: Upload the JSON key file downloaded from Google Cloud Console
  3. Authorization URL: 
    https://accounts.google.com/o/oauth2/v2/auth
  4. Token URL: 
    https://oauth2.googleapis.com/token
  5. Scopes: Configure required scope (see Available Scopes section below)
  6. Click Next

Available Google Chronicle OAuth Scopes​

Configure the appropriate scope based on your application needs:

Full Access​

  • https://www.googleapis.com/auth/cloud-platform
    • Full access to Google Cloud resources, including Chronicle API
    • Read and write access to all Chronicle resources
    • Manage instances, rules, deployments, retrohunts, watchlists, reference lists
    • Manage data access labels and scopes
    • Monitor and manage operations
    • Required for: Full Chronicle API integration
    • Recommended for: All Chronicle API use cases

For Full Chronicle API Integration:

https://www.googleapis.com/auth/cloud-platform

Note: Chronicle API (v1) uses the standard Google Cloud Platform scope, unlike the legacy Backstory API which uses Chronicle-specific scopes.

Required IAM Roles and Permissions​

Service Account Roles​

  • Service Account Token Creator (roles/iam.serviceAccountTokenCreator): Allows the service account to create OAuth tokens
  • Service Account User (roles/iam.serviceAccountUser): Allows using the service account for authentication

Chronicle-Specific Permissions​

Chronicle API uses Google Cloud IAM for access control. The service account needs appropriate permissions within your Chronicle instance:

  1. Instance Permissions:

    • View instance details
    • Access instance resources

  2. Rules Permissions:

    • Create, read, update, delete detection rules
    • View rule revisions
    • Deploy and undeploy rules

  3. Retrohunts Permissions:

    • Create and manage retrohunts
    • View retrohunt results

  4. Reference Lists Permissions:

    • Create, read, update, delete reference lists
    • Manage threat intelligence indicators

  5. Watchlists Permissions:

    • Create, read, update, delete watchlists
    • Manage watchlist entities

  6. Data Access Labels/Scopes Permissions:

    • Create and manage data access labels
    • Create and manage data access scopes
    • Associate labels with scopes

Note: These permissions are configured within Chronicle Security Operations. Contact your Chronicle administrator to assign appropriate permissions to your service account.

Step 8: Test Connection​

  1. Click Test Connection
  2. Verify authentication succeeds
  3. Test a sample API call (e.g., get instance details or list reference lists)
  4. Ensure you're using the correct regional endpoint
  5. Verify project ID, location, and instance ID are correct
  6. If successful, click Create MCP Server

Using Your Google Chronicle API MCP Server​

Setup Instructions:

Natural Language Commands​

  • "Get details for Chronicle instance my-instance"
  • "Create a YARA-L detection rule for suspicious PowerShell execution"
  • "Deploy the suspicious PowerShell rule to production"
  • "Run a retrohunt for the suspicious PowerShell rule over the last 30 days"
  • "Create a reference list of known malware SHA256 hashes"
  • "Add compromised hosts to the high-risk watchlist"
  • "List all deployed rules and their status"
  • "Check retrohunt progress for rule suspicious-powershell"
  • "Create a data access label for PII data"
  • "Monitor all long-running operations"

Common Use Cases​

Security Operations​

  • Threat detection rule management and deployment
  • Real-time security monitoring and alerting
  • Incident investigation and response
  • Threat intelligence management

Threat Hunting​

  • Historical threat pattern analysis with retrohunts
  • Custom YARA-L rule development
  • IOC management and tracking
  • Watchlist monitoring

Compliance & Reporting​

  • Security data access control
  • Audit trail maintenance
  • Compliance reporting
  • Data classification and labeling

Resource Management​

  • Multi-tenant instance management
  • Rule versioning and deployment control
  • Reference list maintenance
  • Watchlist updates

Troubleshooting​

Authentication Errors​

Error: "Permission denied" or "UNAUTHENTICATED"

  • Verify service account key file is correct
  • Ensure service account has been granted Chronicle API access
  • Check that Chronicle API is enabled in your Google Cloud project
  • Verify service account email matches the one approved by Google Security Operations
  • Ensure you're using the cloud-platform scope (not Chronicle-specific scopes)

Error: "API not enabled"

  • Contact Google Security Operations to enable Chronicle API access
  • Chronicle API may require separate subscription activation
  • Verify your organization has Chronicle Security Operations subscription

Regional Endpoint Issues​

Error: "Not Found" or connection timeout

  • Verify you're using the correct regional endpoint for your Chronicle instance
  • Check that your region identifier matches one of the supported regions
  • Ensure network connectivity to the regional endpoint
  • Contact support to confirm your instance region

Error: "Invalid location" or "Invalid instance"

  • Verify the location parameter matches your Chronicle instance location (e.g., us-central1)
  • Check that the instance ID is correct
  • Ensure project ID matches your GCP project
  • Verify all path parameters are correctly formatted

API Access Issues​

Error: "Access denied" or "FORBIDDEN"

  • Verify service account has appropriate Chronicle permissions
  • Check IAM roles assigned to service account in Google Cloud Console
  • Ensure required scope (cloud-platform) is included in OAuth configuration
  • Contact Chronicle administrator to verify permissions

Error: "Rate limit exceeded"

  • Chronicle API has rate limits that vary by customer tier
  • Implement exponential backoff for retries
  • Consider batching requests where possible
  • Contact Google Support to request rate limit increase if needed

Service Account Setup​

Cannot create service account key

  • Verify you have "Service Account Key Admin" role (roles/iam.serviceAccountKeyAdmin)
  • Ensure service account exists and is accessible
  • Check project permissions

Service account key not working

  • Verify JSON key file is valid
  • Check key hasn't been rotated or deleted
  • Ensure service account hasn't been disabled
  • Regenerate key if necessary

Best Practices​

Security​

  • Secure Key Storage: Store service account keys securely, never commit to version control
  • Key Rotation: Rotate service account keys regularly (every 90 days recommended)
  • Least Privilege: Grant only necessary Chronicle permissions to service account
  • Audit Logging: Enable audit logs for Chronicle API access
  • Network Security: Use VPC Service Controls if available
  • Regional Endpoints: Use the regional endpoint closest to your infrastructure for better performance

Performance​

  • Rate Limiting: Implement proper rate limiting and retry logic
  • Caching: Cache reference lists and watchlists when appropriate
  • Pagination: Use pagination for large result sets
  • Query Optimization: Optimize YARA-L rules for performance
  • Regional Selection: Choose the regional endpoint closest to your data center

Monitoring​

  • API Usage: Monitor API usage and costs
  • Error Tracking: Track and alert on authentication failures
  • Performance Metrics: Monitor API response times
  • Quota Management: Track API quota usage
  • Operation Status: Monitor long-running operations (retrohunts, exports)

Resource Management​

  • Instance Isolation: Use separate instances for different environments
  • Rule Versioning: Use rule revisions to track changes
  • Deployment Management: Test rules before deploying to production
  • Watchlist Maintenance: Regularly update watchlists with current threat intelligence
  • Reference List Updates: Keep reference lists current with latest IOCs

Additional Resources​

Support​

For issues specific to Chronicle Security Operations:

For AI Gateway integration issues: