airbyte.mcp

Airbyte Replication MCP Server - Model Context Protocol Integration

NOTE: This MCP server implementation is experimental and may change without notice between minor versions of PyAirbyte. The API may be modified or entirely refactored in future versions.

The Airbyte Replication MCP (Model Context Protocol) server provides a standardized interface for managing Airbyte connectors through MCP-compatible clients. This PyAirbyte-powered experimental feature allows you to list connectors, validate configurations, and run sync operations using the MCP protocol.

Getting Started with Airbyte Replication MCP

To get started with the Airbyte Replication MCP server, follow these steps:

Create a Dotenv secrets file.
Register the MCP server with your MCP client.
Test the MCP server connection using your MCP client.

Step 1: Generate a Dotenv Secrets File

To get started with the Airbyte Replication MCP server, you will need to create a dotenv file containing your Airbyte Cloud credentials, as well as credentials for any third-party services you wish to connect to via Airbyte.

Create a file named ~/.mcp/airbyte_mcp.env with the following content:

# Airbyte Project Artifacts Directory
AIRBYTE_PROJECT_DIR=/path/to/any/writeable/project-dir

# Airbyte Cloud Credentials (Required for Airbyte Cloud Operations)
AIRBYTE_CLOUD_CLIENT_ID=your_api_key
AIRBYTE_CLOUD_CLIENT_SECRET=your_api_secret
AIRBYTE_CLOUD_WORKSPACE_ID=your_workspace_id

# API-Specific Credentials (Optional, depending on your connectors)

# For example, for a PostgreSQL source connector:
# POSTGRES_HOST=your_postgres_host
# POSTGRES_PORT=5432
# POSTGRES_DB=your_database_name
# POSTGRES_USER=your_database_user
# POSTGRES_PASSWORD=your_database_password

# For example, for a Stripe source connector:
# STRIPE_API_KEY=your_stripe_api_key
# STRIPE_API_SECRET=your_stripe_api_secret
# STRIPE_WEBHOOK_SECRET=your_stripe_webhook_secret

Note:

You can add more environment variables to this file as needed for different connectors. To start, you only need to create the file and pass it to the MCP server.
Ensure that this file is kept secure, as it contains sensitive information. Your LLM should never be given direct access to this file or its contents.
The MCP tools will give your LLM the ability to view which variables are available, but it does not give access to their values.
The AIRBYTE_PROJECT_DIR variable specifies a directory where the MCP server can store temporary project files. Ensure this directory is writable by the user running the MCP server.

Step 2: Registering the MCP Server

First install uv (brew install uv).

Then, create a file named server_config.json (or the file name required by your MCP client) with the following content. This uses uvx (from brew install uv) to run the MCP server. If a matching version Python is not yet installed, a uv-managed Python version will be installed automatically. This will also auto-update to use the "latest" Airbyte MCP release at time of launch. You can alternatively pin to a specific version of Python and/or of the Airbyte library if you have special requirements.

{
  "mcpServers": {
    "airbyte": {
      "command": "uvx",
      "args": [
        "--python=3.11",
        "--from=airbyte@latest",
        "airbyte-mcp"
      ],
      "env": {
        "AIRBYTE_MCP_ENV_FILE": "/path/to/my/.mcp/airbyte_mcp.env",
        "AIRBYTE_CLOUD_MCP_SAFE_MODE": "1",
        "AIRBYTE_CLOUD_MCP_READONLY_MODE": "0"
      }
    }
  }
}

Note:

Replace /path/to/my/.mcp/airbyte_mcp.env with the absolute path to your dotenv file created in Step 1.

Step 3: Testing the MCP Server Connection

You can test the MCP server connection using your MCP client.

Helpful prompts to try:

"Use your MCP tools to list all available Airbyte connectors."
"Use your MCP tools to get information about the Airbyte Stripe connector."
"Use your MCP tools to list all variables you have access to in the dotenv secrets file."
"Use your MCP tools to check your connection to your Airbyte Cloud workspace."
"Use your MCP tools to list all available destinations in my Airbyte Cloud workspace."

Airbyte Cloud MCP Server Safety

The Airbyte Replication MCP server supports environment variables to control safety and access levels for Airbyte Cloud operations.

Important: The below settings only affect Cloud operations; local operations are not affected.

Airbyte Cloud Safe Mode

Safe mode is enabled by default and is controlled by the AIRBYTE_CLOUD_MCP_SAFE_MODE environment variable.

