You run Airbyte Core with abctl on a VM or your laptop and when a sync fails, you probably open the UI, select the connection, scroll through the job log, and copy the error into a search engine to figure out why. With the Airbyte MCP, Codex can sift through those logs and search for answers independently. It can:
List your connections Pull the failed job's log Explain the error All that before you need to open a browser tab.
The hosted Airbyte MCP at https://mcp.airbyte.com/mcp only talks to Airbyte Cloud; if you’re on Core, you’ll need to manually give Codex your client ID and secret. Our setup docs put those values directly in your MCP client’s config file. That works, but it puts a long-lived secret in a file you may copy between machines, share with teammates, or check into a dotfiles repo.
This tutorial offers an alternative. In it, I’ll show you how to run the Airbyte MCP server on your own machine and point it at your Core deployment's API. Codex starts the server for you over stdio. You'll keep your Airbyte credentials in an env file outside your project. You’ll also configure approval prompts and secret references to allow Codex to deploy a source without seeing your password.
Prerequisites While you don't need prior experience with MCP or Codex configuration, you will need the following:
A running Airbyte Core deployment. Codex CLI installed and signed in. A UNIX terminal environment. If you’re on a Windows machine, you can run Codex and the server inside WSL. That way, you can use the same commands without the translation into PowerShell syntax. uv, which downloads and runs the Airbyte MCP server. If you use Homebrew, brew install uv works.Internet access from the machine running Codex. The server installs from PyPI and looks up connectors in Airbyte's registry. Step 1: Collect your workspace ID and API credentials The local server signs in to Airbyte with an application's client ID and secret. Core has no browser sign-in for the MCP. So do the following instead:
Open Airbyte in your browser. On a new deployment, finish the setup page and enter your email address. The Airbyte MCP can't find your default workspace until your user has one. Copy the alphanumeric string after /workspaces/ in the URL of any workspace page. You’ll use this as the WORKSPACE_ID in the .env file. Get a client ID and client secret:If you deployed with abctl, run abctl local credentials and copy the Client-Id and Client-Secret values. Otherwise, create an application and copy its client ID and secret. Note your API URL. It's your Airbyte URL followed by /api/public/v1. The abctl default is http://localhost:8000/api/public/v1. You now have the four values the server needs. Keep them out of your terminal history and chat for the next step.
Step 2: Store the credentials in an env file outside your project The server reads an env file named by AIRBYTE_MCP_ENV_FILE, so the secret never has to appear in Codex's config.toml. Put the file in its own directory away from any repository Codex works in. The steps below create the file and folder inside your user directory.
Create a private directory and an empty file:
mkdir -p ~/.airbyte-mcp
chmod 700 ~/.airbyte-mcp
touch ~/.airbyte-mcp/core.env
chmod 600 ~/.airbyte-mcp/core.envOpen ~/.airbyte-mcp/core.env in your editor and add your values:
~/.airbyte-mcp/core.env
AIRBYTE_CLOUD_API_URL =http://localhost:8000 /api/public/v1
AIRBYTE_CLOUD_CLIENT_ID =<CLIENT_ID>
AIRBYTE_CLOUD_CLIENT_SECRET =<CLIENT_SECRET>
AIRBYTE_CLOUD_WORKSPACE_ID =<WORKSPACE_ID>The variables say CLOUD because the server shares its code with the hosted version. Point AIRBYTE_CLOUD_API_URL at your own deployment to switch it to Core. Always set AIRBYTE_CLOUD_WORKSPACE_ID; without it, tools that need a workspace can fail with errors.
Use an editor for this step instead of echo so the secret doesn't land in your shell history. The env file keeps the secret out of prompts and config files, but Codex can still read files on your disk, so keep the directory private and don't ask Codex to open it.
Your credentials now live in one file that only your user can read.
Step 3: Register the server with Codex Codex can add a stdio server from the command line. The -- separates Codex's flags from the command that starts the server.
codex mcp add airbyte \
--env AIRBYTE_MCP_ENV_FILE =/Users/ <you>/.airbyte-mcp/ core.env
-- uvx --python=3.12 --from =airbyte@latest airbyte-mcpuvx --from=airbyte@latest airbyte-mcp downloads the airbyte package into a cached environment and starts its MCP server. To pin a version for your team, replace @latest with an exact version such as airbyte==0.71.2.
You may have noticed that I pinned the Python version to 3.12. The package doesn’t yet support Python 3.13+ just yet.
Use an absolute path for AIRBYTE_MCP_ENV_FILE. The server doesn't expand ~ or $HOME because Codex launches it outside a shell.
That command writes an entry to ~/.codex/config.toml. Open the file and add two timeouts so the entry looks like this:
~/.codex/config.toml
[mcp_servers.airbyte]
command = "uvx"
args = ["--from=airbyte@latest" , "airbyte-mcp" ]
startup_timeout_sec = 60
tool_timeout_sec = 300
default_tools_approval_mode = "writes"
[mcp_servers.airbyte.env]
AIRBYTE_MCP_ENV_FILE = "/Users/<you>/.airbyte-mcp/core.env"
AIRBYTE_MCP_TRUSTED_EXECUTION = "1" Here's what each setting does:
startup_timeout_sec = 60 gives the server time to start. Codex waits 10 seconds by default. In our testing, the first launch took about 30 seconds while uv installed the package, and later launches with @latest still took about 15 seconds while uv checked for updates. With the default, Codex gives up before the server is ready.tool_timeout_sec = 300 covers slow calls like reading a long job log. The default is 30 seconds.default_tools_approval_mode = "writes" makes Codex prompt you before any write tool, so you approve each deploy, config change, and sync.AIRBYTE_MCP_TRUSTED_EXECUTION = "1" lets the server treat your env file as a secret store. Codex can see the variable names through list_dotenv_secrets, which returns names only, and can pass secret_reference::<password> in a connector config. The server swaps in the real value when it calls your Airbyte API.If you want to lock the agent down to read only functionality, replace this field with AIRBYTE_CLOUD_MCP_READONLY_MODE = "1" and delete AIRBYTE_MCP_TRUSTED_EXECUTION = "1".
To make the first launch faster, warm the uv cache before you start Codex:
uvx --python=3.13 --from =airbyte@latest airbyte-mcp < /dev/ null The server starts, sees no input, and exits. The package stays cached.
Codex now knows how to start the Airbyte MCP and where to find its credentials.
Step 4: Confirm the connection Check that Codex sees the entry with the following command:
You should see airbyte as enabled. Don’t worry about the Unsupported value in the Auth column. That’s just for remote servers using a browser to sign in. Codex will instead be using the credentials in the env file to sign in.
Start Codex with codex, then type /mcp to see the active servers. airbyte should be listed with its tools.
Send a first prompt:
Prompt
Which Airbyte workspace am I connected to ? List the sources, destinations,
and connections in it, grouped by type.Codex calls get_default_cloud_context and the list_deployed_cloud_* tools and returns your inventory.
The MCP works a little differently on Core than it does on cloud. You can find the full list of differences here. The major differences to expect are:
Links include /api/public/v1. Links to Airbyte that the server returns point at the API path, so they error in your browser. Delete /api/public/v1 from the link to open the page.Billing tools fail. get_cloud_organization_billing_status only works in Airbyte Cloud.No context layer. Direct reads from sources and destinations and connector skills are Cloud-only.If /mcp doesn't show the server, run codex mcp get airbyte to check the entry, and run which uvx in your terminal. If Codex can't find uvx on its PATH, set command to the full path that which prints.
Codex is now connected to your Core deployment and can read and write to your Airbyte Core deployment.
Step 5: Build a connection using Airbyte MCP On top of troubleshooting pipelines, you can also now use Codex to create custom connectors, configure sources and destinations, and build pipelines. If you want to complete the connector configuration directly from Codex, add the source’s secret to your core.env file. For example, add a Postgres password with the following variable:
POSTGRES_PASSWORD =<password>Now ask Codex to build something:
Prompt
List the secret names available to you. Then deploy a Postgres source named
"orders-db" with host db.internal, port 5432 , database orders, username
airbyte_reader, and the password from secret_reference::POSTGRES_PASSWORD.
Never print or ask for the password value. Run a check on the source, then
create a connection to my existing warehouse destination with the orders and
customers streams selected, and start one sync.Codex calls list_dotenv_secrets, deploy_source_to_cloud, check_cloud_source, create_connection_on_cloud, and run_cloud_sync with approval gates at every write action. The password goes from your env file to your Airbyte API without passing through the conversation.
Be aware that the server guards against deletes. Tools that permanently delete sources, destinations, connections, or custom connector definitions only run when the resource's name contains delete-me or deleteme, which means you’ll need to rename a resource yourself in the UI to let Codex remove it.
If you want, you can remove the requirement that deletions have deleteme in their name. Seeing as we included this default, though, we don’t recommend removing it.
Takeaways Running the Airbyte MCP locally gives Codex most of the pipeline tools on Core that Cloud users get from the hosted server: inventory, job history, logs, deploys, connections, and syncs. Airbyte Core permissions don’t have the role-based restrictions that they do for Airbyte Cloud, though, so make sure your agent only has the ability to do exactly what it needs to.
To keep access as safe as possible, use the following guidelines:
Split monitoring from building. Register two entries, airbyte-ro with read-only mode for daily checks and airbyte with write access for pipeline work, and enable the second only when you need it.Share one config with your team. Pin the airbyte version in args, commit a config.toml snippet with a placeholder env file path, and have each person keep their own env file.Report what breaks. If you hit an issue that isn't in the known issues list, open an Airbyte MCP issue, and leave secrets out of it.For setup on Airbyte Cloud, see Install the Airbyte MCP.
