airbyte_ops_mcp.mcp.prod_db_ops

MCP tools for querying the Airbyte Cloud Prod DB Replica.

This module provides MCP tools that wrap the query functions from airbyte_ops_mcp.prod_db_access.queries for use by AI agents.

MCP reference

MCP primitives registered by the prod_db_ops module of the airbyte-internal-ops server: 21 tool(s), 0 prompt(s), 0 resource(s).

Tools (21)

query_connector_pin_stats

Query connector versions that have at least one scoped configuration pin.

Returns versions from the prod DB that are referenced by at least one scoped_configuration pin (key = 'connector_version'). Each version appears exactly once with per-scope pin breakdown (actor, workspace, org).

If neither filter is provided, returns the global superset across all connectors.

Parameters:

Name Type Required Default Description
connector_definition_id string | null no null Connector definition UUID to filter by (optional). Mutually exclusive with connector_canonical_name.
connector_canonical_name string | null no null Connector canonical name (e.g. source-postgres) to filter by. Resolved to a definition ID via the registry. Mutually exclusive with connector_definition_id.

Show input JSON schema

{
  "additionalProperties": false,
  "properties": {
    "connector_definition_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Connector definition UUID to filter by (optional). Mutually exclusive with `connector_canonical_name`."
    },
    "connector_canonical_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Connector canonical name (e.g. `source-postgres`) to filter by. Resolved to a definition ID via the registry. Mutually exclusive with `connector_definition_id`."
    }
  },
  "type": "object"
}

Show output JSON schema

{
  "properties": {
    "result": {
      "items": {
        "description": "A connector version that has at least one scoped configuration pin.",
        "properties": {
          "version_id": {
            "description": "The actor_definition_version UUID",
            "type": "string"
          },
          "connector_definition_id": {
            "description": "The connector definition UUID",
            "type": "string"
          },
          "connector_name": {
            "description": "Human-readable connector name",
            "type": "string"
          },
          "docker_repository": {
            "description": "Docker repository path",
            "type": "string"
          },
          "docker_image_tag": {
            "description": "Docker image tag for this version",
            "type": "string"
          },
          "last_published": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "ISO timestamp when this version was last published"
          },
          "pin_count": {
            "description": "Total number of scoped_configuration rows pinning to this version",
            "type": "integer"
          },
          "breaking_change_pins": {
            "default": 0,
            "description": "Number of actor-scoped pins created by breaking changes",
            "type": "integer"
          },
          "rollout_pins": {
            "default": 0,
            "description": "Number of pins created by connector rollouts",
            "type": "integer"
          },
          "actor_pins": {
            "description": "Number of actor-scoped pins (excludes breaking change and rollout pins)",
            "type": "integer"
          },
          "workspace_pins": {
            "description": "Number of workspace-scoped pins",
            "type": "integer"
          },
          "org_pins": {
            "description": "Number of organization-scoped pins",
            "type": "integer"
          }
        },
        "required": [
          "version_id",
          "connector_definition_id",
          "connector_name",
          "docker_repository",
          "docker_image_tag",
          "pin_count",
          "actor_pins",
          "workspace_pins",
          "org_pins"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "type": "object",
  "x-fastmcp-wrap-result": true
}

query_connector_population_summary

Summarize the applied vs potential pinning audience for a connector, by tier.

Answers "how many actors are pinned and how many are eligible for pinning, split by tier" — the population view analogous to a rollout's audience.

  • active: the potential audience — non-tombstoned actors of the definition that have at least one active connection (connection.status = 'active'). Inactive/disabled and deprecated connections are excluded, so this reflects the enabled, rollout-touchable population rather than every actor ever created.
  • pinned_any: active actors that already have an effective connector_version pin at any scope (actor/workspace/org).
  • eligible: active minus pinned_any — actors available to pin.
  • pinned_to_version: the applied audience for the requested version (only when a version identifier was provided).

Backed by scoped_configuration + actor/connection tables, so it is cheap to compute. Accepts a version identifier (preferred, adds pinned_to_version) or a definition-level identifier.

Parameters:

Name Type Required Default Description
connector_version_id string | null no null Connector version UUID. When provided, the applied audience (pinned_to_version) is included. Provide this OR connector_name + connector_version OR a definition-level identifier.
connector_name string | null no null Canonical connector name (e.g. source-postgres). Used with connector_version to resolve the version UUID.
connector_version string | null no null Semver version tag (e.g. 0.3.59). Used with connector_name.
connector_definition_id string | null no null Connector definition UUID for a definition-level summary (no pinned_to_version breakdown).
connector_canonical_name string | null no null Canonical connector name resolved to a definition ID via the registry, for a definition-level summary.
customer_tier_filter enum("TIER_0", "TIER_1", "TIER_2", "UNKNOWN", "ALL") no "TIER_2" Which customer tiers to count. Defaults to TIER_2; pass ALL to include TIER_0/TIER_1 (revenue-critical) customers.

Show input JSON schema

{
  "additionalProperties": false,
  "properties": {
    "connector_version_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Connector version UUID. When provided, the applied audience (`pinned_to_version`) is included. Provide this OR `connector_name` + `connector_version` OR a definition-level identifier."
    },
    "connector_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Canonical connector name (e.g. `source-postgres`). Used with `connector_version` to resolve the version UUID."
    },
    "connector_version": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Semver version tag (e.g. `0.3.59`). Used with `connector_name`."
    },
    "connector_definition_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Connector definition UUID for a definition-level summary (no `pinned_to_version` breakdown)."
    },
    "connector_canonical_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Canonical connector name resolved to a definition ID via the registry, for a definition-level summary."
    },
    "customer_tier_filter": {
      "default": "TIER_2",
      "description": "Which customer tiers to count. Defaults to `TIER_2`; pass `ALL` to include TIER_0/TIER_1 (revenue-critical) customers.",
      "enum": [
        "TIER_0",
        "TIER_1",
        "TIER_2",
        "UNKNOWN",
        "ALL"
      ],
      "type": "string"
    }
  },
  "type": "object"
}

Show output JSON schema

