airbyte_ops_mcp.mcp.gcp_logs
MCP tools for GCP Cloud Logging operations.
This module provides MCP tools for querying GCP Cloud Logging, particularly for looking up error details by error ID.
MCP reference
MCP primitives registered by the gcp_logs module of the airbyte-internal-ops server: 1 tool(s), 0 prompt(s), 0 resource(s).
Tools (1)
lookup_cloud_backend_error
Hints: read-only · idempotent
Look up error details from GCP Cloud Logging by error ID.
When an Airbyte Cloud API returns an error response with only an error ID (e.g., {"errorId": "3173452e-8f22-4286-a1ec-b0f16c1e078a"}), this tool fetches the full stack trace and error details from GCP Cloud Logging.
The tool searches for log entries containing the error ID and fetches related entries (multi-line stack traces) from the same timestamp and pod.
Requires GCP credentials with Logs Viewer role on the target project.
Parameters:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
error_id |
string |
yes | — | The error ID (UUID) to search for. This is typically returned in API error responses as {'errorId': '...'} |
project |
string |
no | "prod-ab-cloud-proj" |
GCP project ID to search in. Defaults to 'prod-ab-cloud-proj' (Airbyte Cloud production). |
lookback_days |
integer |
no | 7 |
Number of days to look back in logs. Defaults to 7. |
min_severity_filter |
enum("DEBUG", "INFO", "NOTICE", "WARNING", "ERROR", "CRITICAL", "ALERT", "EMERGENCY") | null |
no | null |
Optional minimum severity level to filter logs. |
max_log_entries |
integer |
no | 200 |
Maximum number of log entries to return. Defaults to 200. |
Show input JSON schema
{
"additionalProperties": false,
"properties": {
"error_id": {
"description": "The error ID (UUID) to search for. This is typically returned in API error responses as {'errorId': '...'}",
"type": "string"
},
"project": {
"default": "prod-ab-cloud-proj",
"description": "GCP project ID to search in. Defaults to 'prod-ab-cloud-proj' (Airbyte Cloud production).",
"type": "string"
},
"lookback_days": {
"default": 7,
"description": "Number of days to look back in logs. Defaults to 7.",
"type": "integer"
},
"min_severity_filter": {
"anyOf": [
{
"description": "Valid GCP Cloud Logging severity levels.",
"enum": [
"DEBUG",
"INFO",
"NOTICE",
"WARNING",
"ERROR",
"CRITICAL",
"ALERT",
"EMERGENCY"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional minimum severity level to filter logs."
},
"max_log_entries": {
"default": 200,
"description": "Maximum number of log entries to return. Defaults to 200.",
"type": "integer"
}
},
"required": [
"error_id"
],
"type": "object"
}
Show output JSON schema
{
"description": "Result of searching GCP Cloud Logging for an error ID.",
"properties": {
"error_id": {
"description": "The error ID that was searched for",
"type": "string"
},
"project": {
"description": "GCP project that was searched",
"type": "string"
},
"lookback_days_searched": {
"description": "Number of lookback days that were searched",
"type": "integer"
},
"total_entries_found": {
"description": "Total number of log entries found (including related entries)",
"type": "integer"
},
"entries": {
"description": "Raw log entries found",
"items": {
"description": "A single log entry from GCP Cloud Logging.",
"properties": {
"timestamp": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "When the log entry was created"
},
"severity": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Log severity (DEBUG, INFO, WARNING, ERROR, etc.)"
},
"log_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Full log name path"
},
"insert_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Unique identifier for the log entry"
},
"trace": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Trace ID for distributed tracing"
},
"span_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Span ID within the trace"
},
"payload": {
"default": null,
"description": "Log entry payload (text or struct)",
"title": "Payload"
},
"payload_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Type of payload (text, struct, protobuf)"
},
"resource": {
"description": "Resource information",
"properties": {
"type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Resource type"
},
"labels": {
"description": "Resource labels",
"properties": {
"pod_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Kubernetes pod name"
},
"container_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Container name within the pod"
},
"namespace_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Kubernetes namespace"
},
"cluster_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "GKE cluster name"
}
},
"type": "object"
}
},
"type": "object"
},
"source_location": {
"anyOf": [
{
"description": "Source location information from a GCP log entry.",
"properties": {
"file": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source file path"
},
"line": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Line number"
},
"function": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Function name"
}
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Source code location"
},
"labels": {
"additionalProperties": {
"type": "string"
},
"description": "User-defined labels",
"type": "object"
}
},
"type": "object"
},
"type": "array"
},
"payloads": {
"description": "Extracted and grouped payloads (reconstructed stack traces)",
"items": {
"description": "Extracted and combined payload from grouped log entries.",
"properties": {
"timestamp": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Timestamp of the first entry in the group"
},
"severity": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Severity of the log group"
},
"resource": {
"description": "Resource information",
"properties": {
"type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Resource type"
},
"labels": {
"description": "Resource labels",
"properties": {
"pod_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Kubernetes pod name"
},
"container_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Container name within the pod"
},
"namespace_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Kubernetes namespace"
},
"cluster_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "GKE cluster name"
}
},
"type": "object"
}
},
"type": "object"
},
"num_log_lines": {
"default": 0,
"description": "Number of log lines combined into this payload",
"type": "integer"
},
"message": {
"default": "",
"description": "Combined message from all log lines",
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"required": [
"error_id",
"project",
"lookback_days_searched",
"total_entries_found"
],
"type": "object"
}
1# Copyright (c) 2025 Airbyte, Inc., all rights reserved. 2"""MCP tools for GCP Cloud Logging operations. 3 4This module provides MCP tools for querying GCP Cloud Logging, 5particularly for looking up error details by error ID. 6 7## MCP reference 8 9.. include:: ../../../docs/mcp-generated/gcp_logs.md 10 :start-line: 2 11""" 12 13from __future__ import annotations 14 15__all__: list[str] = [] 16 17from typing import Annotated 18 19from fastmcp import FastMCP 20from fastmcp_extensions import mcp_tool, register_mcp_tools 21from pydantic import Field 22 23from airbyte_ops_mcp.gcp_logs import ( 24 GCPLogSearchResult, 25 GCPSeverity, 26 fetch_error_logs, 27) 28from airbyte_ops_mcp.gcp_logs.error_lookup import DEFAULT_GCP_PROJECT 29 30 31@mcp_tool( 32 read_only=True, 33 idempotent=True, 34) 35def lookup_cloud_backend_error( 36 error_id: Annotated[ 37 str, 38 Field( 39 description=( 40 "The error ID (UUID) to search for. This is typically returned " 41 "in API error responses as {'errorId': '...'}" 42 ) 43 ), 44 ], 45 project: Annotated[ 46 str, 47 Field( 48 default=DEFAULT_GCP_PROJECT, 49 description=( 50 "GCP project ID to search in. Defaults to 'prod-ab-cloud-proj' " 51 "(Airbyte Cloud production)." 52 ), 53 ), 54 ], 55 lookback_days: Annotated[ 56 int, 57 Field( 58 default=7, 59 description="Number of days to look back in logs. Defaults to 7.", 60 ), 61 ], 62 min_severity_filter: Annotated[ 63 GCPSeverity | None, 64 Field( 65 default=None, 66 description="Optional minimum severity level to filter logs.", 67 ), 68 ], 69 max_log_entries: Annotated[ 70 int, 71 Field( 72 default=200, 73 description="Maximum number of log entries to return. Defaults to 200.", 74 ), 75 ], 76) -> GCPLogSearchResult: 77 """Look up error details from GCP Cloud Logging by error ID. 78 79 When an Airbyte Cloud API returns an error response with only an error ID 80 (e.g., {"errorId": "3173452e-8f22-4286-a1ec-b0f16c1e078a"}), this tool 81 fetches the full stack trace and error details from GCP Cloud Logging. 82 83 The tool searches for log entries containing the error ID and fetches 84 related entries (multi-line stack traces) from the same timestamp and pod. 85 86 Requires GCP credentials with Logs Viewer role on the target project. 87 """ 88 return fetch_error_logs( 89 error_id=error_id, 90 project=project, 91 lookback_days=lookback_days, 92 min_severity_filter=min_severity_filter, 93 max_log_entries=max_log_entries, 94 ) 95 96 97def register_gcp_logs_tools(app: FastMCP) -> None: 98 """Register GCP logs tools with the FastMCP app.""" 99 register_mcp_tools(app)