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.

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_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.

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### Machines / agents → headless bearer token
169
170There is **no** transport mode that accepts a raw `client_id` + `client_secret`
171in a header. A headless agent **mints its own short-lived bearer token** and
172sends it as `Authorization: Bearer <token>`; the server verifies the signature
173(no browser, no stored/rotating refresh token).
174
175The server verifies tokens against whatever realm the deployment configures via
176the `AIRBYTE_MCP_AUTH_*` env values below. Against the hosted Airbyte Cloud MCP
177(configured for Airbyte Cloud's application-client realm), the agent mints an
178Airbyte Cloud access token from its
179`AIRBYTE_CLOUD_CLIENT_ID` / `AIRBYTE_CLOUD_CLIENT_SECRET` (the
180`https://api.airbyte.com/v1/applications/token` endpoint) and sends it as the
181bearer. That single token both authenticates transport (verified by the server)
182and authorizes downstream Cloud API calls, because an Airbyte-Cloud-issued token
183is itself a valid Cloud API bearer. Tokens are short-lived (~15 min), so
184re-mint on expiry / on a `401` rather than pinning a static token.
185
186Clients that support HTTP transports can pass the token via a `headers` block in
187their MCP config:
188
189```json
190{
191  "mcpServers": {
192    "airbyte": {
193      "url": "https://<host>/mcp",
194      "headers": {
195        "Authorization": "Bearer ${AIRBYTE_MCP_TOKEN}"
196      }
197    }
198  }
199}
200```
201
202### Server environment variables (HTTP mode)
203
204The auth vars use this server's branded `AIRBYTE_MCP_*` namespace. This server
205declares only the env var *names* and reads them; the concrete *values* (a
206realm's JWKS URI, issuer, audience, discovery URL, etc.) are supplied at deploy
207time by the deployment's own repo — none are baked in here. The headless
208verifier activates once a signing-key source (JWKS URI or static public key) is
209set; the interactive path activates once the OIDC client credentials are set.
210`MCP_SERVER_URL` is a deployment URL (not an auth var) and stays unbranded.
211
212- `MCP_SERVER_URL` — public base URL of the server (also used for OIDC redirect
213  callbacks); defaults to `http://localhost:8080`.
214- `AIRBYTE_MCP_ALLOWED_HOSTS` — comma-separated allowed hostnames or `fnmatch`
215  patterns for HTTP `Host` and `Origin` validation. Ports are ignored: an entry
216  may carry one for readability, but matching is on hostname only, so
217  `example.com:8443` also allows `example.com` on any port.
218- `AIRBYTE_MCP_HTTP_HOST` — host interface to bind for the HTTP server (defaults
219  to `0.0.0.0`).
220- `AIRBYTE_MCP_OIDC_CLIENT_ID`, `AIRBYTE_MCP_OIDC_CLIENT_SECRET` — enable
221  interactive OIDC (both required).
222- `AIRBYTE_MCP_OIDC_CONFIG_URL` — OIDC discovery URL (required when the client
223  credentials are set).
224- `AIRBYTE_MCP_OIDC_CLIENT_STORAGE_FACTORY` — optional `"package.module:callable"`
225  naming a durable OAuth-state store factory for the interactive proxy (defaults
226  to in-memory).
227- `AIRBYTE_MCP_AUTH_JWKS_URI` / `AIRBYTE_MCP_AUTH_JWT_PUBLIC_KEY` — JWKS URL or
228  static public key for verifying headless tokens (one activates the verifier).
229- `AIRBYTE_MCP_AUTH_ISSUER` / `AIRBYTE_MCP_AUTH_AUDIENCE` /
230  `AIRBYTE_MCP_AUTH_ALGORITHM` — expected `iss` / `aud` claims and signing
231  algorithm.
232
233For stateless HTTP clients that need MCP Apps `interactive-ui` tools, clients
234that declare extensions at initialize receive a self-describing `Mcp-Session-Id`
235which spec-compliant clients echo on subsequent requests. Clients that do not
236echo session IDs can use the explicit fallback
237`X-MCP-Extensions: io.modelcontextprotocol/ui` header on each request instead.
238Multiple extension IDs may be comma-separated (recommended) or
239whitespace-separated.
240The stateless capability-token middleware and extension resolver are provided
241by the installed `fastmcp-extensions` package.
242
243The eventual spec-aligned replacement is per-request `_meta` under
244`io.modelcontextprotocol/clientCapabilities`. That path exists in the modern
245`mcp` 2.x server architecture, while this project currently resolves the
246legacy `fastmcp` 3.x and `mcp` 1.x stack. Using it requires a stack migration
247rather than a version-only change.
248
249With no auth variables set, the HTTP server falls back to unauthenticated local
250behavior. This server maps the `AIRBYTE_MCP_*` variables into the typed config
251objects consumed by
252[`fastmcp-extensions`](https://github.com/airbytehq/fastmcp-extensions), which
253assembles the verifier(s) and reads no environment variables itself.
254
255## Troubleshooting
256
257### Troubleshooting Local Connector Installation Issues
258
259The MCP server uses PyAirbyte under the hood to manage Airbyte connectors. PyAirbyte
260supports both Python-native connectors (installed via pip/uv) and Docker-based connectors
261(run in containers).
262
263To ensure docker connectors run correctly, please make sure `which docker` returns a valid
264path and that Docker Desktop (or an alternative container runtime) is running.
265
266To ensure Python connectors run correctly, please make sure the Python version used to run the
267MCP server is compatible with the connector requirements. See the MCP server conifiguration
268section above for details on how to specify the Python version used by the MCP server.
269
270### Using Abolute Paths
271
272**Always use absolute paths in your environment files.** Relative paths, tilde (`~`), or
273environment variables like `$HOME` will not work correctly, due to the way MCP servers
274are loaded and executed.
275
276The `AIRBYTE_PROJECT_DIR` environment variable is critical - it specifies where PyAirbyte
277stores connector artifacts, cache files, and temporary data. Ensure this directory:
278
279- Uses an absolute path. (For example: `/Users/username/airbyte-projects`.)
280- Exists on the filesystem. (Use `mkdir -p /path/to/dir` to create it if needed.)
281- Is writable by the user account running the MCP server.
282
283Note:
284- In rare cases, your agent may not be able to find `uv` or `uvx` if they are not in the system
285  `PATH` or if the agent has a stale `PATH` value. In these cases, you can use `which uvx` from
286  your own terminal to discover the full path to the `uvx` binary, and then provide the full path
287  in your MCP configuration file.
288
289### Securing Your Secrets
290
291The MCP server implements a security model that protects your credentials:
292
293- **LLM sees only environment variable names** - The AI assistant can see which variables
294  are available (e.g., `POSTGRES_PASSWORD`) but never their actual values.
295- **MCP server reads actual values** - Only the MCP server process accesses the secret
296  values when executing operations.
297- **Credentials never exposed to LLM** - Your API keys, passwords, and other secrets remain secure.
298
299This design allows AI assistants to help configure connectors without compromising security.
300
301Note: While the MCP server takes steps to secure your credentials, you are responsible for
302ensuring the agent is not given access to your secrets by other means. For example, Claude Code
303may have *full* local disk access when run in certain modes. Consult your agent's documentation
304for details on securing local files.
305
306## Contributing to the Airbyte MCP Server
307
308- [PyAirbyte Contributing Guide](https://github.com/airbytehq/PyAirbyte/blob/main/docs/CONTRIBUTING.md)
309
310### Additional resources
311
312- [Airbyte AI Agents Documentation Home](https://docs.airbyte.com/ai-agents/)
313- [MCP Documentation Home](https://modelcontextprotocol.io/)
314
315For issues and questions:
316- [PyAirbyte GitHub Issues](https://github.com/airbytehq/pyairbyte/issues)
317- [PyAirbyte Discussions](https://github.com/airbytehq/pyairbyte/discussions)
318
319"""  # noqa: D415
320
321from airbyte.mcp import agents, cloud, interactive, local, prompts, registry
322
323
324__all__: list[str] = [
325    "agents",
326    "cloud",
327    "interactive",
328    "local",
329    "prompts",
330    "registry",
331]
332
333__docformat__ = "google"