{
  "description": "Applied vs potential pinning audience for a connector, split by tier.",
  "properties": {
    "connector_definition_id": {
      "description": "The connector definition UUID",
      "type": "string"
    },
    "connector_version_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The version UUID, when a specific version was requested"
    },
    "docker_repository": {
      "description": "Docker repository path",
      "type": "string"
    },
    "docker_image_tag": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Docker image tag, when a version was requested"
    },
    "customer_tier_filter": {
      "description": "Tier filter applied to the counts (`TIER_0`/`TIER_1`/`TIER_2`/`UNKNOWN`/`ALL`)",
      "type": "string"
    },
    "active": {
      "description": "Potential audience: enabled actors of the definition (those with at least one active connection, `status = 'active'`), by tier",
      "properties": {
        "tier_0_count": {
          "default": 0,
          "description": "Number of TIER_0 entries",
          "type": "integer"
        },
        "tier_1_count": {
          "default": 0,
          "description": "Number of TIER_1 entries",
          "type": "integer"
        },
        "tier_2_count": {
          "default": 0,
          "description": "Number of TIER_2 entries",
          "type": "integer"
        },
        "unknown_count": {
          "default": 0,
          "description": "Number of UNKNOWN entries",
          "type": "integer"
        },
        "total": {
          "default": 0,
          "description": "Total number of entries",
          "type": "integer"
        },
        "warnings": {
          "description": "Warnings raised while building this summary.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "type": "object"
    },
    "pinned_any": {
      "description": "Active actors already pinned to any version, by tier",
      "properties": {
        "tier_0_count": {
          "default": 0,
          "description": "Number of TIER_0 entries",
          "type": "integer"
        },
        "tier_1_count": {
          "default": 0,
          "description": "Number of TIER_1 entries",
          "type": "integer"
        },
        "tier_2_count": {
          "default": 0,
          "description": "Number of TIER_2 entries",
          "type": "integer"
        },
        "unknown_count": {
          "default": 0,
          "description": "Number of UNKNOWN entries",
          "type": "integer"
        },
        "total": {
          "default": 0,
          "description": "Total number of entries",
          "type": "integer"
        },
        "warnings": {
          "description": "Warnings raised while building this summary.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "type": "object"
    },
    "eligible": {
      "description": "Active actors not pinned to any version (available to pin), by tier",
      "properties": {
        "tier_0_count": {
          "default": 0,
          "description": "Number of TIER_0 entries",
          "type": "integer"
        },
        "tier_1_count": {
          "default": 0,
          "description": "Number of TIER_1 entries",
          "type": "integer"
        },
        "tier_2_count": {
          "default": 0,
          "description": "Number of TIER_2 entries",
          "type": "integer"
        },
        "unknown_count": {
          "default": 0,
          "description": "Number of UNKNOWN entries",
          "type": "integer"
        },
        "total": {
          "default": 0,
          "description": "Total number of entries",
          "type": "integer"
        },
        "warnings": {
          "description": "Warnings raised while building this summary.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "type": "object"
    },
    "pinned_to_version": {
      "anyOf": [
        {
          "description": "Summary of tier distribution across a set of results.",
          "properties": {
            "tier_0_count": {
              "default": 0,
              "description": "Number of TIER_0 entries",
              "type": "integer"
            },
            "tier_1_count": {
              "default": 0,
              "description": "Number of TIER_1 entries",
              "type": "integer"
            },
            "tier_2_count": {
              "default": 0,
              "description": "Number of TIER_2 entries",
              "type": "integer"
            },
            "unknown_count": {
              "default": 0,
              "description": "Number of UNKNOWN entries",
              "type": "integer"
            },
            "total": {
              "default": 0,
              "description": "Total number of entries",
              "type": "integer"
            },
            "warnings": {
              "description": "Warnings raised while building this summary.",
              "items": {
                "type": "string"
              },
              "type": "array"
            }
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Applied audience: actors pinned to the requested version, by tier. `None` when no specific version was requested."
    }
  },
  "required": [
    "connector_definition_id",
    "docker_repository",
    "customer_tier_filter",
    "active",
    "pinned_any",
    "eligible"
  ],
  "type": "object"
}

query_connector_version_health_summary

Summarize actor health for a connector version into four buckets.

Answers "how many actors on a version are healthy / unhealthy / awaiting / disabled". Classification per actor over the lookback window:

  • healthy: at least one successful sync (the same success signal the autopilot health gate uses).
  • unhealthy: failures and no successes.
  • awaiting: ran but produced only non-terminal jobs (no result yet).
  • disabled: (when include_pinned_disabled) pinned to the version with no jobs at all in the window — the dormant/inactive audience.

Built on the attempt/version primitive — the version stamped into jobs.config at job-creation time — not the current pin state, so it reflects actors that actually ran this version. This scans jobs over the window and is more expensive than the population summary; keep days bounded and query per-version.

Parameters:

Name Type Required Default Description
connector_version_id string | null no null Connector version UUID. Provide this OR connector_name + connector_version.
connector_name string | null no null Canonical connector name (e.g. source-postgres). Used with connector_version to resolve the version UUID.
connector_version string | null no null Semver version tag (e.g. 0.3.59). Used with connector_name.
days integer no 7 Number of days to look back (default: 7, max: 30)
include_pinned_disabled boolean no true If True (default), actors pinned to the version that ran no jobs in the window are counted as disabled.
customer_tier_filter enum("TIER_0", "TIER_1", "TIER_2", "UNKNOWN", "ALL") no "TIER_2" Which customer tiers to count. Defaults to TIER_2; pass ALL to include TIER_0/TIER_1 (revenue-critical) customers.

Show input JSON schema

{
  "additionalProperties": false,
  "properties": {
    "connector_version_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Connector version UUID. Provide this OR `connector_name` + `connector_version`."
    },
    "connector_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Canonical connector name (e.g. `source-postgres`). Used with `connector_version` to resolve the version UUID."
    },
    "connector_version": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Semver version tag (e.g. `0.3.59`). Used with `connector_name`."
    },
    "days": {
      "default": 7,
      "description": "Number of days to look back (default: 7, max: 30)",
      "maximum": 30,
      "minimum": 1,
      "type": "integer"
    },
    "include_pinned_disabled": {
      "default": true,
      "description": "If `True` (default), actors pinned to the version that ran no jobs in the window are counted as `disabled`.",
      "type": "boolean"
    },
    "customer_tier_filter": {
      "default": "TIER_2",
      "description": "Which customer tiers to count. Defaults to `TIER_2`; pass `ALL` to include TIER_0/TIER_1 (revenue-critical) customers.",
      "enum": [
        "TIER_0",
        "TIER_1",
        "TIER_2",
        "UNKNOWN",
        "ALL"
      ],
      "type": "string"
    }
  },
  "type": "object"
}

Show output JSON schema

{
  "description": "Four-bucket health rollup for the actors running a connector version.",
  "properties": {
    "connector_version_id": {
      "description": "The connector version UUID",
      "type": "string"
    },
    "connector_definition_id": {
      "description": "The connector definition UUID",
      "type": "string"
    },
    "docker_repository": {
      "description": "Docker repository path",
      "type": "string"
    },
    "docker_image_tag": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Docker image tag for this version"
    },
    "days": {
      "description": "Lookback window in days",
      "type": "integer"
    },
    "customer_tier_filter": {
      "description": "Tier filter applied to the counts (`TIER_0`/`TIER_1`/`TIER_2`/`UNKNOWN`/`ALL`)",
      "type": "string"
    },
    "healthy": {
      "description": "Actors with at least one successful sync",
      "type": "integer"
    },
    "unhealthy": {
      "description": "Actors with failures and no successes in the window",
      "type": "integer"
    },
    "awaiting": {
      "description": "Actors that ran but produced only non-terminal jobs (no result yet)",
      "type": "integer"
    },
    "disabled": {
      "description": "Actors pinned to the version that produced no jobs in the window \u2014 the dormant/inactive audience",
      "type": "integer"
    },
    "total_actors": {
      "description": "Total actors counted across all states",
      "type": "integer"
    },
    "healthy_by_tier": {
      "description": "Healthy actors by tier",
      "properties": {
        "tier_0_count": {
          "default": 0,
          "description": "Number of TIER_0 entries",
          "type": "integer"
        },
        "tier_1_count": {
          "default": 0,
          "description": "Number of TIER_1 entries",
          "type": "integer"
        },
        "tier_2_count": {
          "default": 0,
          "description": "Number of TIER_2 entries",
          "type": "integer"
        },
        "unknown_count": {
          "default": 0,
          "description": "Number of UNKNOWN entries",
          "type": "integer"
        },
        "total": {
          "default": 0,
          "description": "Total number of entries",
          "type": "integer"
        },
        "warnings": {
          "description": "Warnings raised while building this summary.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "type": "object"
    },
    "unhealthy_by_tier": {
      "description": "Unhealthy actors by tier",
      "properties": {
        "tier_0_count": {
          "default": 0,
          "description": "Number of TIER_0 entries",
          "type": "integer"
        },
        "tier_1_count": {
          "default": 0,
          "description": "Number of TIER_1 entries",
          "type": "integer"
        },
        "tier_2_count": {
          "default": 0,
          "description": "Number of TIER_2 entries",
          "type": "integer"
        },
        "unknown_count": {
          "default": 0,
          "description": "Number of UNKNOWN entries",
          "type": "integer"
        },
        "total": {
          "default": 0,
          "description": "Total number of entries",
          "type": "integer"
        },
        "warnings": {
          "description": "Warnings raised while building this summary.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "type": "object"
    },
    "awaiting_by_tier": {
      "description": "Awaiting-results actors by tier",
      "properties": {
        "tier_0_count": {
          "default": 0,
          "description": "Number of TIER_0 entries",
          "type": "integer"
        },
        "tier_1_count": {
          "default": 0,
          "description": "Number of TIER_1 entries",
          "type": "integer"
        },
        "tier_2_count": {
          "default": 0,
          "description": "Number of TIER_2 entries",
          "type": "integer"
        },
        "unknown_count": {
          "default": 0,
          "description": "Number of UNKNOWN entries",
          "type": "integer"
        },
        "total": {
          "default": 0,
          "description": "Total number of entries",
          "type": "integer"
        },
        "warnings": {
          "description": "Warnings raised while building this summary.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "type": "object"
    },
    "disabled_by_tier": {
      "description": "Disabled actors by tier",
      "properties": {
        "tier_0_count": {
          "default": 0,
          "description": "Number of TIER_0 entries",
          "type": "integer"
        },
        "tier_1_count": {
          "default": 0,
          "description": "Number of TIER_1 entries",
          "type": "integer"
        },
        "tier_2_count": {
          "default": 0,
          "description": "Number of TIER_2 entries",
          "type": "integer"
        },
        "unknown_count": {
          "default": 0,
          "description": "Number of UNKNOWN entries",
          "type": "integer"
        },
        "total": {
          "default": 0,
          "description": "Total number of entries",
          "type": "integer"
        },
        "warnings": {
          "description": "Warnings raised while building this summary.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "connector_version_id",
    "connector_definition_id",
    "docker_repository",
    "days",
    "customer_tier_filter",
    "healthy",
    "unhealthy",
    "awaiting",
    "disabled",
    "total_actors",
    "healthy_by_tier",
    "unhealthy_by_tier",
    "awaiting_by_tier",
    "disabled_by_tier"
  ],
  "type": "object"
}

query_prod_actors_by_pinned_connector_version

List actors (sources/destinations) effectively pinned to a specific connector version.

Returns all actors that are effectively pinned to a specific connector version, considering all scope levels: actor-level pins, workspace-level pins, and organization-level pins (with actor > workspace > organization precedence). Useful for monitoring rollouts and understanding which customers are affected.

The actor_id field is the actor ID (superset of source_id/destination_id).

Returns list of dicts with keys: actor_id, connector_definition_id, origin_type, origin, description, created_at, expires_at, pin_scope_type, actor_name, workspace_id, workspace_name, organization_id, dataplane_group_id, dataplane_name

pin_scope_type is 'actor', 'workspace', or 'organization' indicating which scope level the effective pin came from.

Parameters:

Name Type Required Default Description
connector_version_id string yes — Connector version UUID to find pinned instances for

Show input JSON schema

{
  "additionalProperties": false,
  "properties": {
    "connector_version_id": {
      "description": "Connector version UUID to find pinned instances for",
      "type": "string"
    }
  },
  "required": [
    "connector_version_id"
  ],
  "type": "object"
}

Show output JSON schema

{
  "properties": {
    "result": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "type": "object",
  "x-fastmcp-wrap-result": true
}

query_prod_connection_sync_activity

List recent sync jobs and attempts from the Prod DB Replica.

Returns one row per (job, attempt) pair for sync jobs whose updated_at falls in [start_at, end_at), scoped to the provided organization, workspace, or connection IDs. Designed for live operational lookups — e.g. "what happened on this connection in the last hour" — not for historical analysis.

Each row is enriched with customer_tier and is_eu for the owning organization. Tier filtering is intentionally not applied — this is a read-only observability query.

Input requirements:

  • At least one of organization_id, workspace_id, or connection_ids must be provided (any combination is accepted).
  • start_at and end_at must be timezone-aware and start_at < end_at.

Key fields in each row:

  • job_id, attempt_id, attempt_number
  • job_status, attempt_status
  • job_started_at, job_updated_at, attempt_ended_at
  • failure_summary (JSON; populated when an attempt failed)
  • connection_id, connection_name, connection_status
  • source_actor_id, source_actor_name, source_actor_definition_id
  • destination_actor_id, destination_actor_name, destination_actor_definition_id
  • workspace_id, workspace_name, organization_id
  • dataplane_group_id, dataplane_name
  • customer_tier, is_eu (added by tier enrichment)

Parameters:

Name Type Required Default Description
start_at string yes — Inclusive start timestamp for the sync activity window. Must be timezone-aware (ISO 8601 with offset or Z).
end_at string yes — Exclusive end timestamp for the sync activity window. Must be timezone-aware and strictly after start_at.
organization_id string | enum("664c690e-5263-49ba-b01f-4a6759b3330a") | null no null Optional organization UUID or alias. At least one of organization_id, workspace_id, or connection_ids is required. Accepts @airbyte-internal as an alias for the Airbyte internal org.
workspace_id string | enum("266ebdfe-0d7b-4540-9817-de7e4505ba61") | null no null Optional workspace UUID or alias. At least one of organization_id, workspace_id, or connection_ids is required. Accepts @devin-ai-sandbox as an alias for the Devin AI sandbox workspace.
connection_ids array<string> | null no null Optional list of connection UUIDs. At least one of organization_id, workspace_id, or connection_ids is required.
status_filter enum("all", "succeeded", "failed") no "all" Filter by job status: all (default), succeeded, or failed. Applied to jobs.status in the Prod DB Replica.
limit integer no 1000 Maximum number of attempt rows to return.

Show input JSON schema

{
  "additionalProperties": false,
  "properties": {
    "start_at": {
      "description": "Inclusive start timestamp for the sync activity window. Must be timezone-aware (ISO 8601 with offset or `Z`).",
      "format": "date-time",
      "type": "string"
    },
    "end_at": {
      "description": "Exclusive end timestamp for the sync activity window. Must be timezone-aware and strictly after `start_at`.",
      "format": "date-time",
      "type": "string"
    },
    "organization_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "description": "Organization ID aliases that can be used in place of UUIDs.\n\nEach member's name is the alias (e.g., \"@airbyte-internal\") and its value\nis the actual organization UUID. Use `OrganizationAliasEnum.resolve()` to\nresolve aliases to actual IDs.",
          "enum": [
            "664c690e-5263-49ba-b01f-4a6759b3330a"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional organization UUID or alias. At least one of `organization_id`, `workspace_id`, or `connection_ids` is required. Accepts `@airbyte-internal` as an alias for the Airbyte internal org."
    },
    "workspace_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "description": "Workspace ID aliases that can be used in place of UUIDs.\n\nEach member's name is the alias (e.g., \"@devin-ai-sandbox\") and its value\nis the actual workspace UUID. Use `WorkspaceAliasEnum.resolve()` to\nresolve aliases to actual IDs.",
          "enum": [
            "266ebdfe-0d7b-4540-9817-de7e4505ba61"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional workspace UUID or alias. At least one of `organization_id`, `workspace_id`, or `connection_ids` is required. Accepts `@devin-ai-sandbox` as an alias for the Devin AI sandbox workspace."
    },
    "connection_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional list of connection UUIDs. At least one of `organization_id`, `workspace_id`, or `connection_ids` is required."
    },
    "status_filter": {
      "description": "Filter by job status: `all` (default), `succeeded`, or `failed`. Applied to `jobs.status` in the Prod DB Replica.",
      "enum": [
        "all",
        "succeeded",
        "failed"
      ],
      "type": "string",
      "default": "all"
    },
    "limit": {
      "default": 1000,
      "description": "Maximum number of attempt rows to return.",
      "type": "integer"
    }
  },
  "required": [
    "start_at",
    "end_at"
  ],
  "type": "object"
}

Show output JSON schema

{
  "properties": {
    "result": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "type": "object",
  "x-fastmcp-wrap-result": true
}

query_prod_connections_by_connector

Search for all connections using a specific source or destination connector type.

This tool queries the Airbyte Cloud Prod DB Replica directly for fast results. It finds all connections where the source or destination connector matches the specified type, regardless of how the connector is named by users.

Results are always enriched with customer_tier and is_eu fields. The customer_tier_filter parameter is required to ensure tier-aware querying.

Optionally filter by organization_id to limit results to a specific organization. Use '@airbyte-internal' as an alias for the Airbyte internal organization.

Set exclude_pinned=True to filter out connections that are already pinned to a specific version. This is useful for 'prove fix' live connection testing workflows where you want to find unpinned connections to test against.

Set enabled_schedules_only=True to restrict results to connections that are both enabled (status='active') and on an automated schedule (not manual-trigger-only). This is useful for canary prerelease workflows where you need connections that will run organically during the monitoring window.

Returns a list of connection dicts with workspace context and clickable Cloud UI URLs. For source queries, returns: connection_id, connection_name, connection_url, source_id, source_name, source_definition_id, workspace_id, workspace_name, organization_id, dataplane_group_id, dataplane_name, pin_origin_type, pin_origin, pinned_version_id, pin_scope_type, customer_tier, is_eu. For destination queries, returns: connection_id, connection_name, connection_url, destination_id, destination_name, destination_definition_id, workspace_id, workspace_name, organization_id, dataplane_group_id, dataplane_name, pin_origin_type, pin_origin, pinned_version_id, pin_scope_type, customer_tier, is_eu.

pin_scope_type is 'actor', 'workspace', or 'organization' indicating which scope level the effective pin came from (NULL if not pinned).

Parameters:

Name Type Required Default Description
source_definition_id string | null no null Source connector definition ID (UUID) to search for. Exactly one of source_definition_id, source_canonical_name, destination_definition_id, or destination_canonical_name is required. Example: 'afa734e4-3571-11ec-991a-1e0031268139' for YouTube Analytics.
source_canonical_name string | null no null Canonical source connector name to search for. Exactly one of source_definition_id, source_canonical_name, destination_definition_id, or destination_canonical_name is required. Examples: 'source-youtube-analytics', 'YouTube Analytics'.
destination_definition_id string | null no null Destination connector definition ID (UUID) to search for. Exactly one of source_definition_id, source_canonical_name, destination_definition_id, or destination_canonical_name is required. Example: 'e5c8e66c-a480-4a5e-9c0e-e8e5e4c5c5c5' for DuckDB.
destination_canonical_name string | null no null Canonical destination connector name to search for. Exactly one of source_definition_id, source_canonical_name, destination_definition_id, or destination_canonical_name is required. Examples: 'destination-duckdb', 'DuckDB'.
organization_id string | enum("664c690e-5263-49ba-b01f-4a6759b3330a") | null no null Optional organization ID (UUID) or alias to filter results. If provided, only connections in this organization will be returned. Accepts '@airbyte-internal' as an alias for the Airbyte internal org.
limit integer no 1000 Maximum number of results (default: 1000)
customer_tier_filter enum("TIER_0", "TIER_1", "TIER_2", "UNKNOWN", "ALL") no "TIER_2" Required tier filter: 'TIER_0', 'TIER_1', 'TIER_2', 'UNKNOWN', or 'ALL'. Filters results to only include connections belonging to organizations in the specified tier. Use 'ALL' to include all tiers.
exclude_pinned boolean no false If True, exclude connections whose connector is already pinned to a specific version (at any scope level: actor, workspace, or organization). Useful for 'prove fix' workflows where you want to find unpinned connections for live testing. Default: False (include all connections).
enabled_schedules_only boolean no false If True, only return connections that are both active (not paused/inactive) and on an automated sync schedule (not manual-trigger-only). Useful for canary workflows where you need connections that will produce organic syncs during a monitoring window. Default: False (include all connections).

Show input JSON schema

{
  "additionalProperties": false,
  "properties": {
    "source_definition_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Source connector definition ID (UUID) to search for. Exactly one of source_definition_id, source_canonical_name, destination_definition_id, or destination_canonical_name is required. Example: 'afa734e4-3571-11ec-991a-1e0031268139' for YouTube Analytics."
    },
    "source_canonical_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Canonical source connector name to search for. Exactly one of source_definition_id, source_canonical_name, destination_definition_id, or destination_canonical_name is required. Examples: 'source-youtube-analytics', 'YouTube Analytics'."
    },
    "destination_definition_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Destination connector definition ID (UUID) to search for. Exactly one of source_definition_id, source_canonical_name, destination_definition_id, or destination_canonical_name is required. Example: 'e5c8e66c-a480-4a5e-9c0e-e8e5e4c5c5c5' for DuckDB."
    },
    "destination_canonical_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Canonical destination connector name to search for. Exactly one of source_definition_id, source_canonical_name, destination_definition_id, or destination_canonical_name is required. Examples: 'destination-duckdb', 'DuckDB'."
    },
    "organization_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "description": "Organization ID aliases that can be used in place of UUIDs.\n\nEach member's name is the alias (e.g., \"@airbyte-internal\") and its value\nis the actual organization UUID. Use `OrganizationAliasEnum.resolve()` to\nresolve aliases to actual IDs.",
          "enum": [
            "664c690e-5263-49ba-b01f-4a6759b3330a"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional organization ID (UUID) or alias to filter results. If provided, only connections in this organization will be returned. Accepts '@airbyte-internal' as an alias for the Airbyte internal org."
    },
    "limit": {
      "default": 1000,
      "description": "Maximum number of results (default: 1000)",
      "type": "integer"
    },
    "customer_tier_filter": {
      "default": "TIER_2",
      "description": "Required tier filter: 'TIER_0', 'TIER_1', 'TIER_2', 'UNKNOWN', or 'ALL'. Filters results to only include connections belonging to organizations in the specified tier. Use 'ALL' to include all tiers.",
      "enum": [
        "TIER_0",
        "TIER_1",
        "TIER_2",
        "UNKNOWN",
        "ALL"
      ],
      "type": "string"
    },
    "exclude_pinned": {
      "default": false,
      "description": "If True, exclude connections whose connector is already pinned to a specific version (at any scope level: actor, workspace, or organization). Useful for 'prove fix' workflows where you want to find unpinned connections for live testing. Default: False (include all connections).",
      "type": "boolean"
    },
    "enabled_schedules_only": {
      "default": false,
      "description": "If True, only return connections that are both active (not paused/inactive) and on an automated sync schedule (not manual-trigger-only). Useful for canary workflows where you need connections that will produce organic syncs during a monitoring window. Default: False (include all connections).",
      "type": "boolean"
    }
  },
  "type": "object"
}

Show output JSON schema

{
  "properties": {
    "result": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "type": "object",
  "x-fastmcp-wrap-result": true
}

query_prod_connections_by_stream

Find connections that have a specific stream enabled in their catalog.

This tool searches the connection's configured catalog (JSONB) for streams matching the specified name. It's particularly useful when validating connector fixes that affect specific streams - you can quickly find customer connections that use the affected stream.

Results are always enriched with customer_tier and is_eu fields. The customer_tier_filter parameter is required to ensure tier-aware querying.

Set exclude_pinned=True to filter out connections that are already pinned to a specific version. This is useful for 'prove fix' live connection testing workflows where you want to find unpinned connections to test against.

Use cases:

  • Finding connections with a specific stream enabled for regression testing
  • Validating connector fixes that affect particular streams
  • Identifying which customers use rarely-enabled streams

Returns a list of connection dicts with workspace context and clickable Cloud UI URLs.

Parameters:

Name Type Required Default Description
stream_name string yes — Name of the stream to search for in connection catalogs. This must match the exact stream name as configured in the connection. Examples: 'global_exclusions', 'campaigns', 'users'.
source_definition_id string | null no null Source connector definition ID (UUID) to search for. Provide this OR source_canonical_name (exactly one required). Example: 'afa734e4-3571-11ec-991a-1e0031268139' for YouTube Analytics.
source_canonical_name string | null no null Canonical source connector name to search for. Provide this OR source_definition_id (exactly one required). Examples: 'source-klaviyo', 'Klaviyo', 'source-youtube-analytics'.
organization_id string | enum("664c690e-5263-49ba-b01f-4a6759b3330a") | null no null Optional organization ID (UUID) or alias to filter results. If provided, only connections in this organization will be returned. Accepts '@airbyte-internal' as an alias for the Airbyte internal org.
limit integer no 100 Maximum number of results (default: 100)
customer_tier_filter enum("TIER_0", "TIER_1", "TIER_2", "UNKNOWN", "ALL") no "TIER_2" Required tier filter: 'TIER_0', 'TIER_1', 'TIER_2', 'UNKNOWN', or 'ALL'. Filters results to only include connections belonging to organizations in the specified tier. Use 'ALL' to include all tiers.
exclude_pinned boolean no false If True, exclude connections whose connector is already pinned to a specific version (at any scope level: actor, workspace, or organization). Useful for 'prove fix' workflows where you want to find unpinned connections for live testing. Default: False (include all connections).

Show input JSON schema

{
  "additionalProperties": false,
  "properties": {
    "stream_name": {
      "description": "Name of the stream to search for in connection catalogs. This must match the exact stream name as configured in the connection. Examples: 'global_exclusions', 'campaigns', 'users'.",
      "type": "string"
    },
    "source_definition_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Source connector definition ID (UUID) to search for. Provide this OR source_canonical_name (exactly one required). Example: 'afa734e4-3571-11ec-991a-1e0031268139' for YouTube Analytics."
    },
    "source_canonical_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Canonical source connector name to search for. Provide this OR source_definition_id (exactly one required). Examples: 'source-klaviyo', 'Klaviyo', 'source-youtube-analytics'."
    },
    "organization_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "description": "Organization ID aliases that can be used in place of UUIDs.\n\nEach member's name is the alias (e.g., \"@airbyte-internal\") and its value\nis the actual organization UUID. Use `OrganizationAliasEnum.resolve()` to\nresolve aliases to actual IDs.",
          "enum": [
            "664c690e-5263-49ba-b01f-4a6759b3330a"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional organization ID (UUID) or alias to filter results. If provided, only connections in this organization will be returned. Accepts '@airbyte-internal' as an alias for the Airbyte internal org."
    },
    "limit": {
      "default": 100,
      "description": "Maximum number of results (default: 100)",
      "type": "integer"
    },
    "customer_tier_filter": {
      "default": "TIER_2",
      "description": "Required tier filter: 'TIER_0', 'TIER_1', 'TIER_2', 'UNKNOWN', or 'ALL'. Filters results to only include connections belonging to organizations in the specified tier. Use 'ALL' to include all tiers.",
      "enum": [
        "TIER_0",
        "TIER_1",
        "TIER_2",
        "UNKNOWN",
        "ALL"
      ],
      "type": "string"
    },
    "exclude_pinned": {
      "default": false,
      "description": "If True, exclude connections whose connector is already pinned to a specific version (at any scope level: actor, workspace, or organization). Useful for 'prove fix' workflows where you want to find unpinned connections for live testing. Default: False (include all connections).",
      "type": "boolean"
    }
  },
  "required": [
    "stream_name"
  ],
  "type": "object"
}

Show output JSON schema

{
  "properties": {
    "result": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "type": "object",
  "x-fastmcp-wrap-result": true
}

query_prod_connector_connection_stats

Get aggregate connection stats for multiple connectors.

Returns counts of connections grouped by pinned version for each connector, including:

  • Total, enabled, and active connection counts
  • Pinned vs unpinned breakdown
  • Latest attempt status breakdown (succeeded, failed, cancelled, running, unknown)

This tool is designed for release monitoring workflows. It allows you to:

  1. Query recently released connectors to identify which ones to monitor
  2. Get aggregate stats showing how many connections are using each version
  3. See health metrics (pass/fail) broken down by version

The lookback_days parameter controls the lookback window for:

  • Counting 'active' connections (those with recent sync activity)
  • Determining 'latest attempt status' (most recent attempt within the window)

Connections with no sync activity in the lookback window will have 'unknown' status in the latest_attempt breakdown.

Parameters:

Name Type Required Default Description
source_definition_ids array<string> | null no null List of source connector definition IDs (UUIDs) to get stats for. Example: ['afa734e4-3571-11ec-991a-1e0031268139']
destination_definition_ids array<string> | null no null List of destination connector definition IDs (UUIDs) to get stats for. Example: ['94bd199c-2ff0-4aa2-b98e-17f0acb72610']
lookback_days integer no 7 Number of days to look back for 'active' connections (default: 7). Connections with sync activity within this window are counted as active.

Show input JSON schema

{
  "additionalProperties": false,
  "properties": {
    "source_definition_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "List of source connector definition IDs (UUIDs) to get stats for. Example: ['afa734e4-3571-11ec-991a-1e0031268139']"
    },
    "destination_definition_ids": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "List of destination connector definition IDs (UUIDs) to get stats for. Example: ['94bd199c-2ff0-4aa2-b98e-17f0acb72610']"
    },
    "lookback_days": {
      "default": 7,
      "description": "Number of days to look back for 'active' connections (default: 7). Connections with sync activity within this window are counted as active.",
      "type": "integer"
    }
  },
  "type": "object"
}

Show output JSON schema

{
  "description": "Response containing connection stats for multiple connectors.",
  "properties": {
    "sources": {
      "description": "Stats for source connectors",
      "items": {
        "description": "Aggregate connection stats for a connector.",
        "properties": {
          "connector_definition_id": {
            "description": "The connector definition UUID",
            "type": "string"
          },
          "connector_type": {
            "description": "'source' or 'destination'",
            "type": "string"
          },
          "canonical_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The canonical connector name if resolved"
          },
          "total_connections": {
            "description": "Total number of non-deprecated connections",
            "type": "integer"
          },
          "enabled_connections": {
            "description": "Number of enabled (active status) connections",
            "type": "integer"
          },
          "active_connections": {
            "description": "Number of connections with recent sync activity",
            "type": "integer"
          },
          "pinned_connections": {
            "description": "Number of connections with explicit version pins",
            "type": "integer"
          },
          "unpinned_connections": {
            "description": "Number of connections on default version",
            "type": "integer"
          },
          "latest_attempt": {
            "description": "Overall breakdown by latest attempt status",
            "properties": {
              "succeeded": {
                "default": 0,
                "description": "Connections where latest attempt succeeded",
                "type": "integer"
              },
              "failed": {
                "default": 0,
                "description": "Connections where latest attempt failed",
                "type": "integer"
              },
              "cancelled": {
                "default": 0,
                "description": "Connections where latest attempt was cancelled",
                "type": "integer"
              },
              "running": {
                "default": 0,
                "description": "Connections where latest attempt is still running",
                "type": "integer"
              },
              "unknown": {
                "default": 0,
                "description": "Connections with no recent attempts in the lookback window",
                "type": "integer"
              }
            },
            "type": "object"
          },
          "by_version": {
            "description": "Stats broken down by pinned version",
            "items": {
              "description": "Stats for connections pinned to a specific version.",
              "properties": {
                "pinned_version_id": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "The connector version UUID (None for unpinned connections)"
                },
                "docker_image_tag": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "default": null,
                  "description": "The docker image tag for this version"
                },
                "total_connections": {
                  "description": "Total number of connections",
                  "type": "integer"
                },
                "enabled_connections": {
                  "description": "Number of enabled (active status) connections",
                  "type": "integer"
                },
                "active_connections": {
                  "description": "Number of connections with recent sync activity",
                  "type": "integer"
                },
                "latest_attempt": {
                  "description": "Breakdown by latest attempt status",
                  "properties": {
                    "succeeded": {
                      "default": 0,
                      "description": "Connections where latest attempt succeeded",
                      "type": "integer"
                    },
                    "failed": {
                      "default": 0,
                      "description": "Connections where latest attempt failed",
                      "type": "integer"
                    },
                    "cancelled": {
                      "default": 0,
                      "description": "Connections where latest attempt was cancelled",
                      "type": "integer"
                    },
                    "running": {
                      "default": 0,
                      "description": "Connections where latest attempt is still running",
                      "type": "integer"
                    },
                    "unknown": {
                      "default": 0,
                      "description": "Connections with no recent attempts in the lookback window",
                      "type": "integer"
                    }
                  },
                  "type": "object"
                }
              },
              "required": [
                "pinned_version_id",
                "total_connections",
                "enabled_connections",
                "active_connections",
                "latest_attempt"
              ],
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "connector_definition_id",
          "connector_type",
          "total_connections",
          "enabled_connections",
          "active_connections",
          "pinned_connections",
          "unpinned_connections",
          "latest_attempt",
          "by_version"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "destinations": {
      "description": "Stats for destination connectors",
      "items": {
        "description": "Aggregate connection stats for a connector.",
        "properties": {
          "connector_definition_id": {
            "description": "The connector definition UUID",
            "type": "string"
          },
          "connector_type": {
            "description": "'source' or 'destination'",
            "type": "string"
          },
          "canonical_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The canonical connector name if resolved"
          },
          "total_connections": {
            "description": "Total number of non-deprecated connections",
            "type": "integer"
          },
          "enabled_connections": {
            "description": "Number of enabled (active status) connections",
            "type": "integer"
          },
          "active_connections": {
            "description": "Number of connections with recent sync activity",
            "type": "integer"
          },
          "pinned_connections": {
            "description": "Number of connections with explicit version pins",
            "type": "integer"
          },
          "unpinned_connections": {
            "description": "Number of connections on default version",
            "type": "integer"
          },
          "latest_attempt": {
            "description": "Overall breakdown by latest attempt status",
            "properties": {
              "succeeded": {
                "default": 0,
                "description": "Connections where latest attempt succeeded",
                "type": "integer"
              },
              "failed": {
                "default": 0,
                "description": "Connections where latest attempt failed",
                "type": "integer"
              },
              "cancelled": {
                "default": 0,
                "description": "Connections where latest attempt was cancelled",
                "type": "integer"
              },
              "running": {
                "default": 0,
                "description": "Connections where latest attempt is still running",
                "type": "integer"
              },
              "unknown": {
                "default": 0,
                "description": "Connections with no recent attempts in the lookback window",
                "type": "integer"
              }
            },
            "type": "object"
          },
          "by_version": {
            "description": "Stats broken down by pinned version",
            "items": {
              "description": "Stats for connections pinned to a specific version.",
              "properties": {
                "pinned_version_id": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "description": "The connector version UUID (None for unpinned connections)"
                },
                "docker_image_tag": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "default": null,
                  "description": "The docker image tag for this version"
                },
                "total_connections": {
                  "description": "Total number of connections",
                  "type": "integer"
                },
                "enabled_connections": {
                  "description": "Number of enabled (active status) connections",
                  "type": "integer"
                },
                "active_connections": {
                  "description": "Number of connections with recent sync activity",
                  "type": "integer"
                },
                "latest_attempt": {
                  "description": "Breakdown by latest attempt status",
                  "properties": {
                    "succeeded": {
                      "default": 0,
                      "description": "Connections where latest attempt succeeded",
                      "type": "integer"
                    },
                    "failed": {
                      "default": 0,
                      "description": "Connections where latest attempt failed",
                      "type": "integer"
                    },
                    "cancelled": {
                      "default": 0,
                      "description": "Connections where latest attempt was cancelled",
                      "type": "integer"
                    },
                    "running": {
                      "default": 0,
                      "description": "Connections where latest attempt is still running",
                      "type": "integer"
                    },
                    "unknown": {
                      "default": 0,
                      "description": "Connections with no recent attempts in the lookback window",
                      "type": "integer"
                    }
                  },
                  "type": "object"
                }
              },
              "required": [
                "pinned_version_id",
                "total_connections",
                "enabled_connections",
                "active_connections",
                "latest_attempt"
              ],
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "connector_definition_id",
          "connector_type",
          "total_connections",
          "enabled_connections",
          "active_connections",
          "pinned_connections",
          "unpinned_connections",
          "latest_attempt",
          "by_version"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "lookback_days": {
      "description": "Lookback window used for 'active' connections",
      "type": "integer"
    },
    "generated_at": {
      "description": "When this response was generated",
      "format": "date-time",
      "type": "string"
    }
  },
  "required": [
    "lookback_days",
    "generated_at"
  ],
  "type": "object"
}

query_prod_connector_rollouts

Query connector rollouts with flexible filtering.

Returns rollouts based on the provided filters. If no filters are specified, returns all active rollouts. Useful for monitoring rollout status and history.

Filter behavior:

  • rollout_id: Returns that specific rollout (ignores other filters)
  • active_only: Returns only active (non-terminal) rollouts
  • actor_definition_id: Returns rollouts for that specific connector
  • No filters: Returns all active rollouts (same as active_only=True)

Parameters:

Name Type Required Default Description
actor_definition_id string | null no null Connector definition UUID to filter by (optional)
rollout_id string | null no null Specific rollout UUID to look up (optional)
active_only boolean no false If true, only return active (non-terminal) rollouts
limit integer no 100 Maximum number of results (default: 100)

Show input JSON schema

{
  "additionalProperties": false,
  "properties": {
    "actor_definition_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Connector definition UUID to filter by (optional)"
    },
    "rollout_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Specific rollout UUID to look up (optional)"
    },
    "active_only": {
      "default": false,
      "description": "If true, only return active (non-terminal) rollouts",
      "type": "boolean"
    },
    "limit": {
      "default": 100,
      "description": "Maximum number of results (default: 100)",
      "type": "integer"
    }
  },
  "type": "object"
}

Show output JSON schema

{
  "properties": {
    "result": {
      "items": {
        "description": "Information about a connector rollout.",
        "properties": {
          "rollout_id": {
            "description": "The rollout UUID",
            "type": "string"
          },
          "actor_definition_id": {
            "description": "The connector definition UUID",
            "type": "string"
          },
          "state": {
            "description": "Rollout state: initialized, workflow_started, in_progress, paused, finalizing, succeeded, errored, failed_rolled_back, canceled",
            "type": "string"
          },
          "initial_rollout_pct": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Initial rollout percentage"
          },
          "current_target_rollout_pct": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Current target rollout percentage"
          },
          "final_target_rollout_pct": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Final target rollout percentage"
          },
          "has_breaking_changes": {
            "description": "Whether the RC has breaking changes",
            "type": "boolean"
          },
          "max_step_wait_time_mins": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Maximum wait time between rollout steps in minutes"
          },
          "rollout_strategy": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Rollout strategy: manual, automated, overridden"
          },
          "updated_by_user_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "User ID recorded as last updating the rollout"
          },
          "updated_by_user_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Name recorded as last updating the rollout"
          },
          "updated_by_user_email": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Email recorded as last updating the rollout"
          },
          "workflow_run_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Temporal workflow run ID"
          },
          "error_msg": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Error message if errored"
          },
          "failed_reason": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Reason for failure if failed"
          },
          "paused_reason": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Reason for pause if paused"
          },
          "tag": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Optional tag for the rollout"
          },
          "created_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "When the rollout was created"
          },
          "updated_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "When the rollout was last updated"
          },
          "completed_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "When the rollout completed (if terminal)"
          },
          "expires_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "When the rollout expires"
          },
          "rc_docker_image_tag": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Docker image tag of the release candidate"
          },
          "rc_docker_repository": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Docker repository of the release candidate"
          },
          "initial_docker_image_tag": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Docker image tag of the initial version"
          },
          "initial_docker_repository": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Docker repository of the initial version"
          },
          "filters": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Raw rollout filters JSON (e.g., {'tierFilter': {'tier': 'TIER_0'}})"
          },
          "customer_tier": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Customer tier targeted by this rollout (extracted from filters), e.g., 'TIER_0', 'TIER_1'. None if no tier filter is set."
          }
        },
        "required": [
          "rollout_id",
          "actor_definition_id",
          "state",
          "has_breaking_changes"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "type": "object",
  "x-fastmcp-wrap-result": true
}

query_prod_connector_versions

List all versions for a connector definition.

Returns all published versions of a connector, ordered by last_published date descending. Useful for understanding version history and finding specific version IDs for pinning or rollout monitoring.

Returns list of dicts with keys: version_id, docker_image_tag, docker_repository, release_stage, support_level, cdk_version, language, last_published, release_date

Parameters:

Name Type Required Default Description
connector_definition_id string yes — Connector definition UUID to list versions for

Show input JSON schema

{
  "additionalProperties": false,
  "properties": {
    "connector_definition_id": {
      "description": "Connector definition UUID to list versions for",
      "type": "string"
    }
  },
  "required": [
    "connector_definition_id"
  ],
  "type": "object"
}

Show output JSON schema

