Skip to main content

Agent MCP

AvailableFreeAvailableIndividualAvailableTeamAvailableCustom Compare plans

The Agent MCP connects your AI agent to your data through the Model Context Protocol (MCP). It gives your agent authenticated access to the platforms you use every day, like your CRM, support desk, analytics tools, and more, so your agent can read and write data on your behalf. See Connectors for a list of available connectors.

Airbyte hosts and manages this remote MCP server, so there's nothing to install.

Requirements​

Before you begin, make sure you have the following:

  • An Airbyte Agents account. Sign up at app.airbyte.ai if you don't have one.

  • An AI agent that supports MCP. For example, Claude Desktop, Claude Code, Cursor, Codex, or ChatGPT.

  • Credentials for the connectors you want to use. Each service requires its own authentication. For example, you need a Linear API key to connect Linear, or Salesforce OAuth credentials to connect Salesforce.

Add the Agent MCP to your agent​

Select your client below for setup instructions. Each client requires you to authenticate with your Airbyte account before you can use the MCP server.

Claude Desktop uses Custom Connectors for remote MCP servers. Don't use the claude_desktop_config.json file, as it only supports local servers.

  1. Open Claude Desktop and go to Settings > Connectors.

  2. Click Add custom connector.

  3. Enter the server name and URL: https://mcp.airbyte.ai/mcp

  4. Click Add.

  5. Find the Airbyte connector in the list and click Connect. Your browser opens.

  6. If you're not logged into Airbyte, log in now.

  7. Grant access to the Agent MCP.

  8. Return to Claude Desktop. The MCP server is automatically enabled. If it isn't, in your chat, click + > Connectors > Airbyte to turn it on.

Example usage​

After you connect the MCP server, your agent can discover and call its tools automatically based on your prompts. The following examples show common actions.

Add a connector​

To connect a new data source, prompt your agent with the service you want to connect. The MCP can use any Airbyte agent connector. The agent handles the setup, including starting a browser-based credential flow where you enter your credentials securely.

Connect my Linear account

The agent:

  1. Starts a credential flow and gives you a URL to visit.
  2. You visit the URL and enter your credentials in the browser.
  3. The agent confirms the connector was created and is ready to query.
note

Credentials are always entered in the browser, never in the chat.

Remove a connector​

To remove a connector you no longer need:

Delete my Linear connector

Query data​

After you connect a data source, prompt your agent. The agent discovers the available entities, understands their schemas, and executes the right queries.

Show me the 10 most recent Gong calls
Find all open deals in Salesforce worth more than $50,000
List HubSpot contacts who were created this week
How many Zendesk tickets are in "open" status?

The agent uses field selection to return only the data you need, which reduces token usage and improves response quality.

How authentication works​

The Agent MCP uses a two-layer authentication model: one layer to authenticate you with the Airbyte Agents, and a second layer to authenticate with each third-party service you connect.

Layer 1: Authenticating with the MCP server​

When your AI client first connects to the MCP server, it initiates an OAuth 2.0 authorization flow with Airbyte:

  1. Your client detects that the MCP server at https://mcp.airbyte.ai/mcp requires authentication.
  2. Your client opens a browser window to the Airbyte login page.
  3. You log in with your Airbyte account (or create one).
  4. You grant the MCP server access to your Airbyte account.
  5. The browser redirects back to your client with an OAuth token.
  6. Your client stores the token and uses it for all subsequent MCP requests.

This token authorizes the MCP server to act on your behalf within the Airbyte Agents. The token is scoped to your Airbyte account and organization, so the MCP server can only access connectors and data that belong to you. If the token expires, your client automatically triggers a new OAuth flow.

Layer 2: Authenticating with third-party services​

