# Advanced Airbyte MCP configuration

Copy Page

CoreStandardPlusProEnterprise Flex[ Compare](https://airbyte.com/pricing)

The hosted [Airbyte MCP](/platform/airbyte-mcp.md) works without any extra configuration. These optional request headers let you narrow which tools your agent can see and use, or set a default workspace. They apply to the hosted server at `https://mcp.airbyte.com/mcp`. If your client can't send custom headers, like Claude, you can turn on read-only mode with a [URL parameter](#url-parameters) instead.

Your MCP client still controls tool approval. Most clients can require your approval before tools that change data, using each tool's read-only, destructive, and open-world annotations.

## Add headers to your client[​](#add-headers-to-your-client "Direct link to Add headers to your client")

Add headers to your client's MCP configuration. Configuration syntax can vary by client, so check your client's documentation for the required JSON syntax.

```
{

  "mcpServers": {

    "airbyte": {

      "url": "https://mcp.airbyte.com/mcp",

      "headers": {

        "X-MCP-Allow-External-Access": "0",

        "X-MCP-Allow-Destructive-Tools": "0"

      }

    }

  }

}
```

Headers can only hide tools and customize tool behaviors. They can't give your agent permissions your Airbyte role doesn't have.

## URL parameters[​](#url-parameters "Direct link to URL parameters")

Some clients, like Claude, can't send custom headers. To use read-only mode with these clients, add the `read-only` parameter to the server URL:

```
https://mcp.airbyte.com/mcp?read-only=true
```

* `read-only` works like the `X-MCP-Readonly-Mode` header and accepts `true`, `false`, `1`, or `0`, in any case. If you set both, the header takes precedence.
* The Airbyte MCP rejects the request with an error if the value isn't one of these, or if the name is a common misspelling, like `readonly` or `read_only`. An empty value, like `?read-only=`, is ignored and leaves read-only mode off.
* The Airbyte MCP ignores other URL parameters. All other settings on this page are only available as headers.

## Tool restrictions[​](#tool-restrictions "Direct link to Tool restrictions")

| Header                          | Allowed values                | Effect                                                                                                                                                                       |
| ------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-MCP-Allow-Pipeline-Changes`  | `1` (enabled), `0` (disabled) | Enabled by default. When set to `0`, hides tools that create, update, rename, or delete sources, destinations, and connections. Running and cancelling syncs stay available. |
| `X-MCP-Allow-External-Access`   | `1` (enabled), `0` (disabled) | Enabled by default. When set to `0`, hides tools that read data directly from sources and destinations, like SQL and API passthrough queries.                                |
| `X-MCP-Readonly-Mode`           | `1` (enabled), `0` (disabled) | Disabled by default. When set to `1`, shows only read-only tools. In addition to restricting pipeline edits, this setting also hides tools for running and cancelling syncs. |
| `X-MCP-Allow-Destructive-Tools` | `1` (enabled), `0` (disabled) | Enabled by default. When set to `0`, hides destructive tools, like deleting a source, destination, or connection.                                                            |
| `X-MCP-Exclude-Tools`           | Comma-separated tool names    | When set, hides the named tools. For tool names, see [Airbyte MCP tools](/platform/airbyte-mcp/tools.md).                                                                    |
| `X-MCP-Include-Modules`         | Comma-separated modules       | When set, shows only tools from these modules: `cloud`, `registry`, `guidance`, `interactive`. Can't be combined with `X-MCP-Exclude-Modules`.                               |
| `X-MCP-Exclude-Modules`         | Comma-separated modules       | When set, hides tools from these modules. Can't be combined with `X-MCP-Include-Modules`.                                                                                    |

`X-MCP-Allow-Pipeline-Changes`, `X-MCP-Allow-External-Access`, and `X-MCP-Allow-Destructive-Tools` also accept `true` or `yes` for `1`, and `false` or `no` for `0`. `X-MCP-Readonly-Mode` also accepts `true` for `1`.

## Delete guard[​](#delete-guard "Direct link to Delete guard")

By default, the delete tools only delete a source, destination, or connection whose name contains `delete-me` or `deleteme` (case insensitive). Your agent can rename a resource to add the marker, but only after you explicitly agree to the rename.

| Header                       | Allowed values                  | Effect                                                                                         |
| ---------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------- |
| `X-MCP-Disable-Delete-Guard` | `1` (guard off), `0` (guard on) | The guard is on by default. Set to `1` to let the delete tools delete without the name marker. |

`1` can also be written as `true` or `yes`, and `0` as `false` or `no`. To block deletions entirely, which is the stronger option, set `X-MCP-Allow-Destructive-Tools` to `0` instead.

## Default workspace and organization[​](#default-workspace-and-organization "Direct link to Default workspace and organization")

| Header                      | Value           | Effect                                                                             |
| --------------------------- | --------------- | ---------------------------------------------------------------------------------- |
| `X-Airbyte-Workspace-Id`    | Workspace ID    | Workspace to use when your agent doesn't name one.                                 |
| `X-Airbyte-Organization-Id` | Organization ID | Organization to use for organization-level tools when your agent doesn't name one. |

## Application name[​](#application-name "Direct link to Application name")

| Header                       | Value                                 | Effect                                                     |
| ---------------------------- | ------------------------------------- | ---------------------------------------------------------- |
| `X-Airbyte-Application-Name` | Your app's name, like `support-agent` | Identifies your agent or app in Airbyte's usage telemetry. |

## See also[​](#see-also "Direct link to See also")

* [Connect the Airbyte MCP to your agent](/platform/airbyte-mcp/install.md)
* [Airbyte MCP tools](/platform/airbyte-mcp/tools.md)