{
  "properties": {
    "result": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "type": "object",
  "x-fastmcp-wrap-result": true
}

query_prod_dataplanes

List all dataplane groups with workspace counts.

Returns information about all active dataplane groups in Airbyte Cloud, including the number of workspaces in each. Useful for understanding the distribution of workspaces across regions (US, US-Central, EU).

Returns list of dicts with keys: dataplane_group_id, dataplane_name, organization_id, enabled, tombstone, created_at, workspace_count

Parameters:

_No parameters._

Show input JSON schema

{
  "additionalProperties": false,
  "properties": {},
  "type": "object"
}

Show output JSON schema

{
  "properties": {
    "result": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "type": "object",
  "x-fastmcp-wrap-result": true
}

query_prod_failed_sync_attempts_for_connector

List failed sync attempts for ALL actors using a connector type.

This tool finds all actors with the given connector definition and returns their failed sync attempts, regardless of whether they have explicit version pins.

Results are always enriched with customer_tier and is_eu fields. The customer_tier_filter parameter is required to ensure tier-aware querying.

This is useful for investigating connector issues across all users. Use this when you want to find failures for a connector type regardless of which version users are on.

Supports both SOURCE and DESTINATION connectors. Provide exactly one of: source_definition_id, source_canonical_name, destination_definition_id, or destination_canonical_name.

Key fields in results:

  • failure_summary: JSON containing failure details including failureType and messages
  • customer_tier: TIER_0, TIER_1, TIER_2, or UNKNOWN
  • is_eu: Whether the workspace is in the EU region
  • pin_origin_type, pin_origin, pinned_version_id: Version pin context (NULL if not pinned)
  • pin_scope_type: 'actor', 'workspace', or 'organization' (NULL if not pinned)

Parameters:

Name Type Required Default Description
source_definition_id string | null no null Source connector definition ID (UUID) to search for. Provide this OR source_canonical_name OR destination_definition_id OR destination_canonical_name (exactly one required). Example: 'afa734e4-3571-11ec-991a-1e0031268139' for YouTube Analytics.
source_canonical_name string | null no null Canonical source connector name to search for. Provide this OR source_definition_id OR destination_definition_id OR destination_canonical_name (exactly one required). Examples: 'source-youtube-analytics', 'YouTube Analytics'.
destination_definition_id string | null no null Destination connector definition ID (UUID) to search for. Provide this OR destination_canonical_name OR source_definition_id OR source_canonical_name (exactly one required). Example: '94bd199c-2ff0-4aa2-b98e-17f0acb72610' for DuckDB.
destination_canonical_name string | null no null Canonical destination connector name to search for. Provide this OR destination_definition_id OR source_definition_id OR source_canonical_name (exactly one required). Examples: 'destination-duckdb', 'DuckDB'.
organization_id string | enum("664c690e-5263-49ba-b01f-4a6759b3330a") | null no null Optional organization ID (UUID) or alias to filter results. If provided, only failed attempts from this organization will be returned. Accepts '@airbyte-internal' as an alias for the Airbyte internal org.
lookback_days integer no 7 Number of days to look back (default: 7)
limit integer no 100 Maximum number of results (default: 100)
customer_tier_filter enum("TIER_0", "TIER_1", "TIER_2", "UNKNOWN", "ALL") no "TIER_2" Required tier filter: 'TIER_0', 'TIER_1', 'TIER_2', 'UNKNOWN', or 'ALL'. Filters results to only include connections belonging to organizations in the specified tier. Use 'ALL' to include all tiers.

Show input JSON schema

{
  "additionalProperties": false,
  "properties": {
    "source_definition_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Source connector definition ID (UUID) to search for. Provide this OR source_canonical_name OR destination_definition_id OR destination_canonical_name (exactly one required). Example: 'afa734e4-3571-11ec-991a-1e0031268139' for YouTube Analytics."
    },
    "source_canonical_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Canonical source connector name to search for. Provide this OR source_definition_id OR destination_definition_id OR destination_canonical_name (exactly one required). Examples: 'source-youtube-analytics', 'YouTube Analytics'."
    },
    "destination_definition_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Destination connector definition ID (UUID) to search for. Provide this OR destination_canonical_name OR source_definition_id OR source_canonical_name (exactly one required). Example: '94bd199c-2ff0-4aa2-b98e-17f0acb72610' for DuckDB."
    },
    "destination_canonical_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Canonical destination connector name to search for. Provide this OR destination_definition_id OR source_definition_id OR source_canonical_name (exactly one required). Examples: 'destination-duckdb', 'DuckDB'."
    },
    "organization_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "description": "Organization ID aliases that can be used in place of UUIDs.\n\nEach member's name is the alias (e.g., \"@airbyte-internal\") and its value\nis the actual organization UUID. Use `OrganizationAliasEnum.resolve()` to\nresolve aliases to actual IDs.",
          "enum": [
            "664c690e-5263-49ba-b01f-4a6759b3330a"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional organization ID (UUID) or alias to filter results. If provided, only failed attempts from this organization will be returned. Accepts '@airbyte-internal' as an alias for the Airbyte internal org."
    },
    "lookback_days": {
      "default": 7,
      "description": "Number of days to look back (default: 7)",
      "type": "integer"
    },
    "limit": {
      "default": 100,
      "description": "Maximum number of results (default: 100)",
      "type": "integer"
    },
    "customer_tier_filter": {
      "default": "TIER_2",
      "description": "Required tier filter: 'TIER_0', 'TIER_1', 'TIER_2', 'UNKNOWN', or 'ALL'. Filters results to only include connections belonging to organizations in the specified tier. Use 'ALL' to include all tiers.",
      "enum": [
        "TIER_0",
        "TIER_1",
        "TIER_2",
        "UNKNOWN",
        "ALL"
      ],
      "type": "string"
    }
  },
  "type": "object"
}

Show output JSON schema

{
  "properties": {
    "result": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "type": "object",
  "x-fastmcp-wrap-result": true
}

query_prod_new_connector_releases

List recently published connector versions.

Returns connector versions published within the specified number of days. Uses last_published timestamp which reflects when the version was actually deployed to the registry (not the changelog date).

Returns list of dicts with keys: version_id, connector_definition_id, docker_repository, docker_image_tag, last_published, release_date, release_stage, support_level, cdk_version, language, created_at

Parameters:

Name Type Required Default Description
days integer no 7 Number of days to look back (default: 7)
limit integer no 100 Maximum number of results (default: 100)

Show input JSON schema

{
  "additionalProperties": false,
  "properties": {
    "days": {
      "default": 7,
      "description": "Number of days to look back (default: 7)",
      "type": "integer"
    },
    "limit": {
      "default": 100,
      "description": "Maximum number of results (default: 100)",
      "type": "integer"
    }
  },
  "type": "object"
}

Show output JSON schema

{
  "properties": {
    "result": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "type": "object",
  "x-fastmcp-wrap-result": true
}

query_prod_org_admin_contacts

Find Org Admins and Workspace Admins of the given workspaces.

Activity is each user's latest user-attributed connection timeline event in this organization within the lookback window. Emails are returned because callers need them to CC customers; never log them. Only direct user grants are included; group-granted permissions are not queried. The org's customer_tier is included for awareness only; outreach must still reach every affected organization regardless of tier.

Parameters:

Name Type Required Default Description
organization_id string yes — Organization UUID whose direct Org Admins to find.
workspace_ids array<string> no [] Workspace UUIDs whose direct Workspace Admins to include. Only these workspaces contribute Workspace Admins.
activity_lookback_days integer no 90 Days to look back for user-attributed connection activity.

Show input JSON schema

{
  "additionalProperties": false,
  "properties": {
    "organization_id": {
      "description": "Organization UUID whose direct Org Admins to find.",
      "type": "string"
    },
    "workspace_ids": {
      "default": [],
      "description": "Workspace UUIDs whose direct Workspace Admins to include. Only these workspaces contribute Workspace Admins.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "activity_lookback_days": {
      "default": 90,
      "description": "Days to look back for user-attributed connection activity.",
      "maximum": 365,
      "minimum": 1,
      "type": "integer"
    }
  },
  "required": [
    "organization_id"
  ],
  "type": "object"
}

Show output JSON schema

{
  "description": "Organization administrator contacts and recent user activity.",
  "properties": {
    "organization_id": {
      "description": "The organization UUID.",
      "type": "string"
    },
    "customer_tier": {
      "description": "Organization customer tier, included for awareness only.",
      "type": "string"
    },
    "tier_warnings": {
      "description": "Warnings raised while resolving the organization customer tier.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "activity_lookback_days": {
      "description": "Number of days used to look back for connection activity.",
      "type": "integer"
    },
    "admins": {
      "description": "Administrators ordered by Airbyte user UUID.",
      "items": {
        "description": "An organization or selected-workspace administrator contact.",
        "properties": {
          "user_id": {
            "description": "The Airbyte user UUID.",
            "type": "string"
          },
          "name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The administrator's name."
          },
          "email": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The administrator's email address."
          },
          "status": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The user's status."
          },
          "is_org_admin": {
            "description": "Whether the user is an Org Admin.",
            "type": "boolean"
          },
          "admin_workspace_ids": {
            "description": "Sorted workspace UUIDs where the user is a Workspace Admin.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "user_created_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "When the user account was created."
          },
          "user_updated_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "When the user account was last updated."
          },
          "last_connection_event_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Latest user-attributed connection timeline event in the activity window."
          }
        },
        "required": [
          "user_id",
          "is_org_admin",
          "admin_workspace_ids"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "organization_id",
    "customer_tier",
    "activity_lookback_days",
    "admins"
  ],
  "type": "object"
}

query_prod_organizations

Search organizations by name or email substring.

Performs a case-insensitive substring match on organization name and email. Use the returned organization_id values with other tools like query_prod_connections_by_connector or lookup_customer_tiers.

Parameters:

Name Type Required Default Description
name_contains string yes — Case-insensitive substring to search for in organization name or email. For example, 'acme' will match organizations named 'Acme Corp' or with email 'admin@acme.io'.
limit integer no 20 Maximum number of organizations to return (default: 20)

Show input JSON schema

{
  "additionalProperties": false,
  "properties": {
    "name_contains": {
      "description": "Case-insensitive substring to search for in organization name or email. For example, 'acme' will match organizations named 'Acme Corp' or with email 'admin@acme.io'.",
      "type": "string"
    },
    "limit": {
      "default": 20,
      "description": "Maximum number of organizations to return (default: 20)",
      "type": "integer"
    }
  },
  "required": [
    "name_contains"
  ],
  "type": "object"
}

Show output JSON schema

{
  "description": "Result of searching organizations by name substring.",
  "properties": {
    "name_contains": {
      "description": "The search substring that was used",
      "type": "string"
    },
    "total_found": {
      "description": "Total number of organizations matching",
      "type": "integer"
    },
    "organizations": {
      "description": "List of matching organizations",
      "items": {
        "description": "A single organization returned by a name/email search.",
        "properties": {
          "organization_id": {
            "description": "The organization UUID",
            "type": "string"
          },
          "organization_name": {
            "description": "The name of the organization",
            "type": "string"
          },
          "email": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The email address associated with the organization"
          },
          "customer_tier": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Customer tier (TIER_0, TIER_1, TIER_2, or UNKNOWN). Enriched from the GCS tier cache."
          }
        },
        "required": [
          "organization_id",
          "organization_name"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "name_contains",
    "total_found",
    "organizations"
  ],
  "type": "object"
}

query_prod_pin_stats_for_organization

Query connector versions pinned anywhere under an organization.

Returns one row per pinned version, aggregating every connector_version pin whose scope belongs to the organization — the org itself, one of its workspaces, or an actor within one of those workspaces (actor, workspace, and organization scopes). Each row carries the per-scope pin breakdown, the manual/rollout/breaking-change split, and a has_active_rollout flag.

This powers the first step of the Organization Pins view (pick an org, then see the versions pinned under it). Use query_prod_pins_for_organization for the individual pins behind a selected version.

Parameters:

Name Type Required Default Description
organization_id string | enum("664c690e-5263-49ba-b01f-4a6759b3330a") yes — Organization UUID (or @airbyte-internal alias) to scope pins to. Resolve organization names to an ID first via search_organizations.
connector_definition_id string | null no null Connector definition UUID to filter by (optional). Mutually exclusive with connector_canonical_name.
connector_canonical_name string | null no null Connector canonical name (e.g. source-postgres) to filter by. Resolved to a definition ID via the registry. Mutually exclusive with connector_definition_id.
limit integer no 1000 Maximum number of versions to return (default: 1000).

Show input JSON schema

{
  "additionalProperties": false,
  "properties": {
    "organization_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "description": "Organization ID aliases that can be used in place of UUIDs.\n\nEach member's name is the alias (e.g., \"@airbyte-internal\") and its value\nis the actual organization UUID. Use `OrganizationAliasEnum.resolve()` to\nresolve aliases to actual IDs.",
          "enum": [
            "664c690e-5263-49ba-b01f-4a6759b3330a"
          ],
          "type": "string"
        }
      ],
      "description": "Organization UUID (or `@airbyte-internal` alias) to scope pins to. Resolve organization names to an ID first via `search_organizations`."
    },
    "connector_definition_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Connector definition UUID to filter by (optional). Mutually exclusive with `connector_canonical_name`."
    },
    "connector_canonical_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Connector canonical name (e.g. `source-postgres`) to filter by. Resolved to a definition ID via the registry. Mutually exclusive with `connector_definition_id`."
    },
    "limit": {
      "default": 1000,
      "description": "Maximum number of versions to return (default: 1000).",
      "type": "integer"
    }
  },
  "required": [
    "organization_id"
  ],
  "type": "object"
}

Show output JSON schema

{
  "properties": {
    "result": {
      "items": {
        "description": "A connector version pinned somewhere under an organization, with counts.",
        "properties": {
          "version_id": {
            "description": "The actor_definition_version UUID",
            "type": "string"
          },
          "connector_definition_id": {
            "description": "The connector definition UUID",
            "type": "string"
          },
          "connector_name": {
            "description": "Human-readable connector name",
            "type": "string"
          },
          "docker_repository": {
            "description": "Docker repository path",
            "type": "string"
          },
          "docker_image_tag": {
            "description": "Docker image tag for this version",
            "type": "string"
          },
          "last_published": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "ISO timestamp when this version was last published"
          },
          "pin_count": {
            "description": "Total pins under the org targeting this version (all scopes)",
            "type": "integer"
          },
          "manual_pins": {
            "default": 0,
            "description": "Pins with no system origin (user-created manual pins), any scope",
            "type": "integer"
          },
          "rollout_pins": {
            "default": 0,
            "description": "Pins created by connector rollouts",
            "type": "integer"
          },
          "breaking_change_pins": {
            "default": 0,
            "description": "Pins created by breaking changes",
            "type": "integer"
          },
          "actor_pins": {
            "description": "Manual actor-scoped pins (excludes rollout and breaking-change)",
            "type": "integer"
          },
          "workspace_pins": {
            "description": "Workspace-scoped pins under the org",
            "type": "integer"
          },
          "org_pins": {
            "description": "Organization-scoped pins",
            "type": "integer"
          },
          "has_active_rollout": {
            "default": false,
            "description": "`True` if at least one rollout pin is backed by a non-terminal `connector_rollout`",
            "type": "boolean"
          }
        },
        "required": [
          "version_id",
          "connector_definition_id",
          "connector_name",
          "docker_repository",
          "docker_image_tag",
          "pin_count",
          "actor_pins",
          "workspace_pins",
          "org_pins"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "type": "object",
  "x-fastmcp-wrap-result": true
}

query_prod_pins_for_organization

List the individual connector-version pins discovered under an organization.

Returns one row per scoped_configuration pin whose scope belongs to the organization (org/workspace/actor), resolving the pinned connector and version, the scope's display name, the manual author's email, and — for rollout-origin pins — the backing connector_rollout id and state. This directly answers whether each pin is manual or caused by an active rollout.

This powers the second step of the Organization Pins view: after picking a version from query_prod_pin_stats_for_organization, pass its pinned_version_id here to list the pins behind it.

Parameters:

Name Type Required Default Description
organization_id string | enum("664c690e-5263-49ba-b01f-4a6759b3330a") yes — Organization UUID (or @airbyte-internal alias) to scope pins to. Resolve organization names to an ID first via search_organizations.
connector_definition_id string | null no null Connector definition UUID to filter by (optional). Mutually exclusive with connector_canonical_name.
connector_canonical_name string | null no null Connector canonical name (e.g. source-postgres) to filter by. Resolved to a definition ID via the registry. Mutually exclusive with connector_definition_id.
pinned_version_id string | null no null Actor_definition_version UUID to return only pins targeting that version. This is the post-selection filter for the org pins tab.
origin_filter enum("all", "manual", "connector_rollout", "breaking_change") no "all" Restrict by how the pin was created: all (default), manual, connector_rollout, or breaking_change.
limit integer no 1000 Maximum number of pins to return (default: 1000).

Show input JSON schema

{
  "additionalProperties": false,
  "properties": {
    "organization_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "description": "Organization ID aliases that can be used in place of UUIDs.\n\nEach member's name is the alias (e.g., \"@airbyte-internal\") and its value\nis the actual organization UUID. Use `OrganizationAliasEnum.resolve()` to\nresolve aliases to actual IDs.",
          "enum": [
            "664c690e-5263-49ba-b01f-4a6759b3330a"
          ],
          "type": "string"
        }
      ],
      "description": "Organization UUID (or `@airbyte-internal` alias) to scope pins to. Resolve organization names to an ID first via `search_organizations`."
    },
    "connector_definition_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Connector definition UUID to filter by (optional). Mutually exclusive with `connector_canonical_name`."
    },
    "connector_canonical_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Connector canonical name (e.g. `source-postgres`) to filter by. Resolved to a definition ID via the registry. Mutually exclusive with `connector_definition_id`."
    },
    "pinned_version_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Actor_definition_version UUID to return only pins targeting that version. This is the post-selection filter for the org pins tab."
    },
    "origin_filter": {
      "description": "Restrict by how the pin was created: `all` (default), `manual`, `connector_rollout`, or `breaking_change`.",
      "enum": [
        "all",
        "manual",
        "connector_rollout",
        "breaking_change"
      ],
      "type": "string",
      "default": "all"
    },
    "limit": {
      "default": 1000,
      "description": "Maximum number of pins to return (default: 1000).",
      "type": "integer"
    }
  },
  "required": [
    "organization_id"
  ],
  "type": "object"
}

Show output JSON schema

{
  "properties": {
    "result": {
      "items": {
        "description": "A single `scoped_configuration` pin discovered under an organization.",
        "properties": {
          "connector_definition_id": {
            "description": "The connector definition UUID",
            "type": "string"
          },
          "connector_name": {
            "description": "Human-readable connector name",
            "type": "string"
          },
          "docker_repository": {
            "description": "Docker repository path",
            "type": "string"
          },
          "pinned_version_id": {
            "description": "The pinned actor_definition_version UUID",
            "type": "string"
          },
          "pinned_version_tag": {
            "description": "Docker image tag of the pinned version",
            "type": "string"
          },
          "pin_scope_type": {
            "description": "Scope of the pin: `organization`, `workspace`, or `actor`",
            "type": "string"
          },
          "scope_id": {
            "description": "UUID of the scoped entity",
            "type": "string"
          },
          "scope_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Display name of the scoped entity, when resolvable"
          },
          "pin_category": {
            "description": "Derived pin type: `manual`, `rollout`, or `breaking_change`",
            "type": "string"
          },
          "set_by": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Email (or name) of the user who set a manual pin, when known"
          },
          "rollout_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Backing connector_rollout UUID for rollout pins"
          },
          "rollout_state": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "State of the backing rollout, for rollout pins"
          },
          "is_active_rollout": {
            "default": false,
            "description": "`True` when `rollout_state` is a non-terminal (active) state",
            "type": "boolean"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Free-text pin reason"
          },
          "reference_url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Reference URL attached to the pin, when present"
          },
          "created_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "ISO timestamp when the pin was created"
          },
          "expires_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "ISO timestamp when the pin expires, when set"
          }
        },
        "required": [
          "connector_definition_id",
          "connector_name",
          "docker_repository",
          "pinned_version_id",
          "pinned_version_tag",
          "pin_scope_type",
          "scope_id",
          "pin_category"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "type": "object",
  "x-fastmcp-wrap-result": true
}

query_prod_recent_syncs_for_connector

List recent sync jobs for ALL actors using a connector type.

This tool finds all actors with the given connector definition and returns their recent sync jobs, regardless of whether they have explicit version pins. It filters out deleted actors, deleted workspaces, and deprecated connections.

Results are always enriched with customer_tier and is_eu fields. The customer_tier_filter parameter is required to ensure tier-aware querying.

Use this tool to:

  • Find healthy connections with recent successful syncs (status_filter='succeeded')
  • Investigate connector issues across all users (status_filter='failed')
  • Get an overview of all recent sync activity (status_filter='all')

Set exclude_pinned=True to filter out syncs for actors that are already pinned to a specific version. This is useful for 'prove fix' live connection testing workflows where you want to find unpinned connections to test against.

Set enabled_schedules_only=True to restrict results to connections that are both enabled (status='active') and on an automated schedule (not manual-trigger-only). This is useful for canary prerelease workflows where you need connections that will run organically during the monitoring window.

Supports both SOURCE and DESTINATION connectors. Provide exactly one of: source_definition_id, source_canonical_name, destination_definition_id, or destination_canonical_name.

Key fields in results:

  • job_status: 'succeeded', 'failed', 'cancelled', etc.
  • connection_id, connection_name: The connection that ran the sync
  • actor_id, actor_name: The source or destination actor
  • customer_tier: TIER_0, TIER_1, TIER_2, or UNKNOWN
  • is_eu: Whether the workspace is in the EU region
  • pin_origin_type, pin_origin, pinned_version_id: Version pin context (NULL if not pinned)
  • pin_scope_type: 'actor', 'workspace', or 'organization' (NULL if not pinned)

Parameters:

Name Type Required Default Description
source_definition_id string | null no null Source connector definition ID (UUID) to search for. Provide this OR source_canonical_name OR destination_definition_id OR destination_canonical_name (exactly one required). Example: 'afa734e4-3571-11ec-991a-1e0031268139' for YouTube Analytics.
source_canonical_name string | null no null Canonical source connector name to search for. Provide this OR source_definition_id OR destination_definition_id OR destination_canonical_name (exactly one required). Examples: 'source-youtube-analytics', 'YouTube Analytics'.
destination_definition_id string | null no null Destination connector definition ID (UUID) to search for. Provide this OR destination_canonical_name OR source_definition_id OR source_canonical_name (exactly one required). Example: '94bd199c-2ff0-4aa2-b98e-17f0acb72610' for DuckDB.
destination_canonical_name string | null no null Canonical destination connector name to search for. Provide this OR destination_definition_id OR source_definition_id OR source_canonical_name (exactly one required). Examples: 'destination-duckdb', 'DuckDB'.
status_filter enum("all", "succeeded", "failed") no "all" Filter by job status: 'all' (default), 'succeeded', or 'failed'. Use 'succeeded' to find healthy connections with recent successful syncs. Use 'failed' to find connections with recent failures.
organization_id string | enum("664c690e-5263-49ba-b01f-4a6759b3330a") | null no null Optional organization ID (UUID) or alias to filter results. If provided, only syncs from this organization will be returned. Accepts '@airbyte-internal' as an alias for the Airbyte internal org.
lookback_days integer no 7 Number of days to look back (default: 7)
limit integer no 100 Maximum number of results (default: 100)
customer_tier_filter enum("TIER_0", "TIER_1", "TIER_2", "UNKNOWN", "ALL") no "TIER_2" Required tier filter: 'TIER_0', 'TIER_1', 'TIER_2', 'UNKNOWN', or 'ALL'. Filters results to only include connections belonging to organizations in the specified tier. Use 'ALL' to include all tiers.
exclude_pinned boolean no false If True, exclude syncs for actors that are already pinned to a specific version (at any scope level: actor, workspace, or organization). Useful for 'prove fix' workflows where you want to find unpinned connections for live testing. Default: False (include all syncs).
enabled_schedules_only boolean no false If True, only return syncs for connections that are both active (not paused/inactive) and on an automated sync schedule (not manual-trigger-only). Useful for canary workflows where you need connections that will produce organic syncs during a monitoring window. Default: False (include all connections).

Show input JSON schema

