Airbyte now ships three MCP surfaces and a public REST API: a hosted MCP server for its data pipelines, the same server run locally for self-managed deployments, a separate Agent MCP for querying business apps, and the Airbyte API that replaced the deprecated Configuration API. They share a brand and a login and diverge on what they touch, which deployments they reach, and whose permissions they carry. This guide compares what each path lets an agent do, the credential each one puts you on, and how to run either across many customer organizations in production.
Your agent sits next to your customers' data stack. It needs to answer "why is the Stripe connection three days stale," re-run a failed sync before the morning dashboards load, spin up a Postgres-to-Snowflake connection for a new tenant, or pull the open Salesforce deals a sales rep asked about. Airbyte now ships a hosted MCP server for its data platform, a separate MCP server for its newer Airbyte Agents product, and a public REST API that has replaced the deprecated Configuration API. They share a brand and a login, and they diverge on what they touch, which deployments they reach, and whose permissions they carry. Here's how to pick.
The Airbyte MCP is a Model Context Protocol (MCP) server for Airbyte's replication platform, hosted at https://mcp.airbyte.com/mcp over Streamable HTTP. Airbyte labels it beta and "in active development." It works with all Airbyte Cloud editions and Airbyte Flex, it is free on every plan, and it acts with the signed-in user's Airbyte permissions (Airbyte MCP overview). Connecting Claude Code is one line: claude mcp add --transport http airbyte https://mcp.airbyte.com/mcp.
Its 46 tools cover organizations and workspaces (list_cloud_workspaces, get_default_cloud_context), connectors (deploy_connector_to_cloud, check_cloud_connector, update_cloud_connector_config), connections (create_connection_on_cloud, set_cloud_connection_selected_streams, update_cloud_connection), syncs (run_cloud_sync, cancel_cloud_sync, get_cloud_sync_status, get_cloud_sync_logs), custom connector manifests (publish_custom_source_definition), direct reads (execute_external_api_query, execute_external_sql_query), and docs search (search_airbyte_knowledge_sources).
For self-managed Airbyte Core, the hosted server does not apply. You run the same MCP locally over stdio with uvx --from=airbyte@latest airbyte-mcp, pointed at AIRBYTE_CLOUD_API_URL=http://localhost:8000/api/public/v1 with AIRBYTE_CLOUD_CLIENT_ID, AIRBYTE_CLOUD_CLIENT_SECRET, and AIRBYTE_CLOUD_WORKSPACE_ID. This is the PyAirbyte MCP server, which PyAirbyte marks experimental. Pipeline tools work there; the context layer and direct reads are Cloud only.
The Airbyte Agent MCP at https://mcp.airbyte.ai/mcp is a different product. It belongs to Airbyte Agents, announced on May 5, 2026, and connects agents to business systems through agent connectors and a managed Context Store. Its tools follow an inspect, read docs, execute pattern: inspect_connector, read_skill_docs, list_skills, search_skills, and an execute tool that queries or writes records. This is the server Scalekit's airbytemcp connector proxies.
The Airbyte API is REST at https://api.airbyte.com/v1/ for Cloud and <your-airbyte-url>/api/public/v1/ for self-managed. The reference groups it into Applications, Sources, Destinations, Connections, Jobs, Streams, Workspaces, Permissions, Users, Organizations, Tags, Health, and Source, Destination, and Declarative Source Definitions. Airbyte also publishes Python and Java SDKs and a Terraform provider. The old Configuration API is deprecated and unsupported.
Auth is one method. You create an application under User settings > Applications, then POST /v1/applications/token with client_id, client_secret, and grant-type: client_credentials (hyphenated in Airbyte's docs). The response is a Bearer access_token with expires_in: 900 (API access guide).
The pipeline MCP and the API manage the same objects. The API goes further on administration (users, permissions, tags, resets) and is the only path that a scheduler can drive with a stable contract. The pipeline MCP goes further on diagnosis: get_cloud_sync_logs and show_connection_sync_history give a model the context it needs to explain a failure. The Agent MCP sits in a different column entirely. It does not know your connections exist.
Airbyte's pipeline model is a chain of UUIDs: organization, workspace, source, destination, connection, job. "Why did the HubSpot sync fail last night" on the raw API means resolving the workspace, listing connections, matching the name, listing jobs, reading the failed one, and then going to the UI for logs. On the pipeline MCP, list_cloud_connections, list_cloud_sync_jobs, and get_cloud_sync_logs chain in one conversation, and check_cloud_connector tests the credential before the model suggests rotating it.
The Agent MCP does the same for business apps. A connector's entities and actions are documented as skills, and the model reads only the section it needs with read_skill_docs before it calls execute. Writing the schema is the hard part. Not the API call.
The tradeoff on both servers is that Airbyte owns the tool list. The pipeline MCP is beta, and Airbyte says features and tools may change.
For interactive clients, the pipeline MCP uses OAuth 2.0 sign-in through Airbyte Cloud, with single sign-on supported. The install guide says the client "registers itself automatically," so you only supply the server URL and leave client ID, secret, and endpoint fields blank. The resulting token carries the user's Airbyte role, so the agent sees only the workspaces, connectors, and connections that user can see. What the user can't do, the agent can't do.
Headless agents, scripts, and CI jobs send an application's credentials in Client-Id and Client-Secret headers on every request, and the server exchanges them for a fresh access token each time. Optional X-Airbyte-Workspace-Id or X-Airbyte-Organization-Id headers target a non-default workspace or organization. A raw Authorization: Bearer token also works, but it expires after 15 minutes.
Destructive tools are fenced. Each tool declares whether it is read-only or destructive, and permanent deletes of connectors, connections, and custom definitions only work when the resource name contains delete-me or deleteme.
The Agent MCP has its own OAuth login to your Airbyte Agents account, scoped to your account and organization. The third-party systems sit behind a second layer: the agent calls a credential flow tool, the user opens a URL, and enters the Salesforce or Zendesk credential in the browser, never in chat. Airbyte stores that credential server-side. Your system holds the Airbyte token; Airbyte holds the Salesforce token.
The direct path has no OAuth Authorization Code flow and no scopes. Airbyte's docs state that an access token "represents an individual Airbyte user, and it has the same permissions as that Airbyte user." An application created by a workspace admin gives your agent admin rights in that workspace, including deleting sources. There is no read-only application.
Three details break naive implementations:
In a multi-tenant B2B agent, MCP's OAuth flow gives you a token per user and the direct API gives you a credential per user or per customer. In neither case does the path itself solve storage, rotation, or revocation; those are infrastructure problems regardless of which path you choose.
Airbyte sharpens it. On the API path, the stored secret is long-lived, unscoped, and equal to a human's full role. A leaked client_secret for a customer's admin is a leaked admin.
Recommended reading: OAuth vs API keys for AI agents
Airbyte hosts the pipeline MCP, owns its 46 tool schemas, and maps them to the platform. You own the OAuth token per user if your product is the MCP client, or the application secret per customer if your agent runs headless with Client-Id headers. You also own the cost of reads: direct reads are capped at 100,000 per organization per month at no cost, and they count against the source system's own API rate limits. A sloppy agent can throttle a customer's Salesforce.
You also own what the server doesn't do. There is no subscription for sync events, so an agent that reacts to failures polls list_cloud_sync_jobs.
You own schemas, retries, the token cache, and the job state machine. POST /v1/jobs returns immediately; your agent polls GET /v1/jobs/{jobId} until status leaves pending or running and lands on succeeded, failed, incomplete, or cancelled. Airbyte's API docs do not publish a request rate limit, so budget polling intervals conservatively.
For events, Airbyte's workspace notifications post Failed sync and Successful sync payloads to any webhook, with connection, jobId, recordsCommitted, and on failure errorMessage, errorType, and errorOrigin. They are configured in workspace settings, and the docs say nothing about payload signing, so treat them as a trigger to call the API, not as a trusted record.
Self-managed deployments add their own lifecycle: your URL, your TLS, and /api/public/v1 instead of /v1.
The API is versioned in the path and the Configuration API is gone, so the public contract is what your scheduler should depend on. The pipeline MCP is beta and changes as Airbyte adds tools; the Agent MCP shipped in 2026 and its connector skills change as Airbyte adds entities and write actions. On the API path, a change is something you adopt when you choose. On the MCP path, the tool list your agent sees can change between runs.
Both paths hand you an Airbyte credential. Neither hands you a vault. A multi-tenant agent serving 60 customer organizations with 5 data engineers each holds 300 OAuth grants on the MCP path. On the API path it holds 60 application secrets, one per customer service account, each exchanged every 15 minutes and each carrying that account's full role. Every one must be stored encrypted, kept out of logs and LLM context, and deleted when a customer churns.
The Agent MCP adds a layer rather than removing one. The user's Salesforce credential lives in Airbyte, but the Airbyte token that reaches it lives with you. Lose control of that token and you have lost control of every system the user connected behind it.
The tempting shortcut is one application under your own admin account across customers. That turns tenant isolation into a filter your prompt has to remember, and a leaked secret into access to every customer's pipelines.
Scalekit's airbytemcp connector handles the Airbyte OAuth flow, stores each user's tokens in the token vault, and refreshes them, so the MCP vs API decision doesn't change your auth infrastructure. Your agent passes an identifier; credentials never touch the agent runtime or the LLM context.
Recommended reading: why a token vault matters for AI agent workflows
Scalekit's airbytemcp connector proxies Airbyte's own Agent MCP server. It exposes 20 tools: 13 read-only, 6 write, and 1 destructive (airbytemcp_delete_connector). The core set:
It authenticates with OAuth 2.1, and Scalekit-managed OAuth credentials are available, so you do not register your own OAuth app.
Create an Airbyte MCP connection in AgentKit > Connections in the Scalekit dashboard. The name you give it is the connection_name your code passes, and the string must match the dashboard exactly. This is the most common integration error. Copy SCALEKIT_ENVIRONMENT_URL, SCALEKIT_CLIENT_ID, and SCALEKIT_CLIENT_SECRET from Developers > API Credentials into .env.
get_or_create_connected_account returns the user's connected account. If it is not ACTIVE, get_authorization_link returns the Airbyte OAuth link the user opens once. Then airbytemcp_check_enrollment_status confirms the Airbyte Agents account is provisioned.
This is not a catalog load. The agent asks for the tools this user's connected account is authorized to call, then narrows them to the five a read-and-report agent needs. airbytemcp_delete_connector and airbytemcp_start_credential_flow never reach the model, so it cannot remove a user's Salesforce connection or start connecting new systems while answering a question.
The loop runs until the model stops requesting tools. Every call executes with this user's Airbyte token and sees only the connectors this user created.
For pipelines, skip the model. execute_tool runs one tool with a fixed input and returns data plus an execution_id you can log. This job lists the user's connectors, then fetches the skill docs for one of them so your code can build airbytemcp_execute items against the documented entity and action.
Onboarding a new system is two calls. airbytemcp_start_credential_flow takes a template_id from airbytemcp_list_available_connectors and returns a URL the user opens; airbytemcp_check_credential_flow_status takes the returned session_id and, once the user finishes, creates the connector and returns its connector_id. The Salesforce credential never passes through your code or the model.
Scalekit does not ship a prebuilt connector for the Airbyte platform API or for mcp.airbyte.com. Scalekit custom connectors support OAUTH, BASIC, BEARER, and API_KEY auth, but not the client credentials exchange the Airbyte API requires, so on the pipeline path the application secret and the 15-minute token loop stay in your code. Keep it small and server-side:
Create the application under a service account with the narrowest workspace role that can run syncs, one per customer organization.
A data-ops assistant rarely stops at one system. It reads the user's CRM through Airbyte, then posts a summary where the team works. Load all 20 airbytemcp tools and the model holds airbytemcp_delete_connector, organization switching, and credential flows while answering a reporting question. A Scalekit virtual MCP server declares exactly which tools an agent role can see across connections, and session tokens keep each run bound to one user's connected accounts. Docs: set up a virtual MCP server.
One server definition serves every user. Before each run, check that the user's accounts are active and mint a short-lived session token scoped to them. Any MCP client that speaks Streamable HTTP can connect; this example uses langchain-mcp-adapters (pip install langchain-mcp-adapters) and passes the token as a Bearer header.
The agent sees six tools instead of 20 plus everything Slack exposes. The endpoint is static; the identity is per-user.
Every execute_tool call returns an execution_id, and every execution is attributed to a connected account, which maps to one of your users and one customer. When a customer asks which agent run wrote to a HubSpot record through airbytemcp_execute, the answer is a lookup, not an investigation.
The API path is weaker by construction. A token from an application "represents an individual Airbyte user," so every sync your orchestrator triggers is recorded in Airbyte as that user. If one service account's application drives every agent, Airbyte attributes every job to it, and your side has to reconstruct which agent run, which prompt, and which customer request led there. Shared credentials are a single-user solution. They do not survive a second user.
Recommended reading: audit trails for agent auth
If your agent is a data engineer's assistant inside Claude Code or Cursor, diagnosing failed syncs, reading logs, and testing connector configs with a human watching, use the Airbyte MCP at mcp.airbyte.com: it is hosted, free, and its troubleshooting tools do real work, with the caveat that it is beta. If your agent answers questions from business apps for your product's users, the Agent MCP is the right surface, and Scalekit's airbytemcp connector gives it per-user OAuth without an app registration. If your agent triggers syncs on a schedule, provisions pipelines per tenant, resets connections, or runs against self-managed Core, build against the Airbyte API. Either way, you hold one Airbyte credential per user or per customer, each worth a full Airbyte role, and that's what needs production-grade infrastructure.
The Airbyte MCP at mcp.airbyte.com manages data pipelines in Airbyte Cloud: connectors, connections, syncs, logs, and custom connector manifests, with 46 tools in open beta. The Airbyte Agent MCP at mcp.airbyte.ai belongs to Airbyte Agents, launched in May 2026, and queries business apps such as Salesforce and Zendesk through agent connectors and a managed Context Store. It does not know your pipelines exist.
The hosted server applies to Airbyte Cloud and Flex only. For self-managed Airbyte Core you run the same MCP locally over stdio with uvx, pointed at your instance's public API URL with an application's client ID, client secret, and workspace ID. Pipeline tools work there; the context layer and direct reads are Cloud only, and PyAirbyte marks the local server experimental.
There is one method. You create an application under User settings, then exchange its client_id and client_secret at /v1/applications/token for a Bearer token that expires after 15 minutes with no refresh token. The body field is grant-type, hyphenated. The token carries every permission of the user who created the application, with no scopes, and the application stops working when that user leaves, which is why Airbyte recommends creating it under a service account.
Workspace notifications can post Failed sync and Successful sync payloads to any webhook URL, carrying the connection, job ID, records committed, and on failure the error message, type, and origin. They are configured in workspace settings and the docs say nothing about payload signing, so treat them as a trigger to call the API rather than a trusted record. Neither MCP server offers a subscription.
When an orchestrator triggers syncs after upstream jobs and blocks downstream models until the job reports succeeded, when pipelines are provisioned per customer as a deterministic flow, when the agent resets connections or manages users, permissions, and tags, or when it runs against self-managed Core and needs a stable contract rather than a beta, stdio-only local MCP.
The airbytemcp connector proxies Airbyte's Agent MCP with 20 tools and OAuth 2.1, and Scalekit-managed OAuth credentials mean no app registration. Each user signs in once, Scalekit stores and refreshes the tokens in the token vault, a virtual MCP server narrows the tools per agent role, and every execution returns an execution_id. The pipeline API's client credentials exchange is not a supported custom connector auth type, so that loop stays in your own server-side code.
Browse the Scalekit Airbyte MCP connector and the Airbyte MCP connector docs with the full tool list. See Scalekit pricing, or talk to us.