When enabled, write operations are allowed but destructive operations (updates, deletions) are only allowed for objects created within the same session. For example, you can create a new connector and then delete it, but you cannot delete an existing connector that was not created in the current session. Modifications to configurations are likewise treated as potentially destructive and are only allowed for objects created in the current session.

Set the environment variable AIRBYTE_CLOUD_MCP_SAFE_MODE=0 to disable safe mode.

Airbyte Cloud Read-Only Mode

Read-only mode is not enabled by default and is controlled by the AIRBYTE_CLOUD_MCP_READONLY_MODE environment variable.

When enabled, only read-only Cloud tools are available. Write and destructive operations are disabled.

This mode does allow running syncs on existing connectors, since sync operations are not considered to be modifications of the Airbyte Cloud workspace.

Set the environment variable AIRBYTE_CLOUD_MCP_READONLY_MODE=1 to enable read-only mode.

Authentication for Remote (HTTP) Servers

The steps above run the MCP server over stdio — the client launches the server process locally, so there is no transport-layer auth and the only credentials that matter are your Airbyte Cloud creds in the dotenv file.

When the server is instead exposed over HTTP (airbyte-mcp-http / poe mcp-serve-http), transport auth verifies an Authorization: Bearer <token> on every request once it is configured. Auth is driven entirely by the AIRBYTE_MCP_* env values a deployment sets — the hosted Airbyte Cloud MCP deployment supplies its realm's values, and a self-hosted deployment supplies its own. Two client shapes are supported on the same deployment (combined automatically when both are configured):

Humans → interactive OIDC

Set AIRBYTE_MCP_OIDC_CLIENT_ID, AIRBYTE_MCP_OIDC_CLIENT_SECRET, and AIRBYTE_MCP_OIDC_CONFIG_URL (the OIDC discovery URL). Interactive clients open a browser (Keycloak Authorization Code + PKCE) and the resulting token is verified by the server. No bearer token to manage by hand.