{
  "additionalProperties": false,
  "properties": {
    "source_definition_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Source connector definition ID (UUID) to search for. Provide this OR source_canonical_name OR destination_definition_id OR destination_canonical_name (exactly one required). Example: 'afa734e4-3571-11ec-991a-1e0031268139' for YouTube Analytics."
    },
    "source_canonical_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Canonical source connector name to search for. Provide this OR source_definition_id OR destination_definition_id OR destination_canonical_name (exactly one required). Examples: 'source-youtube-analytics', 'YouTube Analytics'."
    },
    "destination_definition_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Destination connector definition ID (UUID) to search for. Provide this OR destination_canonical_name OR source_definition_id OR source_canonical_name (exactly one required). Example: '94bd199c-2ff0-4aa2-b98e-17f0acb72610' for DuckDB."
    },
    "destination_canonical_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Canonical destination connector name to search for. Provide this OR destination_definition_id OR source_definition_id OR source_canonical_name (exactly one required). Examples: 'destination-duckdb', 'DuckDB'."
    },
    "status_filter": {
      "description": "Filter by job status: 'all' (default), 'succeeded', or 'failed'. Use 'succeeded' to find healthy connections with recent successful syncs. Use 'failed' to find connections with recent failures.",
      "enum": [
        "all",
        "succeeded",
        "failed"
      ],
      "type": "string",
      "default": "all"
    },
    "organization_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "description": "Organization ID aliases that can be used in place of UUIDs.\n\nEach member's name is the alias (e.g., \"@airbyte-internal\") and its value\nis the actual organization UUID. Use `OrganizationAliasEnum.resolve()` to\nresolve aliases to actual IDs.",
          "enum": [
            "664c690e-5263-49ba-b01f-4a6759b3330a"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional organization ID (UUID) or alias to filter results. If provided, only syncs from this organization will be returned. Accepts '@airbyte-internal' as an alias for the Airbyte internal org."
    },
    "lookback_days": {
      "default": 7,
      "description": "Number of days to look back (default: 7)",
      "type": "integer"
    },
    "limit": {
      "default": 100,
      "description": "Maximum number of results (default: 100)",
      "type": "integer"
    },
    "customer_tier_filter": {
      "default": "TIER_2",
      "description": "Required tier filter: 'TIER_0', 'TIER_1', 'TIER_2', 'UNKNOWN', or 'ALL'. Filters results to only include connections belonging to organizations in the specified tier. Use 'ALL' to include all tiers.",
      "enum": [
        "TIER_0",
        "TIER_1",
        "TIER_2",
        "UNKNOWN",
        "ALL"
      ],
      "type": "string"
    },
    "exclude_pinned": {
      "default": false,
      "description": "If True, exclude syncs for actors that are already pinned to a specific version (at any scope level: actor, workspace, or organization). Useful for 'prove fix' workflows where you want to find unpinned connections for live testing. Default: False (include all syncs).",
      "type": "boolean"
    },
    "enabled_schedules_only": {
      "default": false,
      "description": "If True, only return syncs for connections that are both active (not paused/inactive) and on an automated sync schedule (not manual-trigger-only). Useful for canary workflows where you need connections that will produce organic syncs during a monitoring window. Default: False (include all connections).",
      "type": "boolean"
    }
  },
  "type": "object"
}

Show output JSON schema

{
  "properties": {
    "result": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "type": "object",
  "x-fastmcp-wrap-result": true
}

query_prod_recent_syncs_for_connector_version

List sync jobs that were run with a specific connector version.

Works for both source and destination connectors. Automatically detects the connector type from the version metadata and uses the appropriate query variant.

Accepts either connector_version_id (UUID) or connector_name + connector_version (e.g. source-pokeapi + 0.3.59). When using name + version, the docker_repository is derived from the canonical name (e.g. source-pokeapi → airbyte/source-pokeapi).

Filters on the version stamped into jobs.config at job-creation time, not the current pin state. This avoids false positives (pre-pin syncs counted as RC) and false negatives (post-unpin syncs missed).

Pin columns (pin_origin_type, pin_origin, pin_scope_type) are still included as informational output but are not used for filtering.

Returns list of dicts with keys: job_id, connection_id, job_status, started_at, job_updated_at, connection_name, actor_id, actor_name, actor_definition_id, source_definition_version_id, destination_definition_version_id, pin_origin_type, pin_origin, pin_scope_type, workspace_id, workspace_name, organization_id, dataplane_group_id, dataplane_name.

Parameters:

Name Type Required Default Description
connector_version_id string | null no null Connector version UUID. Provide this OR connector_name + connector_version.
connector_name string | null no null Canonical connector name (e.g. source-pokeapi, destination-duckdb). Used with connector_version to resolve the version UUID.
connector_version string | null no null Semver version tag (e.g. 0.3.59). Used with connector_name to resolve the version UUID.
days integer no 7 Number of days to look back (default: 7)
limit integer no 100 Maximum number of results (default: 100)
successful_only boolean no false If True, only return successful syncs (default: False)

Show input JSON schema

{
  "additionalProperties": false,
  "properties": {
    "connector_version_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Connector version UUID. Provide this OR connector_name + connector_version."
    },
    "connector_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Canonical connector name (e.g. `source-pokeapi`, `destination-duckdb`). Used with `connector_version` to resolve the version UUID."
    },
    "connector_version": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Semver version tag (e.g. `0.3.59`). Used with `connector_name` to resolve the version UUID."
    },
    "days": {
      "default": 7,
      "description": "Number of days to look back (default: 7)",
      "type": "integer"
    },
    "limit": {
      "default": 100,
      "description": "Maximum number of results (default: 100)",
      "type": "integer"
    },
    "successful_only": {
      "default": false,
      "description": "If `True`, only return successful syncs (default: `False`)",
      "type": "boolean"
    }
  },
  "type": "object"
}

Show output JSON schema

{
  "properties": {
    "result": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "type": "object",
  "x-fastmcp-wrap-result": true
}

query_prod_workspace_info

Get workspace information including dataplane group.

Returns details about a specific workspace, including which dataplane (region) it belongs to. Useful for determining if a workspace is in the EU region for filtering purposes.

Returns dict with keys: workspace_id, workspace_name, slug, organization_id, dataplane_group_id, dataplane_name, created_at, tombstone Or None if workspace not found.

Parameters:

Name Type Required Default Description
workspace_id string | enum("266ebdfe-0d7b-4540-9817-de7e4505ba61") yes — Workspace UUID or alias to look up. Accepts '@devin-ai-sandbox' as an alias for the Devin AI sandbox workspace.

Show input JSON schema

{
  "additionalProperties": false,
  "properties": {
    "workspace_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "description": "Workspace ID aliases that can be used in place of UUIDs.\n\nEach member's name is the alias (e.g., \"@devin-ai-sandbox\") and its value\nis the actual workspace UUID. Use `WorkspaceAliasEnum.resolve()` to\nresolve aliases to actual IDs.",
          "enum": [
            "266ebdfe-0d7b-4540-9817-de7e4505ba61"
          ],
          "type": "string"
        }
      ],
      "description": "Workspace UUID or alias to look up. Accepts '@devin-ai-sandbox' as an alias for the Devin AI sandbox workspace."
    }
  },
  "required": [
    "workspace_id"
  ],
  "type": "object"
}

Show output JSON schema

{
  "properties": {
    "result": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "result"
  ],
  "type": "object",
  "x-fastmcp-wrap-result": true
}

query_prod_workspaces

Search workspaces by name substring or email domain.

At least one of name_contains or email_domain must be provided. When name_contains is given, performs a case-insensitive substring match on workspace name and slug. When email_domain is given, matches workspaces by user email domain.

The returned organization IDs can be used with other tools like query_prod_connections_by_connector to find connections within those organizations for safe testing.

Parameters:

Name Type Required Default Description
name_contains string | null no null Case-insensitive substring to search for in workspace name or slug. For example, 'acme' will match workspaces named 'Acme Staging'.
email_domain string | null no null Email domain to search for (e.g., 'motherduck.com'). Do not include the '@' symbol.
limit integer no 100 Maximum number of workspaces to return (default: 100)

Show input JSON schema

{
  "additionalProperties": false,
  "properties": {
    "name_contains": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Case-insensitive substring to search for in workspace name or slug. For example, 'acme' will match workspaces named 'Acme Staging'."
    },
    "email_domain": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Email domain to search for (e.g., 'motherduck.com'). Do not include the '@' symbol."
    },
    "limit": {
      "default": 100,
      "description": "Maximum number of workspaces to return (default: 100)",
      "type": "integer"
    }
  },
  "type": "object"
}

Show output JSON schema

