feat(mcp): add `ALLOW_EXTERNAL_ACCESS` and `ALLOW_PIPELINE_CHANGES` policies for Cloud MCP by aaronsteers · Pull Request #1179 · airbytehq/PyAirbyte

Aaron ("AJ") Steers (aaronsteers) · 2026-09-17T20:58:49Z

Overview

👉 TL;DR: Adds two independent on/off switches to the Cloud MCP server: one for whether an agent may reach through Airbyte into a customer's connected SaaS or warehouse, and one for whether it may change Airbyte pipelines. An explicitly declared safe mode also turns off external access as a stopgap, so locked-down deployments gain no new exposure; the unset default does not affect external access. Specifically, this adds `AIRBYTE_CLOUD_MCP_ALLOW_EXTERNAL_ACCESS` (`X-MCP-Allow-External-Access`) and `AIRBYTE_CLOUD_MCP_ALLOW_PIPELINE_CHANGES` (`X-MCP-Allow-Pipeline-Changes`), driven by new `@mcp_tool(pipeline_change=..., external_access=...)` kwargs and enforced by tool filters plus `PolicyGuardMiddleware`. Rebuilt on `release-candidate/v1`.

Changes

New @mcp_tool kwargs pipeline_change: bool | None = None (default not read_only) and external_access: bool = False, stored in an in-process _TOOL_POLICIES registry keyed by tool name (fastmcp-extensions 0.33 rejects custom annotation keys, so they stay off the wire). Unregistered tools fall back to pipeline_change = not readOnlyHint.
airbyte_readonly_mode_filter now hides pipeline_change tools when pipeline changes are disabled; new airbyte_external_access_filter hides external_access tools when external access is disabled.
New PolicyGuardMiddleware rejects the same calls at runtime with AirbytePipelineChangesDisabledError / AirbyteExternalAccessDisabledError (user-facing, with guidance). AirbyteSafeModeError is now user-facing too.
external_access=True on execute_external_api_query, execute_external_sql_query, execute_external_search_query, get_cloud_search_status, get_agent_skill_docs (examples; tool names will change).
pipeline_change=False on run_cloud_sync and cancel_cloud_sync: running or cancelling a sync is not a pipeline edit.
Docs in airbyte/mcp/__init__.py; unit tests for filters, middleware (incl. an in-memory client call), and decorator defaults.

Review Spotlight

Reviewers with limited time, please review first:

_tool_utils.py policy resolution: _resolve_policy, pipeline_changes_allowed, external_access_allowed, get_tool_policy
_policy_middleware.py: call-time enforcement

Feature flags: `ALLOW_EXTERNAL_ACCESS`, `ALLOW_PIPELINE_CHANGES` (default unset)

values: 1|true|yes -> allow, 0|false|no -> deny, unset/other (e.g. auto) -> calculated default
env False wins; env True can be narrowed by header False; env unset -> header decides

pipeline_changes_allowed(): AIRBYTE_CLOUD_MCP_READONLY_MODE truthy -> False, else resolved value
external_access_allowed():  resolved value if set,
                            else False if pipeline changes are False or AIRBYTE_CLOUD_MCP_SAFE_MODE is explicitly truthy,
                            else None (allowed)

Risks

Behavior change: legacy AIRBYTE_CLOUD_MCP_READONLY_MODE=1 now leaves run_cloud_sync / cancel_cloud_sync available.
Deployments that set AIRBYTE_CLOUD_MCP_SAFE_MODE=1 explicitly (e.g. coral-agents) lose external-access tools unless they also set AIRBYTE_CLOUD_MCP_ALLOW_EXTERNAL_ACCESS=1.

Follow-ups

Module/tool renames deferred until tool consolidation.
External-writes and external read-only tiers not implemented.
Possible safe-mode DeprecationWarning (not in this PR).

Test plan

uv run ruff format . && uv run ruff check .
uv run pyrefly check airbyte/mcp
uv run pytest tests/unit_tests/test_mcp_policy_middleware.py tests/unit_tests/test_mcp_tool_filters.py tests/unit_tests/test_mcp_tool_utils.py tests/unit_tests/test_mcp_cloud.py tests/unit_tests/test_mcp_guidance.py tests/unit_tests/test_mcp_tool_errors.py tests/unit_tests/test_exceptions.py -q