After you authenticate with the MCP server, you still need to connect each third-party service individually. When you ask your agent to connect a service (for example, "Connect my Salesforce account"), a second credential flow begins:

  1. The agent calls the MCP server to initiate a credential flow for the requested service.
  2. The MCP server returns a secure URL for you to visit in your browser.
  3. You open the URL and authenticate directly with the third-party service. Depending on the connector, this is either:
    • An OAuth consent screen where you authorize Airbyte to access your account (used by services like Salesforce, HubSpot, GitHub, Google, and Slack), or
    • A credential form where you enter an API key or access token (used by services like Stripe, Gong, and Linear).
  4. After you complete the flow, Airbyte securely stores your credentials and creates a connector.
  5. The agent confirms the connector is ready and you can begin querying data.
note

Your third-party credentials are always entered in the browser, never in the agent chat. Airbyte stores credentials securely on the server side and the MCP server never exposes them to the AI agent.

Once a connector is created, the agent uses it for all subsequent queries to that service. You don't need to re-authenticate unless your credentials expire or are revoked by the third-party service.

What connectors do​

Each connector is a type-safe integration that gives your AI agent direct access to a third-party platform's API. Connectors let your agent list, search, retrieve, and in some cases create or update records in the connected service. Every connector exposes a set of entities (such as contacts, deals, issues, or invoices) and actions (such as list, get, search, create, or update) that the agent can call.

For example:

  • A CRM connector like Salesforce or HubSpot lets your agent query contacts, companies, deals, and tickets.
  • A billing connector like Stripe lets your agent look up customers, invoices, charges, and subscriptions.
  • A communication connector like Slack lets your agent read channel messages and threads, and send or update messages.
  • A revenue intelligence connector like Gong lets your agent retrieve call recordings, transcripts, and activity statistics.
  • A project management connector like Jira or Linear lets your agent search issues, projects, and comments.

Connectors handle authentication, pagination, schema validation, and error handling so the agent can focus on answering questions and performing tasks. The agent automatically discovers which entities and actions are available for each connector you've added, so you only need to describe what you want in natural language.

When you connect a service through the MCP server, the Airbyte Agents can copy key data from that connector into a Context Store. The Context Store is a managed, searchable replica of select entities from all your connected data sources. This improves search speed and reduces token consumption compared to querying third-party APIs directly, especially for prompts that involve filtering or searching large datasets.

For the complete list of connectors and their supported entities, see Agent connectors.

Troubleshooting​

MCP server authentication fails​

  • Make sure you have an active account at app.airbyte.ai.
  • Try logging out of your agent's MCP integration and reconnecting to trigger a fresh OAuth flow.
  • If you joined a new Airbyte organization, authenticate again to refresh your access.
  • If your client reports a token error, remove and re-add the MCP server to clear stored tokens.

Agent can't find the MCP server​

  • Restart your agent after adding the MCP server configuration.
  • Verify the server URL is exactly https://mcp.airbyte.ai/mcp in your configuration.
  • Check that your client supports Streamable HTTP or OAuth-based MCP servers.

Connector credential flow doesn't complete​

  • Make sure you visited the credential URL the agent provided and completed the form in the browser.
  • If the flow timed out, ask the agent to start a new credential flow.

ChatGPT connection fails​

  • If Connect is off, check whether your plan, geographic restrictions, or workspace settings limit access.
  • On Enterprise and Education plans, ask a workspace owner or administrator to enable Airbyte Agent Engine from Workspace settings > Apps.
  • If the OAuth flow doesn't complete, try deleting Airbyte Agent Engine in Settings > Apps and connecting it again.

ChatGPT doesn't use MCP server tools​

ChatGPT may not realize it has access to data through the MCP server. If ChatGPT ignores the MCP or tries to answer without using your connected data, instruct it directly. For example: "Use Airbyte Agent Engine to discover tools that can help work with the Salesforce connector."

Queries return unexpected results​

  • Ask the agent to describe the available entities before querying, so it picks the right one.
  • For time-based queries, the agent resolves relative dates like "this week" or "last month" automatically. The MCP server returns timestamps in UTC; see Time zones for how this interacts with your local time.
Was this page helpful?