{
  "description": "Result of searching workspaces by name or email domain.",
  "properties": {
    "name_contains": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The name substring that was searched for"
    },
    "email_domain": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "The email domain that was searched for (e.g., 'motherduck.com')"
    },
    "total_workspaces_found": {
      "description": "Total number of workspaces matching",
      "type": "integer"
    },
    "unique_organization_ids": {
      "description": "List of unique organization IDs found",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "workspaces": {
      "description": "List of matching workspaces",
      "items": {
        "description": "Information about a workspace.",
        "properties": {
          "organization_id": {
            "description": "The organization UUID",
            "type": "string"
          },
          "workspace_id": {
            "description": "The workspace UUID",
            "type": "string"
          },
          "workspace_name": {
            "description": "The name of the workspace",
            "type": "string"
          },
          "slug": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The workspace slug (URL-friendly identifier)"
          },
          "email": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The email address associated with the workspace"
          },
          "dataplane_group_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The dataplane group UUID (region)"
          },
          "dataplane_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The name of the dataplane (e.g., 'US', 'EU')"
          },
          "created_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "When the workspace was created"
          },
          "customer_tier": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Customer tier (TIER_0, TIER_1, TIER_2, or UNKNOWN). Enriched from the GCS tier cache."
          },
          "is_eu": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Whether the workspace is in the EU region (derived from dataplane_name)."
          }
        },
        "required": [
          "organization_id",
          "workspace_id",
          "workspace_name"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "total_workspaces_found",
    "unique_organization_ids",
    "workspaces"
  ],
  "type": "object"
}

   1# Copyright (c) 2025 Airbyte, Inc., all rights reserved.
   2"""MCP tools for querying the Airbyte Cloud Prod DB Replica.
   3
   4This module provides MCP tools that wrap the query functions from
   5airbyte_ops_mcp.prod_db_access.queries for use by AI agents.
   6
   7## MCP reference
   8
   9.. include:: ../../../docs/mcp-generated/prod_db_ops.md
  10    :start-line: 2
  11"""
  12
  13from __future__ import annotations
  14
  15__all__: list[str] = []
  16
  17import json
  18import uuid
  19from datetime import datetime, timedelta, timezone
  20from enum import StrEnum
  21from typing import Annotated, Any
  22
  23from airbyte.exceptions import PyAirbyteInputError
  24from fastmcp import FastMCP
  25from fastmcp_extensions import mcp_tool, register_mcp_tools
  26from pydantic import BaseModel, Field
  27
  28from airbyte_ops_mcp.cloud_admin.registry_lookup import (
  29    resolve_canonical_name_to_definition_id,
  30)
  31from airbyte_ops_mcp.constants import OrganizationAliasEnum, WorkspaceAliasEnum
  32from airbyte_ops_mcp.prod_db_access.queries import (
  33    is_source_connector,
  34    query_actor_population_by_org,
  35    query_actors_pinned_to_version,
  36    query_connection_sync_activity_from_prod,
  37    query_connections_by_connector,
  38    query_connections_by_destination_connector,
  39    query_connections_by_stream,
  40    query_connector_rollouts,
  41    query_connector_versions,
  42    query_dataplanes_list,
  43    query_destination_connection_stats,
  44    query_failed_sync_attempts_for_connector,
  45    query_new_connector_releases,
  46    query_org_admin_contacts,
  47    query_org_connector_pins,
  48    query_org_pin_stats,
  49    query_org_user_last_connection_events,
  50    query_recent_syncs_for_connector,
  51    query_source_connection_stats,
  52    query_syncs_for_connector_version,
  53    query_version_actor_health,
  54    query_versions_with_pins,
  55    query_workspace_info,
  56    query_workspaces_by_email_domain,
  57    resolve_version_id_by_tag,
  58    resolve_version_info,
  59    search_organizations,
  60    search_workspaces,
  61)
  62from airbyte_ops_mcp.tier_cache import (
  63    TierFilter,
  64    TierSummary,
  65    enrich_rows_by_org,
  66    filter_rows_by_tier,
  67    get_org_tiers,
  68    tier_source_warnings,
  69)
  70from airbyte_ops_mcp.version_summaries import (
  71    summarize_population,
  72    summarize_version_health,
  73)
  74
  75
  76class StatusFilter(StrEnum):
  77    """Filter for job status in sync queries."""
  78
  79    ALL = "all"
  80    SUCCEEDED = "succeeded"
  81    FAILED = "failed"
  82
  83
  84# Cloud UI base URL for building connection URLs
  85CLOUD_UI_BASE_URL = "https://cloud.airbyte.com"
  86
  87
  88def _validate_sync_activity_scope(
  89    *,
  90    organization_id: str | None,
  91    workspace_id: str | None,
  92    connection_ids: list[str] | None,
  93) -> None:
  94    """Require at least one explicit scope filter for sync activity queries."""
  95    if organization_id or workspace_id or connection_ids:
  96        return
  97    raise PyAirbyteInputError(
  98        message=(
  99            "Provide at least one scope filter: `organization_id`, `workspace_id`, "
 100            "or `connection_ids`."
 101        ),
 102        context={
 103            "organization_id": organization_id,
 104            "workspace_id": workspace_id,
 105            "connection_ids": connection_ids,
 106        },
 107    )
 108
 109
 110def _validate_sync_activity_window(
 111    *,
 112    start_at: datetime,
 113    end_at: datetime,
 114) -> tuple[datetime, datetime]:
 115    """Validate that `start_at` and `end_at` describe a usable window.
 116
 117    Returns the timestamps normalized to UTC. Raises `PyAirbyteInputError` for
 118    naive timestamps or inverted ranges. No clock-relative caps are enforced
 119    here; the caller is trusted to choose a sensible window.
 120    """
 121    if start_at.tzinfo is None or end_at.tzinfo is None:
 122        raise PyAirbyteInputError(
 123            message="`start_at` and `end_at` must include timezone information.",
 124            context={
 125                "start_at": start_at.isoformat(),
 126                "end_at": end_at.isoformat(),
 127            },
 128        )
 129
 130    normalized_start = start_at.astimezone(timezone.utc)
 131    normalized_end = end_at.astimezone(timezone.utc)
 132
 133    if normalized_start >= normalized_end:
 134        raise PyAirbyteInputError(
 135            message="`start_at` must be earlier than `end_at`.",
 136            context={
 137                "start_at": normalized_start.isoformat(),
 138                "end_at": normalized_end.isoformat(),
 139            },
 140        )
 141    return normalized_start, normalized_end
 142
 143
 144# =============================================================================
 145# Pydantic Models for MCP Tool Responses
 146# =============================================================================
 147
 148
 149class OrganizationSearchHit(BaseModel):
 150    """A single organization returned by a name/email search."""
 151
 152    organization_id: str = Field(description="The organization UUID")
 153    organization_name: str = Field(description="The name of the organization")
 154    email: str | None = Field(
 155        default=None, description="The email address associated with the organization"
 156    )
 157    customer_tier: str | None = Field(
 158        default=None,
 159        description="Customer tier (TIER_0, TIER_1, TIER_2, or UNKNOWN). Enriched from the GCS tier cache.",
 160    )
 161
 162
 163class OrganizationSearchResult(BaseModel):
 164    """Result of searching organizations by name substring."""
 165
 166    name_contains: str = Field(description="The search substring that was used")
 167    total_found: int = Field(description="Total number of organizations matching")
 168    organizations: list[OrganizationSearchHit] = Field(
 169        description="List of matching organizations"
 170    )
 171
 172
 173class WorkspaceInfo(BaseModel):
 174    """Information about a workspace."""
 175
 176    organization_id: str = Field(description="The organization UUID")
 177    workspace_id: str = Field(description="The workspace UUID")
 178    workspace_name: str = Field(description="The name of the workspace")
 179    slug: str | None = Field(
 180        default=None, description="The workspace slug (URL-friendly identifier)"
 181    )
 182    email: str | None = Field(
 183        default=None, description="The email address associated with the workspace"
 184    )
 185    dataplane_group_id: str | None = Field(
 186        default=None, description="The dataplane group UUID (region)"
 187    )
 188    dataplane_name: str | None = Field(
 189        default=None, description="The name of the dataplane (e.g., 'US', 'EU')"
 190    )
 191    created_at: datetime | None = Field(
 192        default=None, description="When the workspace was created"
 193    )
 194    customer_tier: str | None = Field(
 195        default=None,
 196        description="Customer tier (TIER_0, TIER_1, TIER_2, or UNKNOWN). Enriched from the GCS tier cache.",
 197    )
 198    is_eu: bool | None = Field(
 199        default=None,
 200        description="Whether the workspace is in the EU region (derived from dataplane_name).",
 201    )
 202
 203
 204class WorkspaceSearchResult(BaseModel):
 205    """Result of searching workspaces by name or email domain."""
 206
 207    name_contains: str | None = Field(
 208        default=None, description="The name substring that was searched for"
 209    )
 210    email_domain: str | None = Field(
 211        default=None,
 212        description="The email domain that was searched for (e.g., 'motherduck.com')",
 213    )
 214    total_workspaces_found: int = Field(
 215        description="Total number of workspaces matching"
 216    )
 217    unique_organization_ids: list[str] = Field(
 218        description="List of unique organization IDs found"
 219    )
 220    workspaces: list[WorkspaceInfo] = Field(description="List of matching workspaces")
 221
 222
 223# Keep backward-compatible alias for any external references
 224WorkspacesByEmailDomainResult = WorkspaceSearchResult
 225
 226
 227class LatestAttemptBreakdown(BaseModel):
 228    """Breakdown of connections by latest attempt status."""
 229
 230    succeeded: int = Field(
 231        default=0, description="Connections where latest attempt succeeded"
 232    )
 233    failed: int = Field(
 234        default=0, description="Connections where latest attempt failed"
 235    )
 236    cancelled: int = Field(
 237        default=0, description="Connections where latest attempt was cancelled"
 238    )
 239    running: int = Field(
 240        default=0, description="Connections where latest attempt is still running"
 241    )
 242    unknown: int = Field(
 243        default=0,
 244        description="Connections with no recent attempts in the lookback window",
 245    )
 246
 247
 248class VersionPinStats(BaseModel):
 249    """Stats for connections pinned to a specific version."""
 250
 251    pinned_version_id: str | None = Field(
 252        description="The connector version UUID (None for unpinned connections)"
 253    )
 254    docker_image_tag: str | None = Field(
 255        default=None, description="The docker image tag for this version"
 256    )
 257    total_connections: int = Field(description="Total number of connections")
 258    enabled_connections: int = Field(
 259        description="Number of enabled (active status) connections"
 260    )
 261    active_connections: int = Field(
 262        description="Number of connections with recent sync activity"
 263    )
 264    latest_attempt: LatestAttemptBreakdown = Field(
 265        description="Breakdown by latest attempt status"
 266    )
 267
 268
 269class ConnectorConnectionStats(BaseModel):
 270    """Aggregate connection stats for a connector."""
 271
 272    connector_definition_id: str = Field(description="The connector definition UUID")
 273    connector_type: str = Field(description="'source' or 'destination'")
 274    canonical_name: str | None = Field(
 275        default=None, description="The canonical connector name if resolved"
 276    )
 277    total_connections: int = Field(
 278        description="Total number of non-deprecated connections"
 279    )
 280    enabled_connections: int = Field(
 281        description="Number of enabled (active status) connections"
 282    )
 283    active_connections: int = Field(
 284        description="Number of connections with recent sync activity"
 285    )
 286    pinned_connections: int = Field(
 287        description="Number of connections with explicit version pins"
 288    )
 289    unpinned_connections: int = Field(
 290        description="Number of connections on default version"
 291    )
 292    latest_attempt: LatestAttemptBreakdown = Field(
 293        description="Overall breakdown by latest attempt status"
 294    )
 295    by_version: list[VersionPinStats] = Field(
 296        description="Stats broken down by pinned version"
 297    )
 298
 299
 300class ConnectorConnectionStatsResponse(BaseModel):
 301    """Response containing connection stats for multiple connectors."""
 302
 303    sources: list[ConnectorConnectionStats] = Field(
 304        default_factory=list, description="Stats for source connectors"
 305    )
 306    destinations: list[ConnectorConnectionStats] = Field(
 307        default_factory=list, description="Stats for destination connectors"
 308    )
 309    lookback_days: int = Field(
 310        description="Lookback window used for 'active' connections"
 311    )
 312    generated_at: datetime = Field(description="When this response was generated")
 313
 314
 315class OrgAdminContact(BaseModel):
 316    """An organization or selected-workspace administrator contact."""
 317
 318    user_id: str = Field(description="The Airbyte user UUID.")
 319    name: str | None = Field(default=None, description="The administrator's name.")
 320    email: str | None = Field(
 321        default=None, description="The administrator's email address."
 322    )
 323    status: str | None = Field(default=None, description="The user's status.")
 324    is_org_admin: bool = Field(description="Whether the user is an Org Admin.")
 325    admin_workspace_ids: list[str] = Field(
 326        description="Sorted workspace UUIDs where the user is a Workspace Admin."
 327    )
 328    user_created_at: datetime | None = Field(
 329        default=None, description="When the user account was created."
 330    )
 331    user_updated_at: datetime | None = Field(
 332        default=None, description="When the user account was last updated."
 333    )
 334    last_connection_event_at: datetime | None = Field(
 335        default=None,
 336        description="Latest user-attributed connection timeline event in the activity window.",
 337    )
 338
 339
 340class OrgAdminContactsResponse(BaseModel):
 341    """Organization administrator contacts and recent user activity."""
 342
 343    organization_id: str = Field(description="The organization UUID.")
 344    customer_tier: str = Field(
 345        description="Organization customer tier, included for awareness only."
 346    )
 347    tier_warnings: list[str] = Field(
 348        default_factory=list,
 349        description="Warnings raised while resolving the organization customer tier.",
 350    )
 351    activity_lookback_days: int = Field(
 352        description="Number of days used to look back for connection activity."
 353    )
 354    admins: list[OrgAdminContact] = Field(
 355        description="Administrators ordered by Airbyte user UUID."
 356    )
 357
 358
 359def _opt_str(value: Any) -> str | None:
 360    """Convert a nullable value to str, returning None if the value is None/falsy."""
 361    return str(value) if value else None
 362
 363
 364@mcp_tool(
 365    read_only=True,
 366    idempotent=True,
 367)
 368def query_prod_org_admin_contacts(
 369    organization_id: Annotated[
 370        str,
 371        Field(description="Organization UUID whose direct Org Admins to find."),
 372    ],
 373    workspace_ids: Annotated[
 374        list[str],
 375        Field(
 376            description=(
 377                "Workspace UUIDs whose direct Workspace Admins to include. "
 378                "Only these workspaces contribute Workspace Admins."
 379            ),
 380        ),
 381    ] = [],  # noqa: B006
 382    activity_lookback_days: Annotated[
 383        int,
 384        Field(
 385            description="Days to look back for user-attributed connection activity.",
 386            ge=1,
 387            le=365,
 388        ),
 389    ] = 90,
 390) -> OrgAdminContactsResponse:
 391    """Find Org Admins and Workspace Admins of the given workspaces.
 392
 393    Activity is each user's latest user-attributed connection timeline event in
 394    this organization within the lookback window. Emails are returned because
 395    callers need them to CC customers; never log them. Only direct user grants
 396    are included; group-granted permissions are not queried. The org's
 397    `customer_tier` is included for awareness only; outreach must still reach
 398    every affected organization regardless of tier.
 399    """
 400    normalized_organization_id = _require_organization_id(organization_id)
 401    normalized_workspace_ids: list[str] = []
 402    for workspace_id in workspace_ids:
 403        try:
 404            normalized_workspace_ids.append(str(uuid.UUID(workspace_id.strip())))
 405        except (AttributeError, ValueError) as exc:
 406            raise PyAirbyteInputError(
 407                message=f"`workspace_ids` contains an invalid workspace UUID: {workspace_id!r}.",
 408            ) from exc
 409
 410    tier_result = get_org_tiers(
 411        organization_ids=[normalized_organization_id],
 412        allow_degraded=True,
 413    )[0]
 414    admin_rows = query_org_admin_contacts(
 415        normalized_organization_id,
 416        normalized_workspace_ids,
 417    )
 418    admins_by_user_id: dict[str, OrgAdminContact] = {}
 419    for row in admin_rows:
 420        user_id = str(row["user_id"])
 421        admin = admins_by_user_id.get(user_id)
 422        if admin is None:
 423            admin = OrgAdminContact(
 424                user_id=user_id,
 425                name=row["user_name"],
 426                email=row["user_email"],
 427                status=row["user_status"],
 428                is_org_admin=False,
 429                admin_workspace_ids=[],
 430                user_created_at=row["user_created_at"],
 431                user_updated_at=row["user_updated_at"],
 432            )
 433            admins_by_user_id[user_id] = admin
 434
 435        if row["admin_role"] == "organization_admin":
 436            admin.is_org_admin = True
 437        elif row["admin_role"] == "workspace_admin" and row["workspace_id"] is not None:
 438            workspace_id = str(row["workspace_id"])
 439            if workspace_id not in admin.admin_workspace_ids:
 440                admin.admin_workspace_ids.append(workspace_id)
 441
 442    if admins_by_user_id:
 443        activity_rows = query_org_user_last_connection_events(
 444            normalized_organization_id,
 445            sorted(admins_by_user_id),
 446            datetime.now(timezone.utc) - timedelta(days=activity_lookback_days),
 447        )
 448        for row in activity_rows:
 449            user_id = str(row["user_id"])
 450            if user_id in admins_by_user_id:
 451                admins_by_user_id[user_id].last_connection_event_at = row[
 452                    "last_connection_event_at"
 453                ]
 454
 455    admins = [admins_by_user_id[user_id] for user_id in sorted(admins_by_user_id)]
 456    for admin in admins:
 457        admin.admin_workspace_ids.sort()
 458    return OrgAdminContactsResponse(
 459        organization_id=normalized_organization_id,
 460        customer_tier=str(tier_result.customer_tier),
 461        tier_warnings=tier_source_warnings(tier_result.source_health),
 462        activity_lookback_days=activity_lookback_days,
 463        admins=admins,
 464    )
 465
 466
 467@mcp_tool(
 468    read_only=True,
 469    idempotent=True,
 470)
 471def query_prod_dataplanes() -> list[dict[str, Any]]:
 472    """List all dataplane groups with workspace counts.
 473
 474    Returns information about all active dataplane groups in Airbyte Cloud,
 475    including the number of workspaces in each. Useful for understanding
 476    the distribution of workspaces across regions (US, US-Central, EU).
 477
 478    Returns list of dicts with keys: dataplane_group_id, dataplane_name,
 479    organization_id, enabled, tombstone, created_at, workspace_count
 480    """
 481    return query_dataplanes_list()
 482
 483
 484@mcp_tool(
 485    read_only=True,
 486    idempotent=True,
 487)
 488def query_prod_workspace_info(
 489    workspace_id: Annotated[
 490        str | WorkspaceAliasEnum,
 491        Field(
 492            description="Workspace UUID or alias to look up. "
 493            "Accepts '@devin-ai-sandbox' as an alias for the Devin AI sandbox workspace."
 494        ),
 495    ],
 496) -> dict[str, Any] | None:
 497    """Get workspace information including dataplane group.
 498
 499    Returns details about a specific workspace, including which dataplane
 500    (region) it belongs to. Useful for determining if a workspace is in
 501    the EU region for filtering purposes.
 502
 503    Returns dict with keys: workspace_id, workspace_name, slug, organization_id,
 504    dataplane_group_id, dataplane_name, created_at, tombstone
 505    Or None if workspace not found.
 506    """
 507    # Resolve workspace ID alias (workspace_id is required, so resolved value is never None)
 508    resolved_workspace_id = WorkspaceAliasEnum.resolve(workspace_id)
 509    assert resolved_workspace_id is not None  # Type narrowing: workspace_id is required
 510
 511    return query_workspace_info(resolved_workspace_id)
 512
 513
 514@mcp_tool(
 515    read_only=True,
 516    idempotent=True,
 517)
 518def query_prod_connector_versions(
 519    connector_definition_id: Annotated[
 520        str,
 521        Field(description="Connector definition UUID to list versions for"),
 522    ],
 523) -> list[dict[str, Any]]:
 524    """List all versions for a connector definition.
 525
 526    Returns all published versions of a connector, ordered by last_published
 527    date descending. Useful for understanding version history and finding
 528    specific version IDs for pinning or rollout monitoring.
 529
 530    Returns list of dicts with keys: version_id, docker_image_tag, docker_repository,
 531    release_stage, support_level, cdk_version, language, last_published, release_date
 532    """
 533    return query_connector_versions(connector_definition_id)
 534
 535
 536@mcp_tool(
 537    read_only=True,
 538    idempotent=True,
 539)
 540def query_prod_new_connector_releases(
 541    days: Annotated[
 542        int,
 543        Field(description="Number of days to look back (default: 7)", default=7),
 544    ] = 7,
 545    limit: Annotated[
 546        int,
 547        Field(description="Maximum number of results (default: 100)", default=100),
 548    ] = 100,
 549) -> list[dict[str, Any]]:
 550    """List recently published connector versions.
 551
 552    Returns connector versions published within the specified number of days.
 553    Uses last_published timestamp which reflects when the version was actually
 554    deployed to the registry (not the changelog date).
 555
 556    Returns list of dicts with keys: version_id, connector_definition_id, docker_repository,
 557    docker_image_tag, last_published, release_date, release_stage, support_level,
 558    cdk_version, language, created_at
 559    """
 560    return query_new_connector_releases(days=days, limit=limit)
 561
 562
 563@mcp_tool(
 564    read_only=True,
 565    idempotent=True,
 566)
 567def query_prod_actors_by_pinned_connector_version(
 568    connector_version_id: Annotated[
 569        str,
 570        Field(description="Connector version UUID to find pinned instances for"),
 571    ],
 572) -> list[dict[str, Any]]:
 573    """List actors (sources/destinations) effectively pinned to a specific connector version.
 574
 575    Returns all actors that are effectively pinned to a specific connector version,
 576    considering all scope levels: actor-level pins, workspace-level pins, and
 577    organization-level pins (with actor > workspace > organization precedence).
 578    Useful for monitoring rollouts and understanding which customers are affected.
 579
 580    The actor_id field is the actor ID (superset of source_id/destination_id).
 581
 582    Returns list of dicts with keys: actor_id, connector_definition_id, origin_type,
 583    origin, description, created_at, expires_at, pin_scope_type, actor_name,
 584    workspace_id, workspace_name, organization_id, dataplane_group_id, dataplane_name
 585
 586    pin_scope_type is 'actor', 'workspace', or 'organization' indicating which scope
 587    level the effective pin came from.
 588    """
 589    return query_actors_pinned_to_version(connector_version_id)
 590
 591
 592@mcp_tool(
 593    read_only=True,
 594    idempotent=True,
 595)
 596def query_prod_recent_syncs_for_connector_version(
 597    connector_version_id: Annotated[
 598        str | None,
 599        Field(
 600            description=(
 601                "Connector version UUID. Provide this OR "
 602                "connector_name + connector_version."
 603            ),
 604            default=None,
 605        ),
 606    ] = None,
 607    connector_name: Annotated[
 608        str | None,
 609        Field(
 610            description=(
 611                "Canonical connector name (e.g. `source-pokeapi`, "
 612                "`destination-duckdb`). Used with `connector_version` to "
 613                "resolve the version UUID."
 614            ),
 615            default=None,
 616        ),
 617    ] = None,
 618    connector_version: Annotated[
 619        str | None,
 620        Field(
 621            description=(
 622                "Semver version tag (e.g. `0.3.59`). "
 623                "Used with `connector_name` to resolve the version UUID."
 624            ),
 625            default=None,
 626        ),
 627    ] = None,
 628    days: Annotated[
 629        int,
 630        Field(description="Number of days to look back (default: 7)", default=7),
 631    ] = 7,
 632    limit: Annotated[
 633        int,
 634        Field(description="Maximum number of results (default: 100)", default=100),
 635    ] = 100,
 636    successful_only: Annotated[
 637        bool,
 638        Field(
 639            description="If `True`, only return successful syncs (default: `False`)",
 640            default=False,
 641        ),
 642    ] = False,
 643) -> list[dict[str, Any]]:
 644    """List sync jobs that were run with a specific connector version.
 645
 646    Works for both source and destination connectors. Automatically detects
 647    the connector type from the version metadata and uses the appropriate
 648    query variant.
 649
 650    Accepts either `connector_version_id` (UUID) or `connector_name` +
 651    `connector_version` (e.g. `source-pokeapi` + `0.3.59`). When using
 652    name + version, the `docker_repository` is derived from the canonical
 653    name (e.g. `source-pokeapi` → `airbyte/source-pokeapi`).
 654
 655    Filters on the version stamped into `jobs.config` at job-creation time,
 656    not the current pin state. This avoids false positives (pre-pin syncs
 657    counted as RC) and false negatives (post-unpin syncs missed).
 658
 659    Pin columns (`pin_origin_type`, `pin_origin`, `pin_scope_type`) are
 660    still included as informational output but are not used for filtering.
 661
 662    Returns list of dicts with keys: `job_id`, `connection_id`, `job_status`,
 663    `started_at`, `job_updated_at`, `connection_name`, `actor_id`, `actor_name`,
 664    `actor_definition_id`, `source_definition_version_id`,
 665    `destination_definition_version_id`, `pin_origin_type`,
 666    `pin_origin`, `pin_scope_type`, `workspace_id`, `workspace_name`,
 667    `organization_id`, `dataplane_group_id`, `dataplane_name`.
 668    """
 669    # Resolve inputs to a version UUID and connector type.
 670    if connector_version_id is not None:
 671        version_info = resolve_version_info(connector_version_id)
 672        docker_repository = version_info["docker_repository"]
 673    elif connector_name is not None and connector_version is not None:
 674        # Derive docker_repository from canonical name.
 675        docker_repository = f"airbyte/{connector_name}"
 676        version_info = resolve_version_id_by_tag(
 677            docker_repository=docker_repository,
 678            docker_image_tag=connector_version,
 679        )
 680        connector_version_id = version_info["version_id"]
 681    else:
 682        raise PyAirbyteInputError(
 683            message=(
 684                "Provide either `connector_version_id` or both "
 685                "`connector_name` and `connector_version`."
 686            ),
 687        )
 688
 689    is_destination = not is_source_connector(docker_repository)
 690    return query_syncs_for_connector_version(
 691        connector_version_id,
 692        is_destination=is_destination,
 693        days=days,
 694        limit=limit,
 695        successful_only=successful_only,
 696    )
 697
 698
 699@mcp_tool(
 700    read_only=True,
 701    idempotent=True,
 702    open_world=True,
 703)
 704def query_prod_recent_syncs_for_connector(
 705    source_definition_id: Annotated[
 706        str | None,
 707        Field(
 708            description=(
 709                "Source connector definition ID (UUID) to search for. "
 710                "Provide this OR source_canonical_name OR destination_definition_id "
 711                "OR destination_canonical_name (exactly one required). "
 712                "Example: 'afa734e4-3571-11ec-991a-1e0031268139' for YouTube Analytics."
 713            ),
 714            default=None,
 715        ),
 716    ],
 717    source_canonical_name: Annotated[
 718        str | None,
 719        Field(
 720            description=(
 721                "Canonical source connector name to search for. "
 722                "Provide this OR source_definition_id OR destination_definition_id "
 723                "OR destination_canonical_name (exactly one required). "
 724                "Examples: 'source-youtube-analytics', 'YouTube Analytics'."
 725            ),
 726            default=None,
 727        ),
 728    ],
 729    destination_definition_id: Annotated[
 730        str | None,
 731        Field(
 732            description=(
 733                "Destination connector definition ID (UUID) to search for. "
 734                "Provide this OR destination_canonical_name OR source_definition_id "
 735                "OR source_canonical_name (exactly one required). "
 736                "Example: '94bd199c-2ff0-4aa2-b98e-17f0acb72610' for DuckDB."
 737            ),
 738            default=None,
 739        ),
 740    ],
 741    destination_canonical_name: Annotated[
 742        str | None,
 743        Field(
 744            description=(
 745                "Canonical destination connector name to search for. "
 746                "Provide this OR destination_definition_id OR source_definition_id "
 747                "OR source_canonical_name (exactly one required). "
 748                "Examples: 'destination-duckdb', 'DuckDB'."
 749            ),
 750            default=None,
 751        ),
 752    ],
 753    status_filter: Annotated[
 754        StatusFilter,
 755        Field(
 756            description=(
 757                "Filter by job status: 'all' (default), 'succeeded', or 'failed'. "
 758                "Use 'succeeded' to find healthy connections with recent successful syncs. "
 759                "Use 'failed' to find connections with recent failures."
 760            ),
 761            default=StatusFilter.ALL,
 762        ),
 763    ],
 764    organization_id: Annotated[
 765        str | OrganizationAliasEnum | None,
 766        Field(
 767            description=(
 768                "Optional organization ID (UUID) or alias to filter results. "
 769                "If provided, only syncs from this organization will be returned. "
 770                "Accepts '@airbyte-internal' as an alias for the Airbyte internal org."
 771            ),
 772            default=None,
 773        ),
 774    ],
 775    lookback_days: Annotated[
 776        int,
 777        Field(description="Number of days to look back (default: 7)", default=7),
 778    ],
 779    limit: Annotated[
 780        int,
 781        Field(description="Maximum number of results (default: 100)", default=100),
 782    ],
 783    customer_tier_filter: Annotated[
 784        TierFilter,
 785        Field(
 786            description=(
 787                "Required tier filter: 'TIER_0', 'TIER_1', 'TIER_2', 'UNKNOWN', or 'ALL'. "
 788                "Filters results to only include connections belonging to organizations "
 789                "in the specified tier. Use 'ALL' to include all tiers."
 790            ),
 791        ),
 792    ] = "TIER_2",
 793    *,
 794    exclude_pinned: Annotated[
 795        bool,
 796        Field(
 797            description=(
 798                "If True, exclude syncs for actors that are already pinned to a "
 799                "specific version (at any scope level: actor, workspace, or organization). "
 800                "Useful for 'prove fix' workflows where you want to find unpinned "
 801                "connections for live testing. Default: False (include all syncs)."
 802            ),
 803            default=False,
 804        ),
 805    ],
 806    enabled_schedules_only: Annotated[
 807        bool,
 808        Field(
 809            description=(
 810                "If True, only return syncs for connections that are both active "
 811                "(not paused/inactive) and on an automated sync schedule "
 812                "(not manual-trigger-only). Useful for canary workflows where "
 813                "you need connections that will produce organic syncs during a "
 814                "monitoring window. Default: False (include all connections)."
 815            ),
 816            default=False,
 817        ),
 818    ],
 819) -> list[dict[str, Any]]:
 820    """List recent sync jobs for ALL actors using a connector type.
 821
 822    This tool finds all actors with the given connector definition and returns their
 823    recent sync jobs, regardless of whether they have explicit version pins. It filters
 824    out deleted actors, deleted workspaces, and deprecated connections.
 825
 826    Results are always enriched with customer_tier and is_eu fields.
 827    The customer_tier_filter parameter is required to ensure tier-aware querying.
 828
 829    Use this tool to:
 830    - Find healthy connections with recent successful syncs (status_filter='succeeded')
 831    - Investigate connector issues across all users (status_filter='failed')
 832    - Get an overview of all recent sync activity (status_filter='all')
 833
 834    Set `exclude_pinned=True` to filter out syncs for actors that are already pinned to a
 835    specific version. This is useful for 'prove fix' live connection testing workflows
 836    where you want to find unpinned connections to test against.
 837
 838    Set `enabled_schedules_only=True` to restrict results to connections that are both
 839    enabled (status='active') and on an automated schedule (not manual-trigger-only).
 840    This is useful for canary prerelease workflows where you need connections that
 841    will run organically during the monitoring window.
 842
 843    Supports both SOURCE and DESTINATION connectors. Provide exactly one of:
 844    source_definition_id, source_canonical_name, destination_definition_id,
 845    or destination_canonical_name.
 846
 847    Key fields in results:
 848    - job_status: 'succeeded', 'failed', 'cancelled', etc.
 849    - connection_id, connection_name: The connection that ran the sync
 850    - actor_id, actor_name: The source or destination actor
 851    - customer_tier: TIER_0, TIER_1, TIER_2, or UNKNOWN
 852    - is_eu: Whether the workspace is in the EU region
 853    - pin_origin_type, pin_origin, pinned_version_id: Version pin context (NULL if not pinned)
 854    - pin_scope_type: 'actor', 'workspace', or 'organization' (NULL if not pinned)
 855    """
 856    # Validate that exactly one connector parameter is provided
 857    provided_params = [
 858        source_definition_id,
 859        source_canonical_name,
 860        destination_definition_id,
 861        destination_canonical_name,
 862    ]
 863    num_provided = sum(p is not None for p in provided_params)
 864    if num_provided != 1:
 865        raise PyAirbyteInputError(
 866            message=(
 867                "Exactly one of source_definition_id, source_canonical_name, "
 868                "destination_definition_id, or destination_canonical_name must be provided."
 869            ),
 870        )
 871
 872    # Determine if this is a destination connector
 873    is_destination = (
 874        destination_definition_id is not None or destination_canonical_name is not None
 875    )
 876
 877    # Resolve canonical name to definition ID if needed
 878    resolved_definition_id: str
 879    if source_canonical_name:
 880        resolved_definition_id = resolve_canonical_name_to_definition_id(
 881            canonical_name=source_canonical_name,
 882        )
 883    elif destination_canonical_name:
 884        resolved_definition_id = resolve_canonical_name_to_definition_id(
 885            canonical_name=destination_canonical_name,
 886        )
 887    elif source_definition_id:
 888        resolved_definition_id = source_definition_id
 889    else:
 890        # We've validated exactly one param is provided, so this must be set
 891        assert destination_definition_id is not None
 892        resolved_definition_id = destination_definition_id
 893
 894    # Resolve organization ID alias
 895    resolved_organization_id = OrganizationAliasEnum.resolve(organization_id)
 896
 897    rows = query_recent_syncs_for_connector(
 898        connector_definition_id=resolved_definition_id,
 899        is_destination=is_destination,
 900        status_filter=status_filter,
 901        organization_id=resolved_organization_id,
 902        days=lookback_days,
 903        limit=limit,
 904        exclude_pinned=exclude_pinned,
 905        enabled_schedules_only=enabled_schedules_only,
 906    )
 907
 908    enriched = enrich_rows_by_org(
 909        rows=rows,
 910        allow_degraded=True,
 911    )
 912    return filter_rows_by_tier(enriched, customer_tier_filter)
 913
 914
 915@mcp_tool(
 916    read_only=True,
 917    idempotent=True,
 918    open_world=True,
 919)
 920def query_prod_failed_sync_attempts_for_connector(
 921    source_definition_id: Annotated[
 922        str | None,
 923        Field(
 924            description=(
 925                "Source connector definition ID (UUID) to search for. "
 926                "Provide this OR source_canonical_name OR destination_definition_id "
 927                "OR destination_canonical_name (exactly one required). "
 928                "Example: 'afa734e4-3571-11ec-991a-1e0031268139' for YouTube Analytics."
 929            ),
 930            default=None,
 931        ),
 932    ] = None,
 933    source_canonical_name: Annotated[
 934        str | None,
 935        Field(
 936            description=(
 937                "Canonical source connector name to search for. "
 938                "Provide this OR source_definition_id OR destination_definition_id "
 939                "OR destination_canonical_name (exactly one required). "
 940                "Examples: 'source-youtube-analytics', 'YouTube Analytics'."
 941            ),
 942            default=None,
 943        ),
 944    ] = None,
 945    destination_definition_id: Annotated[
 946        str | None,
 947        Field(
 948            description=(
 949                "Destination connector definition ID (UUID) to search for. "
 950                "Provide this OR destination_canonical_name OR source_definition_id "
 951                "OR source_canonical_name (exactly one required). "
 952                "Example: '94bd199c-2ff0-4aa2-b98e-17f0acb72610' for DuckDB."
 953            ),
 954            default=None,
 955        ),
 956    ] = None,
 957    destination_canonical_name: Annotated[
 958        str | None,
 959        Field(
 960            description=(
 961                "Canonical destination connector name to search for. "
 962                "Provide this OR destination_definition_id OR source_definition_id "
 963                "OR source_canonical_name (exactly one required). "
 964                "Examples: 'destination-duckdb', 'DuckDB'."
 965            ),
 966            default=None,
 967        ),
 968    ] = None,
 969    organization_id: Annotated[
 970        str | OrganizationAliasEnum | None,
 971        Field(
 972            description=(
 973                "Optional organization ID (UUID) or alias to filter results. "
 974                "If provided, only failed attempts from this organization will be returned. "
 975                "Accepts '@airbyte-internal' as an alias for the Airbyte internal org."
 976            ),
 977            default=None,
 978        ),
 979    ] = None,
 980    lookback_days: Annotated[
 981        int,
 982        Field(description="Number of days to look back (default: 7)", default=7),
 983    ] = 7,
 984    limit: Annotated[
 985        int,
 986        Field(description="Maximum number of results (default: 100)", default=100),
 987    ] = 100,
 988    customer_tier_filter: Annotated[
 989        TierFilter,
 990        Field(
 991            description=(
 992                "Required tier filter: 'TIER_0', 'TIER_1', 'TIER_2', 'UNKNOWN', or 'ALL'. "
 993                "Filters results to only include connections belonging to organizations "
 994                "in the specified tier. Use 'ALL' to include all tiers."
 995            ),
 996        ),
 997    ] = "TIER_2",
 998) -> list[dict[str, Any]]:
 999    """List failed sync attempts for ALL actors using a connector type.
1000
1001    This tool finds all actors with the given connector definition and returns their
1002    failed sync attempts, regardless of whether they have explicit version pins.
1003
1004    Results are always enriched with customer_tier and is_eu fields.
1005    The customer_tier_filter parameter is required to ensure tier-aware querying.
1006
1007    This is useful for investigating connector issues across all users. Use this when
1008    you want to find failures for a connector type regardless of which version users
1009    are on.
1010
1011    Supports both SOURCE and DESTINATION connectors. Provide exactly one of:
1012    source_definition_id, source_canonical_name, destination_definition_id,
1013    or destination_canonical_name.
1014
1015    Key fields in results:
1016    - failure_summary: JSON containing failure details including failureType and messages
1017    - customer_tier: TIER_0, TIER_1, TIER_2, or UNKNOWN
1018    - is_eu: Whether the workspace is in the EU region
1019    - pin_origin_type, pin_origin, pinned_version_id: Version pin context (NULL if not pinned)
1020    - pin_scope_type: 'actor', 'workspace', or 'organization' (NULL if not pinned)
1021    """
1022    provided_params = [
1023        source_definition_id,
1024        source_canonical_name,
1025        destination_definition_id,
1026        destination_canonical_name,
1027    ]
1028    if sum(p is not None for p in provided_params) != 1:
1029        raise PyAirbyteInputError(
1030            message=(
1031                "Exactly one of source_definition_id, source_canonical_name, "
1032                "destination_definition_id, or destination_canonical_name must be provided."
1033            ),
1034        )
1035
1036    is_destination = (
1037        destination_definition_id is not None or destination_canonical_name is not None
1038    )
1039    canonical_name = source_canonical_name or destination_canonical_name
1040    resolved_definition_id: str
1041    if canonical_name:
1042        resolved_definition_id = resolve_canonical_name_to_definition_id(
1043            canonical_name=canonical_name,
1044        )
1045    else:
1046        definition_id = source_definition_id or destination_definition_id
1047        assert definition_id is not None
1048        resolved_definition_id = definition_id
1049
1050    # Resolve organization ID alias
1051    resolved_organization_id = OrganizationAliasEnum.resolve(organization_id)
1052
1053    rows = query_failed_sync_attempts_for_connector(
1054        connector_definition_id=resolved_definition_id,
1055        organization_id=resolved_organization_id,
1056        days=lookback_days,
1057        limit=limit,
1058        is_destination=is_destination,
1059    )
1060    enriched = enrich_rows_by_org(
1061        rows=rows,
1062        allow_degraded=True,
1063    )
1064    return filter_rows_by_tier(enriched, customer_tier_filter)
1065
1066
1067@mcp_tool(
1068    read_only=True,
1069    idempotent=True,
1070    open_world=True,
1071)
1072def query_prod_connections_by_connector(
1073    source_definition_id: Annotated[
1074        str | None,
1075        Field(
1076            description=(
1077                "Source connector definition ID (UUID) to search for. "
1078                "Exactly one of source_definition_id, source_canonical_name, "
1079                "destination_definition_id, or destination_canonical_name is required. "
1080                "Example: 'afa734e4-3571-11ec-991a-1e0031268139' for YouTube Analytics."
1081            ),
1082            default=None,
1083        ),
1084    ] = None,
1085    source_canonical_name: Annotated[
1086        str | None,
1087        Field(
1088            description=(
1089                "Canonical source connector name to search for. "
1090                "Exactly one of source_definition_id, source_canonical_name, "
1091                "destination_definition_id, or destination_canonical_name is required. "
1092                "Examples: 'source-youtube-analytics', 'YouTube Analytics'."
1093            ),
1094            default=None,
1095        ),
1096    ] = None,
1097    destination_definition_id: Annotated[
1098        str | None,
1099        Field(
1100            description=(
1101                "Destination connector definition ID (UUID) to search for. "
1102                "Exactly one of source_definition_id, source_canonical_name, "
1103                "destination_definition_id, or destination_canonical_name is required. "
1104                "Example: 'e5c8e66c-a480-4a5e-9c0e-e8e5e4c5c5c5' for DuckDB."
1105            ),
1106            default=None,
1107        ),
1108    ] = None,
1109    destination_canonical_name: Annotated[
1110        str | None,
1111        Field(
1112            description=(
1113                "Canonical destination connector name to search for. "
1114                "Exactly one of source_definition_id, source_canonical_name, "
1115                "destination_definition_id, or destination_canonical_name is required. "
1116                "Examples: 'destination-duckdb', 'DuckDB'."
1117            ),
1118            default=None,
1119        ),
1120    ] = None,
1121    organization_id: Annotated[
1122        str | OrganizationAliasEnum | None,
1123        Field(
1124            description=(
1125                "Optional organization ID (UUID) or alias to filter results. "
1126                "If provided, only connections in this organization will be returned. "
1127                "Accepts '@airbyte-internal' as an alias for the Airbyte internal org."
1128            ),
1129            default=None,
1130        ),
1131    ] = None,
1132    limit: Annotated[
1133        int,
1134        Field(description="Maximum number of results (default: 1000)", default=1000),
1135    ] = 1000,
1136    customer_tier_filter: Annotated[
1137        TierFilter,
1138        Field(
1139            description=(
1140                "Required tier filter: 'TIER_0', 'TIER_1', 'TIER_2', 'UNKNOWN', or 'ALL'. "
1141                "Filters results to only include connections belonging to organizations "
1142                "in the specified tier. Use 'ALL' to include all tiers."
1143            ),
1144        ),
1145    ] = "TIER_2",
1146    *,
1147    exclude_pinned: Annotated[
1148        bool,
1149        Field(
1150            description=(
1151                "If True, exclude connections whose connector is already pinned to a "
1152                "specific version (at any scope level: actor, workspace, or organization). "
1153                "Useful for 'prove fix' workflows where you want to find unpinned "
1154                "connections for live testing. Default: False (include all connections)."
1155            ),
1156            default=False,
1157        ),
1158    ],
1159    enabled_schedules_only: Annotated[
1160        bool,
1161        Field(
1162            description=(
1163                "If True, only return connections that are both active "
1164                "(not paused/inactive) and on an automated sync schedule "
1165                "(not manual-trigger-only). Useful for canary workflows where "
1166                "you need connections that will produce organic syncs during a "
1167                "monitoring window. Default: False (include all connections)."
1168            ),
1169            default=False,
1170        ),
1171    ],
1172) -> list[dict[str, Any]]:
1173    """Search for all connections using a specific source or destination connector type.
1174
1175    This tool queries the Airbyte Cloud Prod DB Replica directly for fast results.
1176    It finds all connections where the source or destination connector matches the
1177    specified type, regardless of how the connector is named by users.
1178
1179    Results are always enriched with customer_tier and is_eu fields.
1180    The customer_tier_filter parameter is required to ensure tier-aware querying.
1181
1182    Optionally filter by organization_id to limit results to a specific organization.
1183    Use '@airbyte-internal' as an alias for the Airbyte internal organization.
1184
1185    Set `exclude_pinned=True` to filter out connections that are already pinned to a
1186    specific version. This is useful for 'prove fix' live connection testing workflows
1187    where you want to find unpinned connections to test against.
1188
1189    Set `enabled_schedules_only=True` to restrict results to connections that are both
1190    enabled (status='active') and on an automated schedule (not manual-trigger-only).
1191    This is useful for canary prerelease workflows where you need connections that
1192    will run organically during the monitoring window.
1193
1194    Returns a list of connection dicts with workspace context and clickable Cloud UI URLs.
1195    For source queries, returns: connection_id, connection_name, connection_url, source_id,
1196    source_name, source_definition_id, workspace_id, workspace_name, organization_id,
1197    dataplane_group_id, dataplane_name, pin_origin_type, pin_origin, pinned_version_id,
1198    pin_scope_type, customer_tier, is_eu.
1199    For destination queries, returns: connection_id, connection_name, connection_url,
1200    destination_id, destination_name, destination_definition_id, workspace_id,
1201    workspace_name, organization_id, dataplane_group_id, dataplane_name, pin_origin_type,
1202    pin_origin, pinned_version_id, pin_scope_type, customer_tier, is_eu.
1203
1204    pin_scope_type is 'actor', 'workspace', or 'organization' indicating which scope
1205    level the effective pin came from (NULL if not pinned).
1206    """
1207    # Validate that exactly one of the four connector parameters is provided
1208    provided_params = [
1209        source_definition_id,
1210        source_canonical_name,
1211        destination_definition_id,
1212        destination_canonical_name,
1213    ]
1214    num_provided = sum(p is not None for p in provided_params)
1215    if num_provided != 1:
1216        raise PyAirbyteInputError(
1217            message=(
1218                "Exactly one of source_definition_id, source_canonical_name, "
1219                "destination_definition_id, or destination_canonical_name must be provided."
1220            ),
1221        )
1222
1223    # Determine if this is a source or destination query and resolve the definition ID
1224    is_source_query = (
1225        source_definition_id is not None or source_canonical_name is not None
1226    )
1227    resolved_definition_id: str
1228
1229    if source_canonical_name:
1230        resolved_definition_id = resolve_canonical_name_to_definition_id(
1231            canonical_name=source_canonical_name,
1232        )
1233    elif source_definition_id:
1234        resolved_definition_id = source_definition_id
1235    elif destination_canonical_name:
1236        resolved_definition_id = resolve_canonical_name_to_definition_id(
1237            canonical_name=destination_canonical_name,
1238        )
1239    else:
1240        resolved_definition_id = destination_definition_id  # ty: ignore[invalid-assignment]
1241
1242    # Resolve organization ID alias
1243    resolved_organization_id = OrganizationAliasEnum.resolve(organization_id)
1244
1245    # Query the database based on connector type
1246    if is_source_query:
1247        rows = [
1248            {
1249                "organization_id": str(row.get("organization_id", "")),
1250                "workspace_id": str(row["workspace_id"]),
1251                "workspace_name": row.get("workspace_name", ""),
1252                "connection_id": str(row["connection_id"]),
1253                "connection_name": row.get("connection_name", ""),
1254                "connection_url": (
1255                    f"{CLOUD_UI_BASE_URL}/workspaces/{row['workspace_id']}"
1256                    f"/connections/{row['connection_id']}/status"
1257                ),
1258                "source_id": str(row["source_id"]),
1259                "source_name": row.get("source_name", ""),
1260                "source_definition_id": str(row["source_definition_id"]),
1261                "dataplane_group_id": str(row.get("dataplane_group_id", "")),
1262                "dataplane_name": row.get("dataplane_name", ""),
1263                "pin_origin_type": row.get("pin_origin_type"),
1264                "pin_origin": row.get("pin_origin"),
1265                "pinned_version_id": _opt_str(row.get("pinned_version_id")),
1266                "pin_scope_type": row.get("pin_scope_type"),
1267            }
1268            for row in query_connections_by_connector(
1269                connector_definition_id=resolved_definition_id,
1270                organization_id=resolved_organization_id,
1271                limit=limit,
1272                exclude_pinned=exclude_pinned,
1273                enabled_schedules_only=enabled_schedules_only,
1274            )
1275        ]
1276    else:
1277        # Destination query
1278        rows = [
1279            {
1280                "organization_id": str(row.get("organization_id", "")),
1281                "workspace_id": str(row["workspace_id"]),
1282                "workspace_name": row.get("workspace_name", ""),
1283                "connection_id": str(row["connection_id"]),
1284                "connection_name": row.get("connection_name", ""),
1285                "connection_url": (
1286                    f"{CLOUD_UI_BASE_URL}/workspaces/{row['workspace_id']}"
1287                    f"/connections/{row['connection_id']}/status"
1288                ),
1289                "destination_id": str(row["destination_id"]),
1290                "destination_name": row.get("destination_name", ""),
1291                "destination_definition_id": str(row["destination_definition_id"]),
1292                "dataplane_group_id": str(row.get("dataplane_group_id", "")),
1293                "dataplane_name": row.get("dataplane_name", ""),
1294                "pin_origin_type": row.get("pin_origin_type"),
1295                "pin_origin": row.get("pin_origin"),
1296                "pinned_version_id": _opt_str(row.get("pinned_version_id")),
1297                "pin_scope_type": row.get("pin_scope_type"),
1298            }
1299            for row in query_connections_by_destination_connector(
1300                connector_definition_id=resolved_definition_id,
1301                organization_id=resolved_organization_id,
1302                limit=limit,
1303                exclude_pinned=exclude_pinned,
1304                enabled_schedules_only=enabled_schedules_only,
1305            )
1306        ]
1307
1308    enriched = enrich_rows_by_org(
1309        rows=rows,
1310        allow_degraded=True,
1311    )
1312    return filter_rows_by_tier(enriched, customer_tier_filter)
1313
1314
1315@mcp_tool(
1316    read_only=True,
1317    idempotent=True,
1318    open_world=True,
1319)
1320def query_prod_connections_by_stream(
1321    stream_name: Annotated[
1322        str,
1323        Field(
1324            description=(
1325                "Name of the stream to search for in connection catalogs. "
1326                "This must match the exact stream name as configured in the connection. "
1327                "Examples: 'global_exclusions', 'campaigns', 'users'."
1328            ),
1329        ),
1330    ],
1331    source_definition_id: Annotated[
1332        str | None,
1333        Field(
1334            description=(
1335                "Source connector definition ID (UUID) to search for. "
1336                "Provide this OR source_canonical_name (exactly one required). "
1337                "Example: 'afa734e4-3571-11ec-991a-1e0031268139' for YouTube Analytics."
1338            ),
1339            default=None,
1340        ),
1341    ],
1342    source_canonical_name: Annotated[
1343        str | None,
1344        Field(
1345            description=(
1346                "Canonical source connector name to search for. "
1347                "Provide this OR source_definition_id (exactly one required). "
1348                "Examples: 'source-klaviyo', 'Klaviyo', 'source-youtube-analytics'."
1349            ),
1350            default=None,
1351        ),
1352    ],
1353    organization_id: Annotated[
1354        str | OrganizationAliasEnum | None,
1355        Field(
1356            description=(
1357                "Optional organization ID (UUID) or alias to filter results. "
1358                "If provided, only connections in this organization will be returned. "
1359                "Accepts '@airbyte-internal' as an alias for the Airbyte internal org."
1360            ),
1361            default=None,
1362        ),
1363    ],
1364    limit: Annotated[
1365        int,
1366        Field(description="Maximum number of results (default: 100)", default=100),
1367    ],
1368    customer_tier_filter: Annotated[
1369        TierFilter,
1370        Field(
1371            description=(
1372                "Required tier filter: 'TIER_0', 'TIER_1', 'TIER_2', 'UNKNOWN', or 'ALL'. "
1373                "Filters results to only include connections belonging to organizations "
1374                "in the specified tier. Use 'ALL' to include all tiers."
1375            ),
1376        ),
1377    ] = "TIER_2",
1378    *,
1379    exclude_pinned: Annotated[
1380        bool,
1381        Field(
1382            description=(
1383                "If True, exclude connections whose connector is already pinned to a "
1384                "specific version (at any scope level: actor, workspace, or organization). "
1385                "Useful for 'prove fix' workflows where you want to find unpinned "
1386                "connections for live testing. Default: False (include all connections)."
1387            ),
1388            default=False,
1389        ),
1390    ],
1391) -> list[dict[str, Any]]:
1392    """Find connections that have a specific stream enabled in their catalog.
1393
1394    This tool searches the connection's configured catalog (JSONB) for streams
1395    matching the specified name. It's particularly useful when validating
1396    connector fixes that affect specific streams - you can quickly find
1397    customer connections that use the affected stream.
1398
1399    Results are always enriched with customer_tier and is_eu fields.
1400    The customer_tier_filter parameter is required to ensure tier-aware querying.
1401
1402    Set `exclude_pinned=True` to filter out connections that are already pinned to a
1403    specific version. This is useful for 'prove fix' live connection testing workflows
1404    where you want to find unpinned connections to test against.
1405
1406    Use cases:
1407    - Finding connections with a specific stream enabled for regression testing
1408    - Validating connector fixes that affect particular streams
1409    - Identifying which customers use rarely-enabled streams
1410
1411    Returns a list of connection dicts with workspace context and clickable Cloud UI URLs.
1412    """
1413    provided_params = [source_definition_id, source_canonical_name]
1414    num_provided = sum(p is not None for p in provided_params)
1415    if num_provided != 1:
1416        raise PyAirbyteInputError(
1417            message=(
1418                "Exactly one of source_definition_id or source_canonical_name "
1419                "must be provided."
1420            ),
1421        )
1422
1423    resolved_definition_id: str
1424    if source_canonical_name:
1425        resolved_definition_id = resolve_canonical_name_to_definition_id(
1426            canonical_name=source_canonical_name,
1427        )
1428    else:
1429        assert source_definition_id is not None
1430        resolved_definition_id = source_definition_id
1431
1432    resolved_organization_id = OrganizationAliasEnum.resolve(organization_id)
1433
1434    rows = [
1435        {
1436            "organization_id": str(row.get("organization_id", "")),
1437            "workspace_id": str(row["workspace_id"]),
1438            "workspace_name": row.get("workspace_name", ""),
1439            "connection_id": str(row["connection_id"]),
1440            "connection_name": row.get("connection_name", ""),
1441            "connection_status": row.get("connection_status", ""),
1442            "connection_url": (
1443                f"{CLOUD_UI_BASE_URL}/workspaces/{row['workspace_id']}"
1444                f"/connections/{row['connection_id']}/status"
1445            ),
1446            "source_id": str(row["source_id"]),
1447            "source_name": row.get("source_name", ""),
1448            "source_definition_id": str(row["source_definition_id"]),
1449            "dataplane_group_id": str(row.get("dataplane_group_id", "")),
1450            "dataplane_name": row.get("dataplane_name", ""),
1451        }
1452        for row in query_connections_by_stream(
1453            connector_definition_id=resolved_definition_id,
1454            stream_name=stream_name,
1455            organization_id=resolved_organization_id,
1456            limit=limit,
1457            exclude_pinned=exclude_pinned,
1458        )
1459    ]
1460    enriched = enrich_rows_by_org(
1461        rows=rows,
1462        allow_degraded=True,
1463    )
1464    return filter_rows_by_tier(enriched, customer_tier_filter)
1465
1466
1467@mcp_tool(
1468    read_only=True,
1469    idempotent=True,
1470)
1471def query_prod_organizations(
1472    name_contains: Annotated[
1473        str,
1474        Field(
1475            description=(
1476                "Case-insensitive substring to search for in organization name or email. "
1477                "For example, 'acme' will match organizations named 'Acme Corp' or "
1478                "with email 'admin@acme.io'."
1479            ),
1480        ),
1481    ],
1482    limit: Annotated[
1483        int,
1484        Field(
1485            description="Maximum number of organizations to return (default: 20)",
1486            default=20,
1487        ),
1488    ] = 20,
1489) -> OrganizationSearchResult:
1490    """Search organizations by name or email substring.
1491
1492    Performs a case-insensitive substring match on organization name and email.
1493    Use the returned `organization_id` values with other tools like
1494    `query_prod_connections_by_connector` or `lookup_customer_tiers`.
1495    """
1496    rows = search_organizations(name_contains=name_contains, limit=limit)
1497
1498    orgs = [
1499        OrganizationSearchHit(
1500            organization_id=str(row["organization_id"]),
1501            organization_name=row.get("organization_name", ""),
1502            email=row.get("email"),
1503        )
1504        for row in rows
1505    ]
1506
1507    # Enrich with tier annotation
1508    org_ids = [o.organization_id for o in orgs]
1509    tier_results = {
1510        r.organization_id: r
1511        for r in get_org_tiers(
1512            organization_ids=org_ids,
1513            allow_degraded=True,
1514        )
1515    }
1516    for org in orgs:
1517        tier_result = tier_results.get(org.organization_id)
1518        if tier_result:
1519            org.customer_tier = tier_result.customer_tier
1520
1521    return OrganizationSearchResult(
1522        name_contains=name_contains,
1523        total_found=len(orgs),
1524        organizations=orgs,
1525    )
1526
1527
1528@mcp_tool(
1529    read_only=True,
1530    idempotent=True,
1531)
1532def query_prod_workspaces(
1533    name_contains: Annotated[
1534        str | None,
1535        Field(
1536            description=(
1537                "Case-insensitive substring to search for in workspace name or slug. "
1538                "For example, 'acme' will match workspaces named 'Acme Staging'."
1539            ),
1540            default=None,
1541        ),
1542    ] = None,
1543    email_domain: Annotated[
1544        str | None,
1545        Field(
1546            description=(
1547                "Email domain to search for (e.g., 'motherduck.com'). "
1548                "Do not include the '@' symbol."
1549            ),
1550            default=None,
1551        ),
1552    ] = None,
1553    limit: Annotated[
1554        int,
1555        Field(
1556            description="Maximum number of workspaces to return (default: 100)",
1557            default=100,
1558        ),
1559    ] = 100,
1560) -> WorkspaceSearchResult:
1561    """Search workspaces by name substring or email domain.
1562
1563    At least one of `name_contains` or `email_domain` must be provided.
1564    When `name_contains` is given, performs a case-insensitive substring match
1565    on workspace name and slug. When `email_domain` is given, matches
1566    workspaces by user email domain.
1567
1568    The returned organization IDs can be used with other tools like
1569    `query_prod_connections_by_connector` to find connections within
1570    those organizations for safe testing.
1571    """
1572    if not name_contains and not email_domain:
1573        raise PyAirbyteInputError(
1574            message="At least one of `name_contains` or `email_domain` must be provided.",
1575        )
1576
1577    if name_contains:
1578        rows = search_workspaces(name_contains=name_contains, limit=limit)
1579    else:
1580        assert email_domain is not None
1581        clean_domain = email_domain.lstrip("@")
1582        rows = query_workspaces_by_email_domain(email_domain=clean_domain, limit=limit)
1583
1584    workspaces = [
1585        WorkspaceInfo(
1586            organization_id=str(row["organization_id"]),
1587            workspace_id=str(row["workspace_id"]),
1588            workspace_name=row.get("workspace_name", ""),
1589            slug=row.get("slug"),
1590            email=row.get("email"),
1591            dataplane_group_id=_opt_str(row.get("dataplane_group_id")),
1592            dataplane_name=row.get("dataplane_name"),
1593            created_at=row.get("created_at"),
1594        )
1595        for row in rows
1596    ]
1597
1598    # Enrich with tier annotation (annotation only, no filtering)
1599    unique_org_ids = list(dict.fromkeys(w.organization_id for w in workspaces))
1600    tier_results = {
1601        r.organization_id: r
1602        for r in get_org_tiers(
1603            organization_ids=unique_org_ids,
1604            allow_degraded=True,
1605        )
1606    }
1607    for ws in workspaces:
1608        tier_result = tier_results.get(ws.organization_id)
1609        if tier_result:
1610            ws.customer_tier = tier_result.customer_tier
1611        ws.is_eu = ws.dataplane_name == "EU" if ws.dataplane_name else False
1612
1613    return WorkspaceSearchResult(
1614        name_contains=name_contains,
1615        email_domain=email_domain.lstrip("@") if email_domain else None,
1616        total_workspaces_found=len(workspaces),
1617        unique_organization_ids=unique_org_ids,
1618        workspaces=workspaces,
1619    )
1620
1621
1622# Backward-compatible alias
1623query_prod_workspaces_by_email_domain = query_prod_workspaces
1624
1625
1626def _build_connector_stats(
1627    connector_definition_id: str,
1628    connector_type: str,
1629    canonical_name: str | None,
1630    rows: list[dict[str, Any]],
1631    version_tags: dict[str, str | None],
1632) -> ConnectorConnectionStats:
1633    """Build ConnectorConnectionStats from query result rows."""
1634    # Aggregate totals across all version groups
1635    total_connections = 0
1636    enabled_connections = 0
1637    active_connections = 0
1638    pinned_connections = 0
1639    unpinned_connections = 0
1640    total_succeeded = 0
1641    total_failed = 0
1642    total_cancelled = 0
1643    total_running = 0
1644    total_unknown = 0
1645
1646    by_version: list[VersionPinStats] = []
1647
1648    for row in rows:
1649        version_id = row.get("pinned_version_id")
1650        row_total = int(row.get("total_connections", 0))
1651        row_enabled = int(row.get("enabled_connections", 0))
1652        row_active = int(row.get("active_connections", 0))
1653        row_pinned = int(row.get("pinned_connections", 0))
1654        row_unpinned = int(row.get("unpinned_connections", 0))
1655        row_succeeded = int(row.get("succeeded_connections", 0))
1656        row_failed = int(row.get("failed_connections", 0))
1657        row_cancelled = int(row.get("cancelled_connections", 0))
1658        row_running = int(row.get("running_connections", 0))
1659        row_unknown = int(row.get("unknown_connections", 0))
1660
1661        total_connections += row_total
1662        enabled_connections += row_enabled
1663        active_connections += row_active
1664        pinned_connections += row_pinned
1665        unpinned_connections += row_unpinned
1666        total_succeeded += row_succeeded
1667        total_failed += row_failed
1668        total_cancelled += row_cancelled
1669        total_running += row_running
1670        total_unknown += row_unknown
1671
1672        by_version.append(
1673            VersionPinStats(
1674                pinned_version_id=str(version_id) if version_id else None,
1675                docker_image_tag=version_tags.get(str(version_id))
1676                if version_id
1677                else None,
1678                total_connections=row_total,
1679                enabled_connections=row_enabled,
1680                active_connections=row_active,
1681                latest_attempt=LatestAttemptBreakdown(
1682                    succeeded=row_succeeded,
1683                    failed=row_failed,
1684                    cancelled=row_cancelled,
1685                    running=row_running,
1686                    unknown=row_unknown,
1687                ),
1688            )
1689        )
1690
1691    return ConnectorConnectionStats(
1692        connector_definition_id=connector_definition_id,
1693        connector_type=connector_type,
1694        canonical_name=canonical_name,
1695        total_connections=total_connections,
1696        enabled_connections=enabled_connections,
1697        active_connections=active_connections,
1698        pinned_connections=pinned_connections,
1699        unpinned_connections=unpinned_connections,
1700        latest_attempt=LatestAttemptBreakdown(
1701            succeeded=total_succeeded,
1702            failed=total_failed,
1703            cancelled=total_cancelled,
1704            running=total_running,
1705            unknown=total_unknown,
1706        ),
1707        by_version=by_version,
1708    )
1709
1710
1711@mcp_tool(
1712    read_only=True,
1713    idempotent=True,
1714    open_world=True,
1715)
1716def query_prod_connector_connection_stats(
1717    source_definition_ids: Annotated[
1718        list[str] | None,
1719        Field(
1720            description=(
1721                "List of source connector definition IDs (UUIDs) to get stats for. "
1722                "Example: ['afa734e4-3571-11ec-991a-1e0031268139']"
1723            ),
1724            default=None,
1725        ),
1726    ] = None,
1727    destination_definition_ids: Annotated[
1728        list[str] | None,
1729        Field(
1730            description=(
1731                "List of destination connector definition IDs (UUIDs) to get stats for. "
1732                "Example: ['94bd199c-2ff0-4aa2-b98e-17f0acb72610']"
1733            ),
1734            default=None,
1735        ),
1736    ] = None,
1737    lookback_days: Annotated[
1738        int,
1739        Field(
1740            description=(
1741                "Number of days to look back for 'active' connections (default: 7). "
1742                "Connections with sync activity within this window are counted as active."
1743            ),
1744            default=7,
1745        ),
1746    ] = 7,
1747) -> ConnectorConnectionStatsResponse:
1748    """Get aggregate connection stats for multiple connectors.
1749
1750    Returns counts of connections grouped by pinned version for each connector,
1751    including:
1752    - Total, enabled, and active connection counts
1753    - Pinned vs unpinned breakdown
1754    - Latest attempt status breakdown (succeeded, failed, cancelled, running, unknown)
1755
1756    This tool is designed for release monitoring workflows. It allows you to:
1757    1. Query recently released connectors to identify which ones to monitor
1758    2. Get aggregate stats showing how many connections are using each version
1759    3. See health metrics (pass/fail) broken down by version
1760
1761    The `lookback_days` parameter controls the lookback window for:
1762    - Counting 'active' connections (those with recent sync activity)
1763    - Determining 'latest attempt status' (most recent attempt within the window)
1764
1765    Connections with no sync activity in the lookback window will have
1766    'unknown' status in the latest_attempt breakdown.
1767    """
1768    # Initialize empty lists if None
1769    source_ids = source_definition_ids or []
1770    destination_ids = destination_definition_ids or []
1771
1772    if not source_ids and not destination_ids:
1773        raise PyAirbyteInputError(
1774            message=(
1775                "At least one of source_definition_ids or destination_definition_ids "
1776                "must be provided."
1777            ),
1778        )
1779
1780    sources: list[ConnectorConnectionStats] = []
1781    destinations: list[ConnectorConnectionStats] = []
1782
1783    # Process source connectors
1784    for source_def_id in source_ids:
1785        # Get version info for tag lookup
1786        versions = query_connector_versions(source_def_id)
1787        version_tags = {
1788            str(v["version_id"]): v.get("docker_image_tag") for v in versions
1789        }
1790
1791        # Get aggregate stats
1792        rows = query_source_connection_stats(source_def_id, days=lookback_days)
1793
1794        sources.append(
1795            _build_connector_stats(
1796                connector_definition_id=source_def_id,
1797                connector_type="source",
1798                canonical_name=None,
1799                rows=rows,
1800                version_tags=version_tags,
1801            )
1802        )
1803
1804    # Process destination connectors
1805    for dest_def_id in destination_ids:
1806        # Get version info for tag lookup
1807        versions = query_connector_versions(dest_def_id)
1808        version_tags = {
1809            str(v["version_id"]): v.get("docker_image_tag") for v in versions
1810        }
1811
1812        # Get aggregate stats
1813        rows = query_destination_connection_stats(dest_def_id, days=lookback_days)
1814
1815        destinations.append(
1816            _build_connector_stats(
1817                connector_definition_id=dest_def_id,
1818                connector_type="destination",
1819                canonical_name=None,
1820                rows=rows,
1821                version_tags=version_tags,
1822            )
1823        )
1824
1825    return ConnectorConnectionStatsResponse(
1826        sources=sources,
1827        destinations=destinations,
1828        lookback_days=lookback_days,
1829        generated_at=datetime.now(timezone.utc),
1830    )
1831
1832
1833# =============================================================================
1834# Connector Rollout Models and Tools
1835# =============================================================================
1836
1837
1838class ConnectorRolloutInfo(BaseModel):
1839    """Information about a connector rollout."""
1840
1841    rollout_id: str = Field(description="The rollout UUID")
1842    actor_definition_id: str = Field(description="The connector definition UUID")
1843    state: str = Field(
1844        description="Rollout state: initialized, workflow_started, in_progress, "
1845        "paused, finalizing, succeeded, errored, failed_rolled_back, canceled"
1846    )
1847    initial_rollout_pct: int | None = Field(
1848        default=None, description="Initial rollout percentage"
1849    )
1850    current_target_rollout_pct: int | None = Field(
1851        default=None, description="Current target rollout percentage"
1852    )
1853    final_target_rollout_pct: int | None = Field(
1854        default=None, description="Final target rollout percentage"
1855    )
1856    has_breaking_changes: bool = Field(
1857        description="Whether the RC has breaking changes"
1858    )
1859    max_step_wait_time_mins: int | None = Field(
1860        default=None, description="Maximum wait time between rollout steps in minutes"
1861    )
1862    rollout_strategy: str | None = Field(
1863        default=None, description="Rollout strategy: manual, automated, overridden"
1864    )
1865    updated_by_user_id: str | None = Field(
1866        default=None,
1867        description="User ID recorded as last updating the rollout",
1868    )
1869    updated_by_user_name: str | None = Field(
1870        default=None,
1871        description="Name recorded as last updating the rollout",
1872    )
1873    updated_by_user_email: str | None = Field(
1874        default=None,
1875        description="Email recorded as last updating the rollout",
1876    )
1877    workflow_run_id: str | None = Field(
1878        default=None, description="Temporal workflow run ID"
1879    )
1880    error_msg: str | None = Field(default=None, description="Error message if errored")
1881    failed_reason: str | None = Field(
1882        default=None, description="Reason for failure if failed"
1883    )
1884    paused_reason: str | None = Field(
1885        default=None, description="Reason for pause if paused"
1886    )
1887    tag: str | None = Field(default=None, description="Optional tag for the rollout")
1888    created_at: datetime | None = Field(
1889        default=None, description="When the rollout was created"
1890    )
1891    updated_at: datetime | None = Field(
1892        default=None, description="When the rollout was last updated"
1893    )
1894    completed_at: datetime | None = Field(
1895        default=None, description="When the rollout completed (if terminal)"
1896    )
1897    expires_at: datetime | None = Field(
1898        default=None, description="When the rollout expires"
1899    )
1900    rc_docker_image_tag: str | None = Field(
1901        default=None, description="Docker image tag of the release candidate"
1902    )
1903    rc_docker_repository: str | None = Field(
1904        default=None, description="Docker repository of the release candidate"
1905    )
1906    initial_docker_image_tag: str | None = Field(
1907        default=None, description="Docker image tag of the initial version"
1908    )
1909    initial_docker_repository: str | None = Field(
1910        default=None, description="Docker repository of the initial version"
1911    )
1912    filters: dict[str, Any] | None = Field(
1913        default=None,
1914        description="Raw rollout filters JSON (e.g., {'tierFilter': {'tier': 'TIER_0'}})",
1915    )
1916    customer_tier: str | None = Field(
1917        default=None,
1918        description="Customer tier targeted by this rollout (extracted from filters), "
1919        "e.g., 'TIER_0', 'TIER_1'. None if no tier filter is set.",
1920    )
1921
1922
1923def _parse_rollout_filters(filters_raw: Any) -> dict[str, Any] | None:
1924    """Parse the rollout filters field from a database row.
1925
1926    The filters field may be a JSON string, a dict, or None.
1927    """
1928    if filters_raw is None:
1929        return None
1930    if isinstance(filters_raw, dict):
1931        return filters_raw
1932    if isinstance(filters_raw, str):
1933        try:
1934            parsed = json.loads(filters_raw)
1935            if isinstance(parsed, dict):
1936                return parsed
1937        except (json.JSONDecodeError, TypeError):
1938            pass
1939    return None
1940
1941
1942def _extract_tier_from_filters(filters_raw: Any) -> str | None:
1943    """Extract customer tier from rollout filters JSON.
1944
1945    Supports two formats:
1946    - Legacy: `{"tierFilter": {"tier": "TIER_0"}}`
1947    - Current: `{"customerTierFilters": [{"name": "TIER", "value": ["TIER_1"], "operator": "IN"}]}`
1948    """
1949    parsed = _parse_rollout_filters(filters_raw)
1950    if parsed is None:
1951        return None
1952
1953    # Current format: customerTierFilters list
1954    tier_filters = parsed.get("customerTierFilters")
1955    if isinstance(tier_filters, list):
1956        for entry in tier_filters:
1957            if isinstance(entry, dict) and entry.get("name") == "TIER":
1958                values = entry.get("value")
1959                if isinstance(values, list) and len(values) == 1:
1960                    return str(values[0])
1961                if isinstance(values, list) and len(values) > 1:
1962                    return ", ".join(str(v) for v in values)
1963
1964    # Legacy format: tierFilter dict
1965    tier_filter = parsed.get("tierFilter")
1966    if isinstance(tier_filter, dict):
1967        tier = tier_filter.get("tier")
1968        if isinstance(tier, str):
1969            return tier
1970
1971    return None
1972
1973
1974def _row_to_connector_rollout_info(row: dict[str, Any]) -> ConnectorRolloutInfo:
1975    """Convert a database row to a ConnectorRolloutInfo model."""
1976    return ConnectorRolloutInfo(
1977        rollout_id=str(row["rollout_id"]),
1978        actor_definition_id=str(row["actor_definition_id"]),
1979        state=row["state"],
1980        initial_rollout_pct=row.get("initial_rollout_pct"),
1981        current_target_rollout_pct=row.get("current_target_rollout_pct"),
1982        final_target_rollout_pct=row.get("final_target_rollout_pct"),
1983        has_breaking_changes=row["has_breaking_changes"],
1984        max_step_wait_time_mins=row.get("max_step_wait_time_mins"),
1985        rollout_strategy=row.get("rollout_strategy"),
1986        updated_by_user_id=str(row["updated_by_user_id"])
1987        if row.get("updated_by_user_id") is not None
1988        else None,
1989        updated_by_user_name=row.get("updated_by_user_name"),
1990        updated_by_user_email=row.get("updated_by_user_email"),
1991        workflow_run_id=row.get("workflow_run_id"),
1992        error_msg=row.get("error_msg"),
1993        failed_reason=row.get("failed_reason"),
1994        paused_reason=row.get("paused_reason"),
1995        tag=row.get("tag"),
1996        created_at=row.get("created_at"),
1997        updated_at=row.get("updated_at"),
1998        completed_at=row.get("completed_at"),
1999        expires_at=row.get("expires_at"),
2000        rc_docker_image_tag=row.get("rc_docker_image_tag"),
2001        rc_docker_repository=row.get("rc_docker_repository"),
2002        initial_docker_image_tag=row.get("initial_docker_image_tag"),
2003        initial_docker_repository=row.get("initial_docker_repository"),
2004        filters=_parse_rollout_filters(row.get("filters")),
2005        customer_tier=_extract_tier_from_filters(row.get("filters")),
2006    )
2007
2008
2009@mcp_tool(
2010    read_only=True,
2011    idempotent=True,
2012)
2013def query_prod_connector_rollouts(
2014    actor_definition_id: Annotated[
2015        str | None,
2016        Field(description="Connector definition UUID to filter by (optional)"),
2017    ] = None,
2018    rollout_id: Annotated[
2019        str | None,
2020        Field(description="Specific rollout UUID to look up (optional)"),
2021    ] = None,
2022    active_only: Annotated[
2023        bool,
2024        Field(description="If true, only return active (non-terminal) rollouts"),
2025    ] = False,
2026    limit: Annotated[
2027        int,
2028        Field(description="Maximum number of results (default: 100)"),
2029    ] = 100,
2030) -> list[ConnectorRolloutInfo]:
2031    """Query connector rollouts with flexible filtering.
2032
2033    Returns rollouts based on the provided filters. If no filters are specified,
2034    returns all active rollouts. Useful for monitoring rollout status and history.
2035
2036    Filter behavior:
2037    - rollout_id: Returns that specific rollout (ignores other filters)
2038    - active_only: Returns only active (non-terminal) rollouts
2039    - actor_definition_id: Returns rollouts for that specific connector
2040    - No filters: Returns all active rollouts (same as active_only=True)
2041    """
2042    rows = query_connector_rollouts(
2043        actor_definition_id=actor_definition_id,
2044        rollout_id=rollout_id,
2045        active_only=active_only,
2046        limit=limit,
2047    )
2048    return [_row_to_connector_rollout_info(row) for row in rows]
2049
2050
2051@mcp_tool(
2052    read_only=True,
2053    idempotent=True,
2054    open_world=True,
2055)
2056def query_prod_connection_sync_activity(
2057    start_at: Annotated[
2058        datetime,
2059        Field(
2060            description=(
2061                "Inclusive start timestamp for the sync activity window. "
2062                "Must be timezone-aware (ISO 8601 with offset or `Z`)."
2063            ),
2064        ),
2065    ],
2066    end_at: Annotated[
2067        datetime,
2068        Field(
2069            description=(
2070                "Exclusive end timestamp for the sync activity window. "
2071                "Must be timezone-aware and strictly after `start_at`."
2072            ),
2073        ),
2074    ],
2075    organization_id: Annotated[
2076        str | OrganizationAliasEnum | None,
2077        Field(
2078            description=(
2079                "Optional organization UUID or alias. At least one of "
2080                "`organization_id`, `workspace_id`, or `connection_ids` is "
2081                "required. Accepts `@airbyte-internal` as an alias for the "
2082                "Airbyte internal org."
2083            ),
2084            default=None,
2085        ),
2086    ] = None,
2087    workspace_id: Annotated[
2088        str | WorkspaceAliasEnum | None,
2089        Field(
2090            description=(
2091                "Optional workspace UUID or alias. At least one of "
2092                "`organization_id`, `workspace_id`, or `connection_ids` is "
2093                "required. Accepts `@devin-ai-sandbox` as an alias for the "
2094                "Devin AI sandbox workspace."
2095            ),
2096            default=None,
2097        ),
2098    ] = None,
2099    connection_ids: Annotated[
2100        list[str] | None,
2101        Field(
2102            description=(
2103                "Optional list of connection UUIDs. At least one of "
2104                "`organization_id`, `workspace_id`, or `connection_ids` is "
2105                "required."
2106            ),
2107            default=None,
2108        ),
2109    ] = None,
2110    status_filter: Annotated[
2111        StatusFilter,
2112        Field(
2113            description=(
2114                "Filter by job status: `all` (default), `succeeded`, or "
2115                "`failed`. Applied to `jobs.status` in the Prod DB Replica."
2116            ),
2117            default=StatusFilter.ALL,
2118        ),
2119    ] = StatusFilter.ALL,
2120    limit: Annotated[
2121        int,
2122        Field(
2123            description="Maximum number of attempt rows to return.",
2124            default=1000,
2125        ),
2126    ] = 1000,
2127) -> list[dict[str, Any]]:
2128    """List recent sync jobs and attempts from the Prod DB Replica.
2129
2130    Returns one row per `(job, attempt)` pair for sync jobs whose `updated_at`
2131    falls in `[start_at, end_at)`, scoped to the provided organization,
2132    workspace, or connection IDs. Designed for live operational lookups —
2133    e.g. "what happened on this connection in the last hour" — not for
2134    historical analysis.
2135
2136    Each row is enriched with `customer_tier` and `is_eu` for the owning
2137    organization. Tier filtering is intentionally not applied — this is a
2138    read-only observability query.
2139
2140    Input requirements:
2141    - At least one of `organization_id`, `workspace_id`, or `connection_ids`
2142      must be provided (any combination is accepted).
2143    - `start_at` and `end_at` must be timezone-aware and `start_at < end_at`.
2144
2145    Key fields in each row:
2146    - `job_id`, `attempt_id`, `attempt_number`
2147    - `job_status`, `attempt_status`
2148    - `job_started_at`, `job_updated_at`, `attempt_ended_at`
2149    - `failure_summary` (JSON; populated when an attempt failed)
2150    - `connection_id`, `connection_name`, `connection_status`
2151    - `source_actor_id`, `source_actor_name`, `source_actor_definition_id`
2152    - `destination_actor_id`, `destination_actor_name`,
2153      `destination_actor_definition_id`
2154    - `workspace_id`, `workspace_name`, `organization_id`
2155    - `dataplane_group_id`, `dataplane_name`
2156    - `customer_tier`, `is_eu` (added by tier enrichment)
2157    """
2158    resolved_organization_id = OrganizationAliasEnum.resolve(organization_id)
2159    resolved_workspace_id = WorkspaceAliasEnum.resolve(workspace_id)
2160    _validate_sync_activity_scope(
2161        organization_id=resolved_organization_id,
2162        workspace_id=resolved_workspace_id,
2163        connection_ids=connection_ids,
2164    )
2165    normalized_start_at, normalized_end_at = _validate_sync_activity_window(
2166        start_at=start_at,
2167        end_at=end_at,
2168    )
2169
2170    rows = query_connection_sync_activity_from_prod(
2171        start_at=normalized_start_at,
2172        end_at=normalized_end_at,
2173        organization_id=resolved_organization_id,
2174        workspace_id=resolved_workspace_id,
2175        connection_ids=connection_ids,
2176        status_filter=status_filter.value,
2177        limit=limit,
2178    )
2179    return enrich_rows_by_org(
2180        rows=rows,
2181        allow_degraded=True,
2182    )
2183
2184
2185# =============================================================================
2186# Pinned Connector Versions Models and Tools
2187# =============================================================================
2188
2189
2190class PinnedConnectorVersionInfo(BaseModel):
2191    """A connector version that has at least one scoped configuration pin."""
2192
2193    version_id: str = Field(description="The actor_definition_version UUID")
2194    connector_definition_id: str = Field(description="The connector definition UUID")
2195    connector_name: str = Field(description="Human-readable connector name")
2196    docker_repository: str = Field(description="Docker repository path")
2197    docker_image_tag: str = Field(description="Docker image tag for this version")
2198    last_published: str | None = Field(
2199        default=None, description="ISO timestamp when this version was last published"
2200    )
2201    pin_count: int = Field(
2202        description="Total number of scoped_configuration rows pinning to this version"
2203    )
2204    breaking_change_pins: int = Field(
2205        default=0,
2206        description="Number of actor-scoped pins created by breaking changes",
2207    )
2208    rollout_pins: int = Field(
2209        default=0,
2210        description="Number of pins created by connector rollouts",
2211    )
2212    actor_pins: int = Field(
2213        description="Number of actor-scoped pins (excludes breaking change and rollout pins)"
2214    )
2215    workspace_pins: int = Field(description="Number of workspace-scoped pins")
2216    org_pins: int = Field(description="Number of organization-scoped pins")
2217
2218
2219@mcp_tool(
2220    read_only=True,
2221    idempotent=True,
2222    open_world=True,
2223)
2224def query_connector_pin_stats(
2225    connector_definition_id: Annotated[
2226        str | None,
2227        Field(
2228            description="Connector definition UUID to filter by (optional). "
2229            "Mutually exclusive with `connector_canonical_name`."
2230        ),
2231    ] = None,
2232    connector_canonical_name: Annotated[
2233        str | None,
2234        Field(
2235            description="Connector canonical name (e.g. `source-postgres`) to filter by. "
2236            "Resolved to a definition ID via the registry. "
2237            "Mutually exclusive with `connector_definition_id`."
2238        ),
2239    ] = None,
2240) -> list[PinnedConnectorVersionInfo]:
2241    """Query connector versions that have at least one scoped configuration pin.
2242
2243    Returns versions from the prod DB that are referenced by at least one
2244    `scoped_configuration` pin (`key = 'connector_version'`).  Each version
2245    appears exactly once with per-scope pin breakdown (actor, workspace, org).
2246
2247    If neither filter is provided, returns the global superset across all connectors.
2248    """
2249    if connector_definition_id and connector_canonical_name:
2250        raise PyAirbyteInputError(
2251            message=(
2252                "Provide at most one of `connector_definition_id` or "
2253                "`connector_canonical_name`, not both."
2254            ),
2255        )
2256
2257    resolved_id: str | None = None
2258    if connector_canonical_name:
2259        resolved_id = resolve_canonical_name_to_definition_id(
2260            canonical_name=connector_canonical_name,
2261        )
2262    elif connector_definition_id:
2263        resolved_id = connector_definition_id
2264
2265    rows = query_versions_with_pins(actor_definition_id=resolved_id)
2266    return [
2267        PinnedConnectorVersionInfo(
2268            version_id=str(row["version_id"]),
2269            connector_definition_id=str(row["connector_definition_id"]),
2270            connector_name=row["connector_name"],
2271            docker_repository=row["docker_repository"],
2272            docker_image_tag=row["docker_image_tag"],
2273            last_published=(
2274                row["last_published"].isoformat() if row.get("last_published") else None
2275            ),
2276            pin_count=row["pin_count"],
2277            breaking_change_pins=row.get("breaking_change_pins", 0),
2278            rollout_pins=row.get("rollout_pins", 0),
2279            actor_pins=row.get("actor_pins", 0),
2280            workspace_pins=row.get("workspace_pins", 0),
2281            org_pins=row.get("org_pins", 0),
2282        )
2283        for row in rows
2284    ]
2285
2286
2287# =============================================================================
2288# Organization-scoped Pin Models and Tools
2289# =============================================================================
2290
2291
2292class PinOriginFilter(StrEnum):
2293    """How a `scoped_configuration` pin was created, used to filter pins."""
2294
2295    ALL = "all"
2296    MANUAL = "manual"
2297    CONNECTOR_ROLLOUT = "connector_rollout"
2298    BREAKING_CHANGE = "breaking_change"
2299
2300
2301# Rollout states considered non-terminal ("active"). Kept in sync with the set
2302# used by the rollout-monitoring SQL in `airbyte_ops_mcp.prod_db_access.sql`.
2303_ACTIVE_ROLLOUT_STATES = frozenset(
2304    {
2305        "initialized",
2306        "workflow_started",
2307        "in_progress",
2308        "paused",
2309        "finalizing",
2310        "errored",
2311    }
2312)
2313
2314
2315def _pin_category(origin_type: str | None) -> str:
2316    """Classify a pin as `rollout`, `breaking_change`, or `manual`."""
2317    if origin_type == "connector_rollout":
2318        return "rollout"
2319    if origin_type == "breaking_change":
2320        return "breaking_change"
2321    return "manual"
2322
2323
2324# Maps a `PinOriginFilter` to the `_pin_category` value it keeps. `origin_filter`
2325# is applied here in Python rather than in SQL — the fetched pin list is small,
2326# so an in-SQL `:origin_filter` OR-chain would only add scan cost.
2327_ORIGIN_FILTER_CATEGORIES: dict[str, str] = {
2328    "manual": "manual",
2329    "connector_rollout": "rollout",
2330    "breaking_change": "breaking_change",
2331}
2332
2333
2334def _resolve_connector_filter_id(
2335    *,
2336    connector_definition_id: str | None,
2337    connector_canonical_name: str | None,
2338) -> str | None:
2339    """Resolve mutually-exclusive connector inputs to a definition id or `None`.
2340
2341    Blank or whitespace-only inputs are treated as absent (`None`) so an
2342    optional filter passed as `""` does not become a real, zero-matching SQL
2343    filter.
2344    """
2345    connector_definition_id = (connector_definition_id or "").strip() or None
2346    connector_canonical_name = (connector_canonical_name or "").strip() or None
2347    if connector_definition_id and connector_canonical_name:
2348        raise PyAirbyteInputError(
2349            message=(
2350                "Provide at most one of `connector_definition_id` or "
2351                "`connector_canonical_name`, not both."
2352            ),
2353        )
2354    if connector_canonical_name:
2355        return resolve_canonical_name_to_definition_id(
2356            canonical_name=connector_canonical_name,
2357        )
2358    return connector_definition_id
2359
2360
2361def _require_organization_id(organization_id: str | OrganizationAliasEnum) -> str:
2362    """Resolve a required organization id to a canonical UUID string.
2363
2364    Accepts an organization UUID or an `OrganizationAliasEnum` alias, resolving
2365    aliases to their UUID. The result is validated as a UUID and returned in
2366    canonical (lowercased) form for consistent logging and comparison. (The
2367    org-pin SQL casts this to native `uuid`, so matching is case-insensitive
2368    either way.) Raises `PyAirbyteInputError` on blank or malformed input rather
2369    than passing an invalid value to SQL and returning a confusing empty result.
2370    """
2371    resolved = OrganizationAliasEnum.resolve(organization_id)
2372    if not resolved or not resolved.strip():
2373        raise PyAirbyteInputError(
2374            message="`organization_id` is required (a non-empty organization UUID or alias).",
2375        )
2376    try:
2377        return str(uuid.UUID(resolved.strip()))
2378    except ValueError as exc:
2379        raise PyAirbyteInputError(
2380            message="`organization_id` is not a valid organization UUID or alias.",
2381        ) from exc
2382
2383
2384def _normalize_optional_version_id(pinned_version_id: str | None) -> str | None:
2385    """Coerce a blank `pinned_version_id` to `None` and validate UUID format.
2386
2387    A blank or whitespace-only value is treated as "no filter" (`None`) rather
2388    than being passed to the SQL `uuid` cast, which would raise
2389    `invalid input syntax for type uuid`.
2390    """
2391    normalized = (pinned_version_id or "").strip() or None
2392    if normalized is not None:
2393        try:
2394            uuid.UUID(normalized)
2395        except ValueError as exc:
2396            raise PyAirbyteInputError(
2397                message="`pinned_version_id` is not a valid UUID.",
2398            ) from exc
2399    return normalized
2400
2401
2402class OrgVersionPinStats(BaseModel):
2403    """A connector version pinned somewhere under an organization, with counts."""
2404
2405    version_id: str = Field(description="The actor_definition_version UUID")
2406    connector_definition_id: str = Field(description="The connector definition UUID")
2407    connector_name: str = Field(description="Human-readable connector name")
2408    docker_repository: str = Field(description="Docker repository path")
2409    docker_image_tag: str = Field(description="Docker image tag for this version")
2410    last_published: str | None = Field(
2411        default=None, description="ISO timestamp when this version was last published"
2412    )
2413    pin_count: int = Field(
2414        description="Total pins under the org targeting this version (all scopes)"
2415    )
2416    manual_pins: int = Field(
2417        default=0,
2418        description="Pins with no system origin (user-created manual pins), any scope",
2419    )
2420    rollout_pins: int = Field(
2421        default=0, description="Pins created by connector rollouts"
2422    )
2423    breaking_change_pins: int = Field(
2424        default=0, description="Pins created by breaking changes"
2425    )
2426    actor_pins: int = Field(
2427        description="Manual actor-scoped pins (excludes rollout and breaking-change)"
2428    )
2429    workspace_pins: int = Field(description="Workspace-scoped pins under the org")
2430    org_pins: int = Field(description="Organization-scoped pins")
2431    has_active_rollout: bool = Field(
2432        default=False,
2433        description=(
2434            "`True` if at least one rollout pin is backed by a non-terminal "
2435            "`connector_rollout`"
2436        ),
2437    )
2438
2439
2440class OrgConnectorPin(BaseModel):
2441    """A single `scoped_configuration` pin discovered under an organization."""
2442
2443    connector_definition_id: str = Field(description="The connector definition UUID")
2444    connector_name: str = Field(description="Human-readable connector name")
2445    docker_repository: str = Field(description="Docker repository path")
2446    pinned_version_id: str = Field(
2447        description="The pinned actor_definition_version UUID"
2448    )
2449    pinned_version_tag: str = Field(
2450        description="Docker image tag of the pinned version"
2451    )
2452    pin_scope_type: str = Field(
2453        description="Scope of the pin: `organization`, `workspace`, or `actor`"
2454    )
2455    scope_id: str = Field(description="UUID of the scoped entity")
2456    scope_name: str | None = Field(
2457        default=None, description="Display name of the scoped entity, when resolvable"
2458    )
2459    pin_category: str = Field(
2460        description="Derived pin type: `manual`, `rollout`, or `breaking_change`"
2461    )
2462    set_by: str | None = Field(
2463        default=None,
2464        description="Email (or name) of the user who set a manual pin, when known",
2465    )
2466    rollout_id: str | None = Field(
2467        default=None, description="Backing connector_rollout UUID for rollout pins"
2468    )
2469    rollout_state: str | None = Field(
2470        default=None, description="State of the backing rollout, for rollout pins"
2471    )
2472    is_active_rollout: bool = Field(
2473        default=False,
2474        description="`True` when `rollout_state` is a non-terminal (active) state",
2475    )
2476    description: str | None = Field(default=None, description="Free-text pin reason")
2477    reference_url: str | None = Field(
2478        default=None, description="Reference URL attached to the pin, when present"
2479    )
2480    created_at: str | None = Field(
2481        default=None, description="ISO timestamp when the pin was created"
2482    )
2483    expires_at: str | None = Field(
2484        default=None, description="ISO timestamp when the pin expires, when set"
2485    )
2486
2487
2488@mcp_tool(
2489    read_only=True,
2490    idempotent=True,
2491    open_world=True,
2492)
2493def query_prod_pin_stats_for_organization(
2494    organization_id: Annotated[
2495        str | OrganizationAliasEnum,
2496        Field(
2497            description="Organization UUID (or `@airbyte-internal` alias) to scope pins to. "
2498            "Resolve organization names to an ID first via `search_organizations`."
2499        ),
2500    ],
2501    connector_definition_id: Annotated[
2502        str | None,
2503        Field(
2504            description="Connector definition UUID to filter by (optional). "
2505            "Mutually exclusive with `connector_canonical_name`."
2506        ),
2507    ] = None,
2508    connector_canonical_name: Annotated[
2509        str | None,
2510        Field(
2511            description="Connector canonical name (e.g. `source-postgres`) to filter by. "
2512            "Resolved to a definition ID via the registry. "
2513            "Mutually exclusive with `connector_definition_id`."
2514        ),
2515    ] = None,
2516    limit: Annotated[
2517        int,
2518        Field(description="Maximum number of versions to return (default: 1000)."),
2519    ] = 1000,
2520) -> list[OrgVersionPinStats]:
2521    """Query connector versions pinned anywhere under an organization.
2522
2523    Returns one row per pinned version, aggregating every `connector_version`
2524    pin whose scope belongs to the organization — the org itself, one of its
2525    workspaces, or an actor within one of those workspaces (actor, workspace,
2526    and organization scopes). Each row carries the per-scope pin breakdown, the
2527    manual/rollout/breaking-change split, and a `has_active_rollout` flag.
2528
2529    This powers the first step of the Organization Pins view (pick an org, then
2530    see the versions pinned under it). Use `query_prod_pins_for_organization`
2531    for the individual pins behind a selected version.
2532    """
2533    resolved_org_id = _require_organization_id(organization_id)
2534    resolved_connector_id = _resolve_connector_filter_id(
2535        connector_definition_id=connector_definition_id,
2536        connector_canonical_name=connector_canonical_name,
2537    )
2538    rows = query_org_pin_stats(
2539        resolved_org_id,
2540        connector_definition_id=resolved_connector_id,
2541        limit=limit,
2542    )
2543    return [
2544        OrgVersionPinStats(
2545            version_id=str(row["version_id"]),
2546            connector_definition_id=str(row["connector_definition_id"]),
2547            connector_name=row["connector_name"],
2548            docker_repository=row["docker_repository"],
2549            docker_image_tag=row["docker_image_tag"],
2550            last_published=(
2551                row["last_published"].isoformat() if row.get("last_published") else None
2552            ),
2553            pin_count=row["pin_count"],
2554            manual_pins=row.get("manual_pins", 0),
2555            rollout_pins=row.get("rollout_pins", 0),
2556            breaking_change_pins=row.get("breaking_change_pins", 0),
2557            actor_pins=row.get("actor_pins", 0),
2558            workspace_pins=row.get("workspace_pins", 0),
2559            org_pins=row.get("org_pins", 0),
2560            has_active_rollout=bool(row.get("has_active_rollout", False)),
2561        )
2562        for row in rows
2563    ]
2564
2565
2566@mcp_tool(
2567    read_only=True,
2568    idempotent=True,
2569    open_world=True,
2570)
2571def query_prod_pins_for_organization(
2572    organization_id: Annotated[
2573        str | OrganizationAliasEnum,
2574        Field(
2575            description="Organization UUID (or `@airbyte-internal` alias) to scope pins to. "
2576            "Resolve organization names to an ID first via `search_organizations`."
2577        ),
2578    ],
2579    connector_definition_id: Annotated[
2580        str | None,
2581        Field(
2582            description="Connector definition UUID to filter by (optional). "
2583            "Mutually exclusive with `connector_canonical_name`."
2584        ),
2585    ] = None,
2586    connector_canonical_name: Annotated[
2587        str | None,
2588        Field(
2589            description="Connector canonical name (e.g. `source-postgres`) to filter by. "
2590            "Resolved to a definition ID via the registry. "
2591            "Mutually exclusive with `connector_definition_id`."
2592        ),
2593    ] = None,
2594    pinned_version_id: Annotated[
2595        str | None,
2596        Field(
2597            description="Actor_definition_version UUID to return only pins targeting "
2598            "that version. This is the post-selection filter for the org pins tab."
2599        ),
2600    ] = None,
2601    origin_filter: Annotated[
2602        PinOriginFilter,
2603        Field(
2604            description="Restrict by how the pin was created: `all` (default), "
2605            "`manual`, `connector_rollout`, or `breaking_change`."
2606        ),
2607    ] = PinOriginFilter.ALL,
2608    limit: Annotated[
2609        int,
2610        Field(description="Maximum number of pins to return (default: 1000)."),
2611    ] = 1000,
2612) -> list[OrgConnectorPin]:
2613    """List the individual connector-version pins discovered under an organization.
2614
2615    Returns one row per `scoped_configuration` pin whose scope belongs to the
2616    organization (org/workspace/actor), resolving the pinned connector and
2617    version, the scope's display name, the manual author's email, and — for
2618    rollout-origin pins — the backing `connector_rollout` id and state. This
2619    directly answers whether each pin is manual or caused by an active rollout.
2620
2621    This powers the second step of the Organization Pins view: after picking a
2622    version from `query_prod_pin_stats_for_organization`, pass its
2623    `pinned_version_id` here to list the pins behind it.
2624    """
2625    resolved_org_id = _require_organization_id(organization_id)
2626    resolved_connector_id = _resolve_connector_filter_id(
2627        connector_definition_id=connector_definition_id,
2628        connector_canonical_name=connector_canonical_name,
2629    )
2630    rows = query_org_connector_pins(
2631        resolved_org_id,
2632        connector_definition_id=resolved_connector_id,
2633        pinned_version_id=_normalize_optional_version_id(pinned_version_id),
2634        limit=limit,
2635    )
2636    kept_category = _ORIGIN_FILTER_CATEGORIES.get(origin_filter.value)
2637    pins: list[OrgConnectorPin] = []
2638    for row in rows:
2639        origin_type = row.get("origin_type")
2640        if kept_category is not None and _pin_category(origin_type) != kept_category:
2641            continue
2642        rollout_state = row.get("rollout_state")
2643        set_by = row.get("pinned_by_user_email") or row.get("pinned_by_user_name")
2644        created_at = row.get("created_at")
2645        expires_at = row.get("expires_at")
2646        pins.append(
2647            OrgConnectorPin(
2648                connector_definition_id=str(row["connector_definition_id"]),
2649                connector_name=row["connector_name"],
2650                docker_repository=row["docker_repository"],
2651                pinned_version_id=str(row["pinned_version_id"]),
2652                pinned_version_tag=row["pinned_version_tag"],
2653                pin_scope_type=str(row["pin_scope_type"]),
2654                scope_id=str(row["scope_id"]),
2655                scope_name=row.get("scope_name"),
2656                pin_category=_pin_category(origin_type),
2657                set_by=str(set_by) if set_by else None,
2658                rollout_id=str(row["rollout_id"]) if row.get("rollout_id") else None,
2659                rollout_state=rollout_state,
2660                is_active_rollout=rollout_state in _ACTIVE_ROLLOUT_STATES,
2661                description=row.get("description"),
2662                reference_url=row.get("reference_url"),
2663                created_at=created_at.isoformat() if created_at else None,
2664                expires_at=expires_at.isoformat() if expires_at else None,
2665            )
2666        )
2667    return pins
2668
2669
2670# =============================================================================
2671# Health and Population Summary Models and Tools
2672# =============================================================================
2673
2674
2675def _resolve_connector_target(
2676    *,
2677    connector_version_id: str | None,
2678    connector_name: str | None,
2679    connector_version: str | None,
2680    connector_definition_id: str | None,
2681    connector_canonical_name: str | None,
2682) -> tuple[str | None, str, str, str | None]:
2683    """Resolve mixed connector inputs to a common target tuple.
2684
2685    Returns `(version_id, definition_id, docker_repository, docker_image_tag)`.
2686    `version_id` and `docker_image_tag` are `None` when only a definition-level
2687    identifier was supplied.
2688    """
2689    if connector_version_id is not None:
2690        info = resolve_version_info(connector_version_id)
2691        return (
2692            connector_version_id,
2693            str(info["actor_definition_id"]),
2694            info["docker_repository"],
2695            info.get("docker_image_tag"),
2696        )
2697    if connector_name is not None and connector_version is not None:
2698        docker_repository = f"airbyte/{connector_name}"
2699        info = resolve_version_id_by_tag(
2700            docker_repository=docker_repository,
2701            docker_image_tag=connector_version,
2702        )
2703        return (
2704            str(info["version_id"]),
2705            str(info["actor_definition_id"]),
2706            docker_repository,
2707            connector_version,
2708        )
2709
2710    definition_id: str | None = None
2711    if connector_definition_id is not None:
2712        definition_id = connector_definition_id
2713    elif connector_canonical_name is not None:
2714        definition_id = resolve_canonical_name_to_definition_id(
2715            canonical_name=connector_canonical_name,
2716        )
2717    if definition_id is None:
2718        raise PyAirbyteInputError(
2719            message=(
2720                "Provide one of: `connector_version_id`, "
2721                "`connector_name` + `connector_version`, "
2722                "`connector_definition_id`, or `connector_canonical_name`."
2723            ),
2724        )
2725    versions = query_connector_versions(definition_id)
2726    if not versions:
2727        raise PyAirbyteInputError(
2728            message=f"No connector versions found for definition: {definition_id}",
2729        )
2730    return (None, definition_id, versions[0]["docker_repository"], None)
2731
2732
2733class ConnectorPopulationSummary(BaseModel):
2734    """Applied vs potential pinning audience for a connector, split by tier."""
2735
2736    connector_definition_id: str = Field(description="The connector definition UUID")
2737    connector_version_id: str | None = Field(
2738        default=None,
2739        description="The version UUID, when a specific version was requested",
2740    )
2741    docker_repository: str = Field(description="Docker repository path")
2742    docker_image_tag: str | None = Field(
2743        default=None, description="Docker image tag, when a version was requested"
2744    )
2745    customer_tier_filter: str = Field(
2746        description="Tier filter applied to the counts (`TIER_0`/`TIER_1`/`TIER_2`/`UNKNOWN`/`ALL`)"
2747    )
2748    active: TierSummary = Field(
2749        description=(
2750            "Potential audience: enabled actors of the definition (those with at "
2751            "least one active connection, `status = 'active'`), by tier"
2752        )
2753    )
2754    pinned_any: TierSummary = Field(
2755        description="Active actors already pinned to any version, by tier"
2756    )
2757    eligible: TierSummary = Field(
2758        description="Active actors not pinned to any version (available to pin), by tier"
2759    )
2760    pinned_to_version: TierSummary | None = Field(
2761        default=None,
2762        description=(
2763            "Applied audience: actors pinned to the requested version, by tier. "
2764            "`None` when no specific version was requested."
2765        ),
2766    )
2767
2768
2769class ConnectorVersionHealthSummary(BaseModel):
2770    """Four-bucket health rollup for the actors running a connector version."""
2771
2772    connector_version_id: str = Field(description="The connector version UUID")
2773    connector_definition_id: str = Field(description="The connector definition UUID")
2774    docker_repository: str = Field(description="Docker repository path")
2775    docker_image_tag: str | None = Field(
2776        default=None, description="Docker image tag for this version"
2777    )
2778    days: int = Field(description="Lookback window in days")
2779    customer_tier_filter: str = Field(
2780        description="Tier filter applied to the counts (`TIER_0`/`TIER_1`/`TIER_2`/`UNKNOWN`/`ALL`)"
2781    )
2782    healthy: int = Field(description="Actors with at least one successful sync")
2783    unhealthy: int = Field(
2784        description="Actors with failures and no successes in the window"
2785    )
2786    awaiting: int = Field(
2787        description="Actors that ran but produced only non-terminal jobs (no result yet)"
2788    )
2789    disabled: int = Field(
2790        description=(
2791            "Actors pinned to the version that produced no jobs in the window — "
2792            "the dormant/inactive audience"
2793        )
2794    )
2795    total_actors: int = Field(description="Total actors counted across all states")
2796    healthy_by_tier: TierSummary = Field(description="Healthy actors by tier")
2797    unhealthy_by_tier: TierSummary = Field(description="Unhealthy actors by tier")
2798    awaiting_by_tier: TierSummary = Field(description="Awaiting-results actors by tier")
2799    disabled_by_tier: TierSummary = Field(description="Disabled actors by tier")
2800
2801
2802@mcp_tool(
2803    read_only=True,
2804    idempotent=True,
2805    open_world=True,
2806)
2807def query_connector_population_summary(
2808    connector_version_id: Annotated[
2809        str | None,
2810        Field(
2811            description=(
2812                "Connector version UUID. When provided, the applied audience "
2813                "(`pinned_to_version`) is included. Provide this OR "
2814                "`connector_name` + `connector_version` OR a definition-level "
2815                "identifier."
2816            ),
2817        ),
2818    ] = None,
2819    connector_name: Annotated[
2820        str | None,
2821        Field(
2822            description=(
2823                "Canonical connector name (e.g. `source-postgres`). Used with "
2824                "`connector_version` to resolve the version UUID."
2825            ),
2826        ),
2827    ] = None,
2828    connector_version: Annotated[
2829        str | None,
2830        Field(
2831            description=(
2832                "Semver version tag (e.g. `0.3.59`). Used with `connector_name`."
2833            ),
2834        ),
2835    ] = None,
2836    connector_definition_id: Annotated[
2837        str | None,
2838        Field(
2839            description=(
2840                "Connector definition UUID for a definition-level summary "
2841                "(no `pinned_to_version` breakdown)."
2842            ),
2843        ),
2844    ] = None,
2845    connector_canonical_name: Annotated[
2846        str | None,
2847        Field(
2848            description=(
2849                "Canonical connector name resolved to a definition ID via the "
2850                "registry, for a definition-level summary."
2851            ),
2852        ),
2853    ] = None,
2854    customer_tier_filter: Annotated[
2855        TierFilter,
2856        Field(
2857            description=(
2858                "Which customer tiers to count. Defaults to `TIER_2`; pass "
2859                "`ALL` to include TIER_0/TIER_1 (revenue-critical) customers."
2860            ),
2861        ),
2862    ] = "TIER_2",
2863) -> ConnectorPopulationSummary:
2864    """Summarize the applied vs potential pinning audience for a connector, by tier.
2865
2866    Answers "how many actors are pinned and how many are eligible for pinning,
2867    split by tier" — the population view analogous to a rollout's audience.
2868
2869    - `active`: the potential audience — non-tombstoned actors of the
2870      definition that have at least one *active* connection
2871      (`connection.status = 'active'`). Inactive/disabled and deprecated
2872      connections are excluded, so this reflects the enabled, rollout-touchable
2873      population rather than every actor ever created.
2874    - `pinned_any`: active actors that already have an effective
2875      `connector_version` pin at any scope (actor/workspace/org).
2876    - `eligible`: `active` minus `pinned_any` — actors available to pin.
2877    - `pinned_to_version`: the applied audience for the requested version
2878      (only when a version identifier was provided).
2879
2880    Backed by `scoped_configuration` + actor/connection tables, so it is cheap
2881    to compute. Accepts a version identifier (preferred, adds
2882    `pinned_to_version`) or a definition-level identifier.
2883    """
2884    version_id, definition_id, docker_repository, docker_image_tag = (
2885        _resolve_connector_target(
2886            connector_version_id=connector_version_id,
2887            connector_name=connector_name,
2888            connector_version=connector_version,
2889            connector_definition_id=connector_definition_id,
2890            connector_canonical_name=connector_canonical_name,
2891        )
2892    )
2893    is_destination = not is_source_connector(docker_repository)
2894
2895    population_rows = query_actor_population_by_org(
2896        actor_definition_id=definition_id,
2897        is_destination=is_destination,
2898    )
2899    pinned_version_rows = (
2900        query_actors_pinned_to_version(version_id) if version_id is not None else None
2901    )
2902    summary = summarize_population(
2903        population_rows,
2904        pinned_version_rows=pinned_version_rows,
2905        tier_filter=customer_tier_filter,
2906        # The population query above is run without a `target_version_id`, so the
2907        # version-aware summaries do not apply (the per-version audience comes
2908        # from `pinned_version_rows` instead).
2909        has_target_version=False,
2910    )
2911    return ConnectorPopulationSummary(
2912        connector_definition_id=definition_id,
2913        connector_version_id=version_id,
2914        docker_repository=docker_repository,
2915        docker_image_tag=docker_image_tag,
2916        customer_tier_filter=customer_tier_filter,
2917        active=summary.active_by_tier,
2918        pinned_any=summary.pinned_any_by_tier,
2919        eligible=summary.eligible_by_tier,
2920        pinned_to_version=summary.pinned_to_version_by_tier,
2921    )
2922
2923
2924@mcp_tool(
2925    read_only=True,
2926    idempotent=True,
2927    open_world=True,
2928)
2929def query_connector_version_health_summary(
2930    connector_version_id: Annotated[
2931        str | None,
2932        Field(
2933            description=(
2934                "Connector version UUID. Provide this OR "
2935                "`connector_name` + `connector_version`."
2936            ),
2937        ),
2938    ] = None,
2939    connector_name: Annotated[
2940        str | None,
2941        Field(
2942            description=(
2943                "Canonical connector name (e.g. `source-postgres`). Used with "
2944                "`connector_version` to resolve the version UUID."
2945            ),
2946        ),
2947    ] = None,
2948    connector_version: Annotated[
2949        str | None,
2950        Field(
2951            description=(
2952                "Semver version tag (e.g. `0.3.59`). Used with `connector_name`."
2953            ),
2954        ),
2955    ] = None,
2956    days: Annotated[
2957        int,
2958        Field(
2959            description="Number of days to look back (default: 7, max: 30)",
2960            ge=1,
2961            le=30,
2962        ),
2963    ] = 7,
2964    include_pinned_disabled: Annotated[
2965        bool,
2966        Field(
2967            description=(
2968                "If `True` (default), actors pinned to the version that ran no "
2969                "jobs in the window are counted as `disabled`."
2970            ),
2971        ),
2972    ] = True,
2973    customer_tier_filter: Annotated[
2974        TierFilter,
2975        Field(
2976            description=(
2977                "Which customer tiers to count. Defaults to `TIER_2`; pass "
2978                "`ALL` to include TIER_0/TIER_1 (revenue-critical) customers."
2979            ),
2980        ),
2981    ] = "TIER_2",
2982) -> ConnectorVersionHealthSummary:
2983    """Summarize actor health for a connector version into four buckets.
2984
2985    Answers "how many actors on a version are healthy / unhealthy / awaiting /
2986    disabled". Classification per actor over the lookback window:
2987
2988    - `healthy`: at least one successful sync (the same success signal the
2989      autopilot health gate uses).
2990    - `unhealthy`: failures and no successes.
2991    - `awaiting`: ran but produced only non-terminal jobs (no result yet).
2992    - `disabled`: (when `include_pinned_disabled`) pinned to the version with no
2993      jobs at all in the window — the dormant/inactive audience.
2994
2995    Built on the attempt/version primitive — the version stamped into
2996    `jobs.config` at job-creation time — not the current pin state, so it
2997    reflects actors that actually ran this version. This scans jobs over the
2998    window and is more expensive than the population summary; keep `days`
2999    bounded and query per-version.
3000    """
3001    if connector_version_id is None and not (
3002        connector_name is not None and connector_version is not None
3003    ):
3004        raise PyAirbyteInputError(
3005            message=(
3006                "Provide either `connector_version_id` or both "
3007                "`connector_name` and `connector_version`."
3008            ),
3009        )
3010    version_id, definition_id, docker_repository, docker_image_tag = (
3011        _resolve_connector_target(
3012            connector_version_id=connector_version_id,
3013            connector_name=connector_name,
3014            connector_version=connector_version,
3015            connector_definition_id=None,
3016            connector_canonical_name=None,
3017        )
3018    )
3019    assert version_id is not None
3020    is_destination = not is_source_connector(docker_repository)
3021
3022    health_rows = query_version_actor_health(
3023        version_id,
3024        is_destination=is_destination,
3025        days=days,
3026        connector_definition_id=definition_id,
3027    )
3028    pinned_actor_rows = (
3029        query_actors_pinned_to_version(version_id) if include_pinned_disabled else None
3030    )
3031    summary = summarize_version_health(
3032        health_rows,
3033        pinned_actor_rows=pinned_actor_rows,
3034        tier_filter=customer_tier_filter,
3035    )
3036    return ConnectorVersionHealthSummary(
3037        connector_version_id=version_id,
3038        connector_definition_id=definition_id,
3039        docker_repository=docker_repository,
3040        docker_image_tag=docker_image_tag,
3041        days=days,
3042        customer_tier_filter=customer_tier_filter,
3043        healthy=summary.healthy,
3044        unhealthy=summary.unhealthy,
3045        awaiting=summary.awaiting,
3046        disabled=summary.disabled,
3047        total_actors=summary.total_actors,
3048        healthy_by_tier=summary.healthy_by_tier,
3049        unhealthy_by_tier=summary.unhealthy_by_tier,
3050        awaiting_by_tier=summary.awaiting_by_tier,
3051        disabled_by_tier=summary.disabled_by_tier,
3052    )
3053
3054
3055def register_prod_db_ops_tools(app: FastMCP) -> None:
3056    """Register prod DB query tools with the FastMCP app."""
3057    register_mcp_tools(app, mcp_module=__name__)