Link to Devin session: https://app.devin.ai/sessions/48a4f92f26b9488b802f9eef9c49b608
Open in Devin Desktop: https://app.devin.ai/desktop/session/48a4f92f26b9488b802f9eef9c49b608?variant=devin
Requested by: Aaron ("AJ") Steers (@aaronsteers)

devin-ai-integration · 2026-09-17T20:58:52Z

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

Disable automatic comment, CI, and merge conflict monitoring

github-actions · 2026-09-17T20:59:13Z

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

💡 Show Tips and Tricks

Testing This PyAirbyte Version

You can test this version of PyAirbyte using the following:

# Run PyAirbyte CLI from this branch:
uvx --from 'git+https://github.com/airbytehq/PyAirbyte.git@devin/1789678460-safe-mode-blocks-agents' pyairbyte --help

# Install PyAirbyte from this branch for development:
pip install 'git+https://github.com/airbytehq/PyAirbyte.git@devin/1789678460-safe-mode-blocks-agents'

PR Slash Commands

Airbyte Maintainers can execute the following slash commands on your PR:

/fix-pr - Fixes most formatting and linting issues
/uv-lock - Updates uv.lock file
/test-pr - Runs tests with the updated PyAirbyte
/prerelease - Builds and publishes a prerelease version to PyPI

📚 Show Repo Guidance

Helpful Resources

Community Support

Questions? Join the #pyairbyte channel in our Slack workspace.

📝 Edit this welcome message.

github-code-quality · 2026-09-17T21:06:19Z

Code Coverage Overview

Languages: Python

Python / code-coverage/pytest-no-creds

The overall line coverage in commit 0b9eb06 in the devin/1789678460-saf... branch is 78%. The line coverage in commit d9f652f in the release-candidate/v1 branch is 65%.

Show a line coverage summary of the most impacted files.

File	`release-candidate/v1` d9f652f	`devin/1789678460-saf...` 0b9eb06	+/-
`airbyte/_util/api_util.py`	36%	62%	+26%
`airbyte/mcp/cloud.py`	52%	80%	+28%
`airbyte/cloud/connectors.py`	34%	75%	+41%
`airbyte/mcp/_otel.py`	0%	91%	+91%
`airbyte/mcp/_user_identity.py`	0%	93%	+93%
`airbyte/_direct...ctors/models.py`	0%	94%	+94%
`airbyte/mcp/_telemetry.py`	0%	95%	+95%
`airbyte/mcp/_sso_auth.py`	0%	96%	+96%
`airbyte/cloud/models.py`	0%	97%	+97%
`airbyte/mcp/int...nc_status_ui.py`	0%	97%	+97%

Python / code-coverage/pytest

The overall line coverage in commit 0b9eb06 in the devin/1789678460-saf... branch is 81%. The line coverage in commit d9f652f in the release-candidate/v1 branch is 71%.

Show a line coverage summary of the most impacted files.

File	`release-candidate/v1` d9f652f	`devin/1789678460-saf...` 0b9eb06	+/-
`airbyte/mcp/cloud.py`	52%	80%	+28%
`airbyte/cloud/connectors.py`	51%	80%	+29%
`airbyte/mcp/_otel.py`	0%	91%	+91%
`airbyte/mcp/int..._registry_ui.py`	0%	92%	+92%
`airbyte/mcp/_user_identity.py`	0%	93%	+93%
`airbyte/_direct...ctors/models.py`	0%	94%	+94%
`airbyte/mcp/_telemetry.py`	0%	95%	+95%
`airbyte/mcp/_sso_auth.py`	0%	96%	+96%
`airbyte/cloud/models.py`	0%	97%	+97%
`airbyte/mcp/int...nc_status_ui.py`	0%	97%	+97%

Python / code-coverage/pytest-unit

The overall line coverage in commit 0b9eb06 in the devin/1789678460-saf... branch is 75%. Line coverage data for the release-candidate/v1 branch is not yet available.

Show a line coverage summary of the most covered files.