SSO customers. Airbyte Cloud SSO customers sign in through their own Keycloak realm, named after their company identifier. When the deployment also sets AIRBYTE_MCP_SSO_OIDC_CONFIG_URL_TEMPLATE, every interactive login first shows a small page served by the MCP server at /auth/login with two choices: continue with a regular Airbyte Cloud account, or type the company identifier (the same one used on the Cloud webapp's /sso page) to sign in with SSO. The server then runs the same Authorization Code + PKCE flow against that realm, and the token it verifies and forwards to the Cloud API is an SSO-realm token. This requires the deployment's OIDC client to exist, with the same client id, secret, and callback URL, in every SSO realm; Airbyte Cloud provisions that automatically.

Machines / agents → headless bearer token

There is no transport mode that accepts a raw client_id + client_secret in a header. A headless agent mints its own short-lived bearer token and sends it as Authorization: Bearer <token>; the server verifies the signature (no browser, no stored/rotating refresh token).

The server verifies tokens against whatever realm the deployment configures via the AIRBYTE_MCP_AUTH_* env values below. Against the hosted Airbyte Cloud MCP (configured for Airbyte Cloud's application-client realm), the agent mints an Airbyte Cloud access token from its AIRBYTE_CLOUD_CLIENT_ID / AIRBYTE_CLOUD_CLIENT_SECRET (the https://api.airbyte.com/v1/applications/token endpoint) and sends it as the bearer. That single token both authenticates transport (verified by the server) and authorizes downstream Cloud API calls, because an Airbyte-Cloud-issued token is itself a valid Cloud API bearer. Tokens are short-lived (~15 min), so re-mint on expiry / on a 401 rather than pinning a static token.

Clients that support HTTP transports can pass the token via a headers block in their MCP config:

{
  "mcpServers": {
    "airbyte": {
      "url": "https://<host>/mcp",
      "headers": {
        "Authorization": "Bearer ${AIRBYTE_MCP_TOKEN}"
      }
    }
  }
}

Server environment variables (HTTP mode)

The auth vars use this server's branded AIRBYTE_MCP_* namespace. This server declares only the env var names and reads them; the concrete values (a realm's JWKS URI, issuer, audience, discovery URL, etc.) are supplied at deploy time by the deployment's own repo — none are baked in here. The headless verifier activates once a signing-key source (JWKS URI or static public key) is set; the interactive path activates once the OIDC client credentials are set. MCP_SERVER_URL is a deployment URL (not an auth var) and stays unbranded.

MCP_SERVER_URL — public base URL of the server (also used for OIDC redirect callbacks); defaults to http://localhost:8080.
AIRBYTE_MCP_ALLOWED_HOSTS — comma-separated allowed hostnames or fnmatch patterns for HTTP Host and Origin validation. Ports are ignored: an entry may carry one for readability, but matching is on hostname only, so example.com:8443 also allows example.com on any port.
AIRBYTE_MCP_HTTP_HOST — host interface to bind for the HTTP server (defaults to 0.0.0.0).
AIRBYTE_MCP_OIDC_CLIENT_ID, AIRBYTE_MCP_OIDC_CLIENT_SECRET — enable interactive OIDC (both required).
AIRBYTE_MCP_OIDC_CONFIG_URL — OIDC discovery URL (required when the client credentials are set).
AIRBYTE_MCP_OIDC_CLIENT_STORAGE_FACTORY — optional "package.module:callable" naming a durable OAuth-state store factory for the interactive proxy (defaults to in-memory).
AIRBYTE_MCP_SSO_OIDC_CONFIG_URL_TEMPLATE — optional; enables SSO realm login. The default realm's discovery URL with the realm name replaced by {realm}, e.g. https://cloud.airbyte.com/auth/realms/{realm}/.well-known/openid-configuration. Requires the interactive OIDC vars above.
AIRBYTE_MCP_SSO_IDP_HINT — optional identity-provider alias forwarded as Keycloak's kc_idp_hint on SSO logins (default on Airbyte Cloud), so the realm hands straight off to the customer IdP.
AIRBYTE_MCP_AUTH_JWKS_URI / AIRBYTE_MCP_AUTH_JWT_PUBLIC_KEY — JWKS URL or static public key for verifying headless tokens (one activates the verifier).
AIRBYTE_MCP_AUTH_ISSUER / AIRBYTE_MCP_AUTH_AUDIENCE / AIRBYTE_MCP_AUTH_ALGORITHM — expected iss / aud claims and signing algorithm.

For stateless HTTP clients that need MCP Apps interactive-ui tools, clients that declare extensions at initialize receive a self-describing Mcp-Session-Id which spec-compliant clients echo on subsequent requests. Clients that do not echo session IDs can use the explicit fallback X-MCP-Extensions: io.modelcontextprotocol/ui header on each request instead. Multiple extension IDs may be comma-separated (recommended) or whitespace-separated. The stateless capability-token middleware and extension resolver are provided by the installed fastmcp-extensions package.

The eventual spec-aligned replacement is per-request _meta under io.modelcontextprotocol/clientCapabilities. That path exists in the modern mcp 2.x server architecture, while this project currently resolves the legacy fastmcp 3.x and mcp 1.x stack. Using it requires a stack migration rather than a version-only change.

With no auth variables set, the HTTP server falls back to unauthenticated local behavior. This server maps the AIRBYTE_MCP_* variables into the typed config objects consumed by fastmcp-extensions, which assembles the verifier(s) and reads no environment variables itself.

Optional Hosted Tool Intent Observability

A hosted HTTP deployment may advertise an optional top-level intent argument when its operator sets AIRBYTE_MCP_INTENT_CAPTURE=1. If provided, use one sentence explaining why the tool is being called; never include credentials, identifiers or data values. Calls without intent continue to work. The Agents tools' existing intent parameter serves the same purpose and passes through unchanged to the Agents API; only the trace copy is trimmed and capped. Advertisement and model guidance do not require an export endpoint.

Export is enabled only when an OTLP traces endpoint is configured. The server exports the supplied intent (capped at 4096 characters), tool name, outcome class, validated workspace/organization UUIDs, tool annotations and outbound HTTP methods, recognized public Airbyte API routes with validated UUID/numeric IDs, and statuses. URL queries, unknown routes and custom origins are redacted. Tool arguments and results, error messages/stacks, HTTP header values, request/response bodies, JWTs and caller identity are not exported. Calls to unregistered tool names are dropped. Session grouping uses a SHA-256 digest of the unsigned, client-echoed Mcp-Session-Id, not the raw token or a verified identity. Intent itself is free text and may contain customer information, so keep it free of sensitive data.

Any OTLP backend can receive these spans. With AIRBYTE_MCP_OTEL_VENDOR=datadog, intent is also supplied as Datadog metadata. Export is best effort and does not determine whether a tool call succeeds; the backend controls retention and access. DO_NOT_TRACK continues to govern Segment only; operators control this export with the OTEL_* variables documented in airbyte.mcp.http_main. Segment requests are excluded from traces. Local stdio is unchanged. Hosted clients with cached intent schemas remain compatible after export is disabled by unsetting both OTEL_EXPORTER_OTLP_TRACES_ENDPOINT and OTEL_EXPORTER_OTLP_ENDPOINT. Legacy synthetic telemetry.intent is accepted without advertising it, with top-level intent taking precedence when supplied. Real tool parameters named intent or telemetry retain their normal validation and dispatch behavior.

Troubleshooting

Troubleshooting Local Connector Installation Issues

The MCP server uses PyAirbyte under the hood to manage Airbyte connectors. PyAirbyte supports both Python-native connectors (installed via pip/uv) and Docker-based connectors (run in containers).

To ensure docker connectors run correctly, please make sure which docker returns a valid path and that Docker Desktop (or an alternative container runtime) is running.

To ensure Python connectors run correctly, please make sure the Python version used to run the MCP server is compatible with the connector requirements. See the MCP server conifiguration section above for details on how to specify the Python version used by the MCP server.

Using Abolute Paths

Always use absolute paths in your environment files. Relative paths, tilde (~), or environment variables like $HOME will not work correctly, due to the way MCP servers are loaded and executed.

The AIRBYTE_PROJECT_DIR environment variable is critical - it specifies where PyAirbyte stores connector artifacts, cache files, and temporary data. Ensure this directory:

Uses an absolute path. (For example: /Users/username/airbyte-projects.)
Exists on the filesystem. (Use mkdir -p /path/to/dir to create it if needed.)
Is writable by the user account running the MCP server.

Note:

In rare cases, your agent may not be able to find uv or uvx if they are not in the system PATH or if the agent has a stale PATH value. In these cases, you can use which uvx from your own terminal to discover the full path to the uvx binary, and then provide the full path in your MCP configuration file.

Securing Your Secrets

The MCP server implements a security model that protects your credentials:

LLM sees only environment variable names - The AI assistant can see which variables are available (e.g., POSTGRES_PASSWORD) but never their actual values.
MCP server reads actual values - Only the MCP server process accesses the secret values when executing operations.
Credentials never exposed to LLM - Your API keys, passwords, and other secrets remain secure.

This design allows AI assistants to help configure connectors without compromising security.

Note: While the MCP server takes steps to secure your credentials, you are responsible for ensuring the agent is not given access to your secrets by other means. For example, Claude Code may have full local disk access when run in certain modes. Consult your agent's documentation for details on securing local files.

Contributing to the Airbyte MCP Server

PyAirbyte Contributing Guide

Additional resources

For issues and questions:

View Source

  1# Copyright (c) 2024 Airbyte, Inc., all rights reserved.
  2
  3r"""***Airbyte Replication MCP Server - Model Context Protocol Integration***
  4
  5> **NOTE:**
  6> This MCP server implementation is experimental and may change without notice between minor
  7> versions of PyAirbyte. The API may be modified or entirely refactored in future versions.
  8
  9The Airbyte Replication MCP (Model Context Protocol) server provides a standardized interface
 10for managing Airbyte connectors through MCP-compatible clients. This PyAirbyte-powered
 11experimental feature allows you to list connectors, validate configurations, and run sync
 12operations using the MCP protocol.
 13
 14## Getting Started with Airbyte Replication MCP
 15
 16To get started with the Airbyte Replication MCP server, follow these steps:
 17
 181. Create a Dotenv secrets file.
 192. Register the MCP server with your MCP client.
 203. Test the MCP server connection using your MCP client.
 21
 22### Step 1: Generate a Dotenv Secrets File
 23
 24To get started with the Airbyte Replication MCP server, you will need to create a dotenv
 25file containing your Airbyte Cloud credentials, as well as credentials for any
 26third-party services you wish to connect to via Airbyte.
 27
 28Create a file named `~/.mcp/airbyte_mcp.env` with the following content:
 29
 30```ini
 31# Airbyte Project Artifacts Directory
 32AIRBYTE_PROJECT_DIR=/path/to/any/writeable/project-dir
 33
 34# Airbyte Cloud Credentials (Required for Airbyte Cloud Operations)
 35AIRBYTE_CLOUD_CLIENT_ID=your_api_key
 36AIRBYTE_CLOUD_CLIENT_SECRET=your_api_secret
 37AIRBYTE_CLOUD_WORKSPACE_ID=your_workspace_id
 38
 39# API-Specific Credentials (Optional, depending on your connectors)
 40
 41# For example, for a PostgreSQL source connector:
 42# POSTGRES_HOST=your_postgres_host
 43# POSTGRES_PORT=5432
 44# POSTGRES_DB=your_database_name
 45# POSTGRES_USER=your_database_user
 46# POSTGRES_PASSWORD=your_database_password
 47
 48# For example, for a Stripe source connector:
 49# STRIPE_API_KEY=your_stripe_api_key
 50# STRIPE_API_SECRET=your_stripe_api_secret
 51# STRIPE_WEBHOOK_SECRET=your_stripe_webhook_secret
 52```
 53
 54Note:
 551. You can add more environment variables to this file as needed for different connectors. To start,
 56   you only need to create the file and pass it to the MCP server.
 572. Ensure that this file is kept secure, as it contains sensitive information. Your LLM
 58   *should never* be given direct access to this file or its contents.
 593. The MCP tools will give your LLM the ability to view *which* variables are available, but it
 60   does not give access to their values.
 614. The `AIRBYTE_PROJECT_DIR` variable specifies a directory where the MCP server can
 62   store temporary project files. Ensure this directory is writable by the user running
 63   the MCP server.
 64
 65### Step 2: Registering the MCP Server
 66
 67First install `uv` (`brew install uv`).
 68
 69Then, create a file named `server_config.json` (or the file name required by your MCP client)
 70with the following content. This uses `uvx` (from `brew install uv`) to run the MCP
 71server. If a matching version Python is not yet installed, a `uv`-managed Python
 72version will be installed automatically. This will also auto-update to use the
 73"latest" Airbyte MCP release at time of launch. You can alternatively pin to a
 74specific version of Python and/or of the Airbyte library if you have special
 75requirements.
 76
 77```json
 78{
 79  "mcpServers": {
 80    "airbyte": {
 81      "command": "uvx",
 82      "args": [
 83        "--python=3.11",
 84        "--from=airbyte@latest",
 85        "airbyte-mcp"
 86      ],
 87      "env": {
 88        "AIRBYTE_MCP_ENV_FILE": "/path/to/my/.mcp/airbyte_mcp.env",
 89        "AIRBYTE_CLOUD_MCP_SAFE_MODE": "1",
 90        "AIRBYTE_CLOUD_MCP_READONLY_MODE": "0"
 91      }
 92    }
 93  }
 94}
 95```
 96
 97Note:
 98- Replace `/path/to/my/.mcp/airbyte_mcp.env` with the absolute path to your dotenv file created in
 99  Step 1.
100
101### Step 3: Testing the MCP Server Connection
102
103You can test the MCP server connection using your MCP client.
104
105Helpful prompts to try:
106
1071. "Use your MCP tools to list all available Airbyte connectors."
1082. "Use your MCP tools to get information about the Airbyte Stripe connector."
1093. "Use your MCP tools to list all variables you have access to in the dotenv secrets
110   file."
1114. "Use your MCP tools to check your connection to your Airbyte Cloud workspace."
1125. "Use your MCP tools to list all available destinations in my Airbyte Cloud workspace."
113
114## Airbyte Cloud MCP Server Safety
115
116The Airbyte Replication MCP server supports environment variables to control safety and access
117levels for Airbyte Cloud operations.
118
119**Important:** The below settings only affect Cloud operations; local operations are not affected.
120
121### Airbyte Cloud Safe Mode
122
123Safe mode is enabled by default and is controlled by the `AIRBYTE_CLOUD_MCP_SAFE_MODE` environment
124variable.
125
126When enabled, write operations are allowed but destructive operations (updates, deletions) are
127only allowed for objects created within the same session. For example, you can create a new
128connector and then delete it, but you cannot delete an existing connector that was not created in
129the current session. Modifications to configurations are likewise treated as potentially destructive
130and are only allowed for objects created in the current session.
131
132Set the environment variable `AIRBYTE_CLOUD_MCP_SAFE_MODE=0` to disable safe mode.
133
134### Airbyte Cloud Read-Only Mode
135
136Read-only mode is not enabled by default and is controlled by the
137`AIRBYTE_CLOUD_MCP_READONLY_MODE` environment variable.
138
139When enabled, only read-only Cloud tools are available. Write and destructive operations are
140disabled.
141
142This mode does allow running syncs on existing connectors, since sync operations
143are not considered to be modifications of the Airbyte Cloud workspace.
144
145Set the environment variable `AIRBYTE_CLOUD_MCP_READONLY_MODE=1` to enable read-only mode.
146
147## Authentication for Remote (HTTP) Servers
148
149The steps above run the MCP server over **stdio** — the client launches the
150server process locally, so there is no transport-layer auth and the only
151credentials that matter are your Airbyte Cloud creds in the dotenv file.
152
153When the server is instead exposed over **HTTP** (`airbyte-mcp-http` /
154`poe mcp-serve-http`), transport auth verifies an `Authorization: Bearer
155<token>` on every request once it is configured. Auth is driven entirely by the
156`AIRBYTE_MCP_*` env values a deployment sets — the hosted Airbyte Cloud MCP
157deployment supplies its realm's values, and a self-hosted deployment supplies
158its own. Two client shapes are supported on the same deployment (combined
159automatically when both are configured):
160
161### Humans → interactive OIDC
162
163Set `AIRBYTE_MCP_OIDC_CLIENT_ID`, `AIRBYTE_MCP_OIDC_CLIENT_SECRET`, and
164`AIRBYTE_MCP_OIDC_CONFIG_URL` (the OIDC discovery URL). Interactive clients open
165a browser (Keycloak Authorization Code + PKCE) and the resulting token is
166verified by the server. No bearer token to manage by hand.
167
168**SSO customers.** Airbyte Cloud SSO customers sign in through their own Keycloak
169realm, named after their company identifier. When the deployment also sets
170`AIRBYTE_MCP_SSO_OIDC_CONFIG_URL_TEMPLATE`, every interactive login first shows a
171small page served by the MCP server at `/auth/login` with two choices: continue
172with a regular Airbyte Cloud account, or type the company identifier (the same
173one used on the Cloud webapp's `/sso` page) to sign in with SSO. The server then
174runs the same Authorization Code + PKCE flow against that realm, and the token it
175verifies and forwards to the Cloud API is an SSO-realm token. This requires the
176deployment's OIDC client to exist, with the same client id, secret, and callback
177URL, in every SSO realm; Airbyte Cloud provisions that automatically.
178
179### Machines / agents → headless bearer token
180
181There is **no** transport mode that accepts a raw `client_id` + `client_secret`
182in a header. A headless agent **mints its own short-lived bearer token** and
183sends it as `Authorization: Bearer <token>`; the server verifies the signature
184(no browser, no stored/rotating refresh token).
185
186The server verifies tokens against whatever realm the deployment configures via
187the `AIRBYTE_MCP_AUTH_*` env values below. Against the hosted Airbyte Cloud MCP
188(configured for Airbyte Cloud's application-client realm), the agent mints an
189Airbyte Cloud access token from its
190`AIRBYTE_CLOUD_CLIENT_ID` / `AIRBYTE_CLOUD_CLIENT_SECRET` (the
191`https://api.airbyte.com/v1/applications/token` endpoint) and sends it as the
192bearer. That single token both authenticates transport (verified by the server)
193and authorizes downstream Cloud API calls, because an Airbyte-Cloud-issued token
194is itself a valid Cloud API bearer. Tokens are short-lived (~15 min), so
195re-mint on expiry / on a `401` rather than pinning a static token.
196
197Clients that support HTTP transports can pass the token via a `headers` block in
198their MCP config:
199
200```json
201{
202  "mcpServers": {
203    "airbyte": {
204      "url": "https://<host>/mcp",
205      "headers": {
206        "Authorization": "Bearer ${AIRBYTE_MCP_TOKEN}"
207      }
208    }
209  }
210}
211```
212
213### Server environment variables (HTTP mode)
214
215The auth vars use this server's branded `AIRBYTE_MCP_*` namespace. This server
216declares only the env var *names* and reads them; the concrete *values* (a
217realm's JWKS URI, issuer, audience, discovery URL, etc.) are supplied at deploy
218time by the deployment's own repo — none are baked in here. The headless
219verifier activates once a signing-key source (JWKS URI or static public key) is
220set; the interactive path activates once the OIDC client credentials are set.
221`MCP_SERVER_URL` is a deployment URL (not an auth var) and stays unbranded.
222
223- `MCP_SERVER_URL` — public base URL of the server (also used for OIDC redirect
224  callbacks); defaults to `http://localhost:8080`.
225- `AIRBYTE_MCP_ALLOWED_HOSTS` — comma-separated allowed hostnames or `fnmatch`
226  patterns for HTTP `Host` and `Origin` validation. Ports are ignored: an entry
227  may carry one for readability, but matching is on hostname only, so
228  `example.com:8443` also allows `example.com` on any port.
229- `AIRBYTE_MCP_HTTP_HOST` — host interface to bind for the HTTP server (defaults
230  to `0.0.0.0`).
231- `AIRBYTE_MCP_OIDC_CLIENT_ID`, `AIRBYTE_MCP_OIDC_CLIENT_SECRET` — enable
232  interactive OIDC (both required).
233- `AIRBYTE_MCP_OIDC_CONFIG_URL` — OIDC discovery URL (required when the client
234  credentials are set).
235- `AIRBYTE_MCP_OIDC_CLIENT_STORAGE_FACTORY` — optional `"package.module:callable"`
236  naming a durable OAuth-state store factory for the interactive proxy (defaults
237  to in-memory).
238- `AIRBYTE_MCP_SSO_OIDC_CONFIG_URL_TEMPLATE` — optional; enables SSO realm login.
239  The default realm's discovery URL with the realm name replaced by `{realm}`,
240  e.g. `https://cloud.airbyte.com/auth/realms/{realm}/.well-known/openid-configuration`.
241  Requires the interactive OIDC vars above.
242- `AIRBYTE_MCP_SSO_IDP_HINT` — optional identity-provider alias forwarded as
243  Keycloak's `kc_idp_hint` on SSO logins (`default` on Airbyte Cloud), so the
244  realm hands straight off to the customer IdP.
245- `AIRBYTE_MCP_AUTH_JWKS_URI` / `AIRBYTE_MCP_AUTH_JWT_PUBLIC_KEY` — JWKS URL or
246  static public key for verifying headless tokens (one activates the verifier).
247- `AIRBYTE_MCP_AUTH_ISSUER` / `AIRBYTE_MCP_AUTH_AUDIENCE` /
248  `AIRBYTE_MCP_AUTH_ALGORITHM` — expected `iss` / `aud` claims and signing
249  algorithm.
250
251For stateless HTTP clients that need MCP Apps `interactive-ui` tools, clients
252that declare extensions at initialize receive a self-describing `Mcp-Session-Id`
253which spec-compliant clients echo on subsequent requests. Clients that do not
254echo session IDs can use the explicit fallback
255`X-MCP-Extensions: io.modelcontextprotocol/ui` header on each request instead.
256Multiple extension IDs may be comma-separated (recommended) or
257whitespace-separated.
258The stateless capability-token middleware and extension resolver are provided
259by the installed `fastmcp-extensions` package.
260
261The eventual spec-aligned replacement is per-request `_meta` under
262`io.modelcontextprotocol/clientCapabilities`. That path exists in the modern
263`mcp` 2.x server architecture, while this project currently resolves the
264legacy `fastmcp` 3.x and `mcp` 1.x stack. Using it requires a stack migration
265rather than a version-only change.
266
267With no auth variables set, the HTTP server falls back to unauthenticated local
268behavior. This server maps the `AIRBYTE_MCP_*` variables into the typed config
269objects consumed by
270[`fastmcp-extensions`](https://github.com/airbytehq/fastmcp-extensions), which
271assembles the verifier(s) and reads no environment variables itself.
272
273## Optional Hosted Tool Intent Observability
274
275A hosted HTTP deployment may advertise an optional top-level `intent` argument
276when its operator sets `AIRBYTE_MCP_INTENT_CAPTURE=1`. If provided, use one
277sentence explaining why the tool is being called; never include credentials,
278identifiers or data values. Calls without intent continue to work. The Agents
279tools' existing `intent` parameter serves the same purpose and passes through
280unchanged to the Agents API; only the trace copy is trimmed and capped.
281Advertisement and model guidance do not require an export endpoint.
282
283Export is enabled only when an OTLP traces endpoint is configured. The server
284exports the supplied intent (capped at 4096 characters), tool name, outcome class,
285validated workspace/organization UUIDs, tool annotations and outbound HTTP
286methods, recognized public Airbyte API routes with validated UUID/numeric IDs,
287and statuses. URL queries, unknown routes and custom origins are redacted.
288Tool arguments and results,
289error messages/stacks, HTTP header values, request/response bodies, JWTs and
290caller identity are not exported. Calls to unregistered tool names are dropped.
291Session grouping uses a SHA-256 digest of the unsigned, client-echoed
292`Mcp-Session-Id`, not the raw token or a verified identity. Intent itself is free
293text and may contain customer information, so keep it free of sensitive data.
294
295Any OTLP backend can receive these spans. With `AIRBYTE_MCP_OTEL_VENDOR=datadog`,
296intent is also supplied as Datadog metadata. Export is best effort and does not
297determine whether a tool call succeeds; the backend controls retention and
298access. `DO_NOT_TRACK` continues to govern Segment only; operators control this
299export with the `OTEL_*` variables documented in `airbyte.mcp.http_main`.
300Segment requests are excluded from traces. Local stdio is unchanged. Hosted
301clients with cached `intent` schemas remain compatible after export is
302disabled by unsetting both `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` and
303`OTEL_EXPORTER_OTLP_ENDPOINT`. Legacy synthetic `telemetry.intent` is accepted
304without advertising it, with top-level `intent` taking precedence when supplied.
305Real tool parameters named `intent` or `telemetry` retain their normal validation
306and dispatch behavior.
307
308## Troubleshooting
309
310### Troubleshooting Local Connector Installation Issues
311
312The MCP server uses PyAirbyte under the hood to manage Airbyte connectors. PyAirbyte
313supports both Python-native connectors (installed via pip/uv) and Docker-based connectors
314(run in containers).
315
316To ensure docker connectors run correctly, please make sure `which docker` returns a valid
317path and that Docker Desktop (or an alternative container runtime) is running.
318
319To ensure Python connectors run correctly, please make sure the Python version used to run the
320MCP server is compatible with the connector requirements. See the MCP server conifiguration
321section above for details on how to specify the Python version used by the MCP server.
322
323### Using Abolute Paths
324
325**Always use absolute paths in your environment files.** Relative paths, tilde (`~`), or
326environment variables like `$HOME` will not work correctly, due to the way MCP servers
327are loaded and executed.
328
329The `AIRBYTE_PROJECT_DIR` environment variable is critical - it specifies where PyAirbyte
330stores connector artifacts, cache files, and temporary data. Ensure this directory:
331
332- Uses an absolute path. (For example: `/Users/username/airbyte-projects`.)
333- Exists on the filesystem. (Use `mkdir -p /path/to/dir` to create it if needed.)
334- Is writable by the user account running the MCP server.
335
336Note:
337- In rare cases, your agent may not be able to find `uv` or `uvx` if they are not in the system
338  `PATH` or if the agent has a stale `PATH` value. In these cases, you can use `which uvx` from
339  your own terminal to discover the full path to the `uvx` binary, and then provide the full path
340  in your MCP configuration file.
341
342### Securing Your Secrets
343
344The MCP server implements a security model that protects your credentials:
345
346- **LLM sees only environment variable names** - The AI assistant can see which variables
347  are available (e.g., `POSTGRES_PASSWORD`) but never their actual values.
348- **MCP server reads actual values** - Only the MCP server process accesses the secret
349  values when executing operations.
350- **Credentials never exposed to LLM** - Your API keys, passwords, and other secrets remain secure.
351
352This design allows AI assistants to help configure connectors without compromising security.
353
354Note: While the MCP server takes steps to secure your credentials, you are responsible for
355ensuring the agent is not given access to your secrets by other means. For example, Claude Code
356may have *full* local disk access when run in certain modes. Consult your agent's documentation
357for details on securing local files.
358
359## Contributing to the Airbyte MCP Server
360
361- [PyAirbyte Contributing Guide](https://github.com/airbytehq/PyAirbyte/blob/main/docs/CONTRIBUTING.md)
362
363### Additional resources
364
365- [Airbyte AI Agents Documentation Home](https://docs.airbyte.com/ai-agents/)
366- [MCP Documentation Home](https://modelcontextprotocol.io/)
367
368For issues and questions:
369- [PyAirbyte GitHub Issues](https://github.com/airbytehq/pyairbyte/issues)
370- [PyAirbyte Discussions](https://github.com/airbytehq/pyairbyte/discussions)
371
372"""  # noqa: D415
373
374from airbyte.mcp import agents, cloud, interactive, local, prompts, registry
375
376
377__all__: list[str] = [
378    "agents",
379    "cloud",
380    "interactive",
381    "local",
382    "prompts",
383    "registry",
384]
385
386__docformat__ = "google"