# Agents

## Please Read

Make sure that you leverage human-facing documentation where appropriate, and especially [CONTRIBUTING.md](./CONTRIBUTING.md), which contains common knowledge for both humans and agents who are working within this repo.

- [README.md](./README.md) — project overview and client installation.
- [CONTRIBUTING.md](./CONTRIBUTING.md) — contributor setup, local testing, and development workflows.

## Registry Operations

Registry tools that interact with GCS buckets resolve credentials in this order: (1) `GCS_CREDENTIALS` environment variable (JSON service account key), (2) `GCP_GSM_CREDENTIALS` environment variable (JSON service account key), (3) Application Default Credentials (e.g. `gcloud auth application-default login`). The service account should have read/write access to the dev bucket (`dev-airbyte-cloud-connector-metadata-service-2`) used in registry tests.

Registry compile also reads connector quality metrics from `gs://ab-analytics-connector-metrics/data/connector_quality_metrics/` and needs read access to that bucket. Grant access to each service account that runs registry compile:

```bash
gcloud storage buckets add-iam-policy-binding gs://ab-analytics-connector-metrics \
  --project=ab-analytics-308500 \
  --member="serviceAccount:YOUR_SERVICE_ACCOUNT@YOUR_PROJECT.iam.gserviceaccount.com" \
  --role="roles/storage.objectViewer"
```

### L2 Devin

L2 Devin registry testing usually receives credentials through `GCP_GSM_CREDENTIALS`. Registry code also honors `GCS_CREDENTIALS`; use that name for explicit local overrides when needed.

Current L2 Devin registry testing service account:

```text
devin-connector-integ-testing@dataline-integration-testing.iam.gserviceaccount.com
```

Expected bucket access for that account:

- `gs://prod-airbyte-cloud-connector-metadata-service`: read/list.
- `gs://dev-airbyte-cloud-connector-metadata-service-2`: read/list/write/delete.
- `gs://ab-analytics-connector-metrics`: read/list for registry metrics JSONL.

## Customer Tiers

All MCP tools that operate on customer data are tier-aware. See [docs/customer-tiers.md](./docs/customer-tiers.md) for full details.

Key rules for agents:

- **Every tool defaults to `TIER_2`.** A call that omits `customer_tier_filter` only sees or affects standard (non-sensitive) customers.
- **To operate on TIER_0 or TIER_1 customers**, you must explicitly pass `customer_tier_filter="TIER_0"` (or `"TIER_1"`, or `"ALL"`).
- **Before touching TIER_0 or TIER_1 customers**, escalate to a human using `escalate_to_human`. These are revenue-critical accounts and require human judgment.
- **If a pinning operation returns a tier mismatch error**, the error message includes the actual tier. Use that tier value to retry — but only after human approval.
- **Use `lookup_customer_tiers`** to discover the tier of any workspace, organization, or connection before performing sensitive operations.

## 1Password CLI (`op`)

The `op` CLI is required to retrieve secrets delivered via 1Password share links (used by the `request_devin_secret` MCP tool). If `op` is not already installed, install it with:

```bash
# Install the 1Password CLI (Linux amd64)
curl -sSfo op.zip "https://cache.agilebits.com/dist/1P/op2/pkg/v2.30.3/op_linux_amd64_v2.30.3.zip" \
  && sudo unzip -od /usr/local/bin/ op.zip \
  && rm op.zip
```

After receiving a share link from the secret request workflow, retrieve the secret value with:

```bash
op read '<share_link_url>'
```

No sign-in is required for reading one-time share links.

## Authentication Guidance

When working with a user to set up and use this MCP server, agents should follow these steps for authentication.

### GCP Authentication Flow

For tools that require GCP access, including database queries and secret manager, guide the user through authentication:

1. Check if `gcloud` is installed. If not, install it:

   ```bash
   curl -sSL https://sdk.cloud.google.com | bash -s -- --disable-prompts
   ```

2. Run `gcloud auth login` with `--no-launch-browser` to get a verification URL:

   ```bash
   gcloud auth login --no-launch-browser
   ```

   Send the verification URL to the user and ask them to complete sign-in and provide the verification code.

3. Set up Application Default Credentials for library access:

   ```bash
   gcloud auth application-default login --no-launch-browser
   ```

   Send the verification URL to the user and ask them to complete sign-in and provide the verification code.

4. For database tools, start Cloud SQL Proxy on an available port and use the `USE_CLOUD_SQL_PROXY` and `DB_PORT` environment variables.

### Airbyte Cloud Authentication

For tools that interact with the Airbyte Cloud API, ensure the user has configured:

- `AIRBYTE_CLOUD_CLIENT_ID` and `AIRBYTE_CLOUD_CLIENT_SECRET` in their `.env` file.
- For admin operations, `AIRBYTE_INTERNAL_ADMIN_FLAG=airbyte.io` and `AIRBYTE_INTERNAL_ADMIN_USER`.