File	`release-candidate/v1`	`devin/1789678460-saf...` 0b9eb06	+/-
`airbyte/cloud/models.py`	—	97%	—
`airbyte/mcp/_sso_auth.py`	—	96%	—
`airbyte/_direct...ctors/models.py`	—	94%	—
`airbyte/mcp/_otel.py`	—	91%	—
`airbyte/cloud/client.py`	—	90%	—
`airbyte/mcp/cloud.py`	—	80%	—
`airbyte/progress.py`	—	80%	—
`airbyte/cloud/connectors.py`	—	75%	—
`airbyte/shared/...ql_processor.py`	—	68%	—
`airbyte/_util/api_util.py`	—	62%	—

_{Updated October 05, 2026 01:31 UTC}

Aaron ("AJ") Steers (aaronsteers) · 2026-09-18T07:22:21Z

Devin, resolve conflicts please

devin-ai-integration · 2026-09-18T07:22:53Z

✅ Done. Merged main in 0b2caf7. The only conflict was in airbyte/mcp/agents.py: main removed search_agent_skills (airbytehq/PyAirbyte#1185), so I dropped it and its entry in the policy-guard parametrized test; the external_access=True annotation stays on the remaining Agents tools. Local ruff/pyrefly and the MCP unit tests (207) pass; CI is rerunning.

Written by Devin

devin-ai-integration

🔍 Devin Review: 2 flags

Not posted on this PR by your GitHub settings — view them in Devin Review. (Configure)

Aaron ("AJ") Steers (aaronsteers) · 2026-10-05T00:54:41Z

Devin, rebuild on the release candidate trunk.

devin-ai-integration · 2026-10-05T00:55:12Z

👍 On it. Rebuilding this branch on release-candidate/v1 and retargeting the PR there. Same behavior; I'll adapt to RC's tool/module layout where it differs from main.

Written by Devin

…ies for Cloud MCP Co-Authored-By: AJ Steers <aj@airbyte.io>

Co-Authored-By: AJ Steers <aj@airbyte.io>

devin-ai-integration · 2026-10-05T01:10:57Z

Devin, rebuild on the release candidate trunk.

Done. Rebuilt on release-candidate/v1 (62ca2c5, bcd86d0) and the PR now targets it. The behavior hasn't changed. Two things changed to fit RC:

The former Agents tools now live in cloud.py/guidance.py. external_access=True is set on execute_external_api_query, execute_external_sql_query, execute_external_search_query, get_cloud_search_status and get_agent_skill_docs.
fastmcp-extensions 0.33 rejects custom annotation keys. The pipeline_change/external_access metadata is now stored in a PyAirbyte-side registry keyed by tool name, so it is no longer sent with the tool's annotations.

Description updated. CI is running.

Written by Devin

Co-Authored-By: AJ Steers <aj@airbyte.io>

Copilot

Copilot review overview

🟡 Changes recommended

check_cloud_connector and run_cloud_sync need correct external-access policy annotations, and external-access denial guidance should cover header narrowing.

Review effort: Lite
Findings: 1 · 1

Open (2)

Add explicit policy for check_cloud_connector external access · New
Document request-header override for external-access denial · New

Resolved since last review (1)

This guidance is not sufficient when the denial comes from the supported legacy…

Co-Authored-By: AJ Steers <aj@airbyte.io>

devin-ai-integration Bot assigned Aaron ("AJ") Steers (aaronsteers) Sep 17, 2026

Airbyte Support Bot (airbyte-support-bot) requested a lite review from Copilot September 17, 2026 20:59

Copilot started reviewing on behalf of Airbyte Support Bot (airbyte-support-bot) September 17, 2026 20:59

View session

devin-ai-integration Bot changed the title ~~feat(mcp): block agents tools in cloud safe mode~~ feat(mcp): block agents tools in Cloud safe mode Sep 17, 2026

This comment was marked as resolved.

Sign in to view

devin-ai-integration Bot changed the title ~~feat(mcp): block agents tools in Cloud safe mode~~ feat(mcp): add ALLOW_EXTERNAL_ACCESS and ALLOW_PIPELINE_CHANGES policies for Cloud MCP Sep 17, 2026

Airbyte Support Bot (airbyte-support-bot) requested a lite review from Copilot September 17, 2026 22:14

Copilot started reviewing on behalf of Airbyte Support Bot (airbyte-support-bot) September 17, 2026 22:14

View session

This comment was marked as resolved.

Sign in to view

Aaron ("AJ") Steers (aaronsteers) commented Sep 17, 2026

View reviewed changes

Comment thread airbyte/mcp/__init__.py Outdated

Aaron ("AJ") Steers (aaronsteers) marked this pull request as ready for review September 18, 2026 07:22

devin-ai-integration Bot reviewed Sep 18, 2026

View reviewed changes

feat(mcp): add ALLOW_EXTERNAL_ACCESS and ALLOW_PIPELINE_CHANGES polic…

62ca2c5

…ies for Cloud MCP Co-Authored-By: AJ Steers <aj@airbyte.io>

devin-ai-integration Bot force-pushed the devin/1789678460-safe-mode-blocks-agents branch from 0b2caf7 to 62ca2c5 Compare October 5, 2026 01:08

fix(mcp): keep existing insiders module gate

bcd86d0

Co-Authored-By: AJ Steers <aj@airbyte.io>

devin-ai-integration Bot changed the base branch from main to release-candidate/v1 October 5, 2026 01:09

Airbyte Support Bot (airbyte-support-bot) requested a lite review from Copilot October 5, 2026 01:10

Copilot started reviewing on behalf of Airbyte Support Bot (airbyte-support-bot) October 5, 2026 01:10

View session

fix(mcp): align policy guidance types with base exception

99db821

Co-Authored-By: AJ Steers <aj@airbyte.io>

Copilot AI reviewed Oct 5, 2026

View reviewed changes

Comment thread airbyte/mcp/_tool_utils.py

Comment thread airbyte/exceptions.py Outdated

fix(mcp): mention external access header in guidance

0b9eb06

Co-Authored-By: AJ Steers <aj@airbyte.io>

Aaron ("AJ") Steers (aaronsteers) merged commit e0ad6f5 into release-candidate/v1 Oct 5, 2026
22 checks passed

Aaron ("AJ") Steers (aaronsteers) deleted the devin/1789678460-safe-mode-blocks-agents branch October 5, 2026 01:51

Conversation

Aaron ("AJ") Steers (aaronsteers) commented Sep 17, 2026 • edited by devin-ai-integration Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Changes

Review Spotlight

Feature flags: ALLOW_EXTERNAL_ACCESS, ALLOW_PIPELINE_CHANGES (default unset)

Risks

Follow-ups

Test plan

Uh oh!

devin-ai-integration Bot commented Sep 17, 2026

🤖 Devin AI Engineer

Uh oh!

github-actions Bot commented Sep 17, 2026

👋 Greetings, Airbyte Team Member!

Testing This PyAirbyte Version

PR Slash Commands

Helpful Resources

Community Support

Uh oh!

This comment was marked as resolved.

Uh oh!

github-code-quality Bot commented Sep 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Coverage Overview

Python / code-coverage/pytest-no-creds

Python / code-coverage/pytest

Python / code-coverage/pytest-unit

Uh oh!

This comment was marked as resolved.

Uh oh!

Uh oh!

Aaron ("AJ") Steers (aaronsteers) commented Sep 18, 2026

Uh oh!

devin-ai-integration Bot commented Sep 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

devin-ai-integration Bot left a comment

Choose a reason for hiding this comment

🔍 Devin Review: 2 flags

Uh oh!

Aaron ("AJ") Steers (aaronsteers) commented Oct 5, 2026

Uh oh!

devin-ai-integration Bot commented Oct 5, 2026

Uh oh!

devin-ai-integration Bot commented Oct 5, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Aaron ("AJ") Steers (aaronsteers) commented Sep 17, 2026 •

edited by devin-ai-integration Bot

Loading

Feature flags: `ALLOW_EXTERNAL_ACCESS`, `ALLOW_PIPELINE_CHANGES` (default unset)

github-code-quality Bot commented Sep 17, 2026 •

edited

Loading

devin-ai-integration Bot commented Sep 18, 2026 •

edited

Loading