feat(mcp): gate Agents tools behind insiders mode, add org-id header by aaronsteers · Pull Request #1135 · airbytehq/PyAirbyte

Aaron ("AJ") Steers (aaronsteers) · 2026-08-28T21:19:14Z

Summary

The Agents MCP tools added in #1127 are advertised to every caller today, but most organizations have no Airbyte Agents subscription, so those tools cost context and produce authorization failures nobody can act on. This hides them by default and makes the failures readable when they do happen.

Three changes:

1. Insiders gate on the agents module. MCP_INSIDERS_MODULES = {"agents"} marks modules that are not part of the default surface. airbyte_module_filter gains one branch, ordered so an explicit exclusion still wins:

if exclude_modules and tool_module in exclude_modules:
    return False
if tool_module in MCP_INSIDERS_MODULES and not _insiders_enabled(app):
    return tool_module in include_modules   # naming the module is itself an opt-in
if include_modules:
    return tool_module in include_modules
return True

So Agents tools appear when AIRBYTE_MCP_INSIDERS / X-MCP-Insiders is set (they join the normal surface), or when the include list names agents (AIRBYTE_MCP_DOMAINS=agents still yields Agent-only mode, unchanged). Names follow the GitHub MCP server's configuration surface, which is the closest thing to a convention here — MCP itself has no annotation or header for preview/subscription-gated tools, and tool annotations are client hints, so the filtering has to be server-side regardless.

This is a caller-settable gate that widens the tool surface, unlike AIRBYTE_MCP_TRUSTED_EXECUTION which deliberately has no header. That is safe because it changes only which tools are advertised: each Agents tool still authorizes every call against the Airbyte API, and no entitlement probe happens during list_tools.

2. X-Airbyte-Organization-Id. Pairs with the existing AIRBYTE_CLOUD_ORGANIZATION_ID env var, so hosted callers can scope organization-level listings per request. An explicit organization_id tool argument still wins over it.

3. Readable authorization failures. 401/403 from the Agents API previously surfaced as an AirbyteError traceback. The four Agents tools now return their normal result shape with an empty payload and a message explaining which of the two situations applies — invalid credentials, versus authenticated-but-not-entitled/no workspace access — and telling the agent to ask rather than retry. Anything else re-raises with its original context, following the _handle_discovery_permission_error precedent in airbyte/mcp/cloud.py.

Naming/deprecation work discussed alongside this (AIRBYTE_MCP_DOMAINS → include/exclude-modules, AIRBYTE_MCP_HOSTING_URL, adopting more of GitHub's header names, and a documented index of every setting) is intentionally not here and follows in a separate PR.

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

Summary by CodeRabbit

New Features
- Added organization-scoped configuration for MCP requests through supported configuration sources.
- Added optional insiders mode to control access to select tools.
- Added organization-aware workspace and connector operations.
Bug Fixes
- Improved Agents access handling with clear messages for unauthorized or forbidden requests.
- Preserved detailed error handling for unrelated failures.
Tests
- Added coverage for organization ID resolution, access-control responses, and tool visibility rules.

Agents MCP tools are no longer advertised by default. They appear when insiders mode is enabled (AIRBYTE_MCP_INSIDERS / X-MCP-Insiders, following the GitHub MCP server's naming) or when the include-modules list names the agents module explicitly. Adds X-Airbyte-Organization-Id as a per-request source for the organization ID, and turns Agents 401/403 responses into concise tool results instead of tracebacks. Co-Authored-By: AJ Steers <aj@airbyte.io>

devin-ai-integration · 2026-08-28T21:19:17Z

🤖 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-08-28T21:19:38Z

👋 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/1787935160-agents-optin-gate' pyairbyte --help

# Install PyAirbyte from this branch for development:
pip install 'git+https://github.com/airbytehq/PyAirbyte.git@devin/1787935160-agents-optin-gate'

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.

Copilot

Pull request overview

This PR refines the Airbyte MCP server’s tool surface and request scoping by (1) hiding subscription/preview tool modules by default behind an “insiders” gate, and (2) adding per-request organization scoping, while also improving how Agents authorization failures are surfaced to callers.

Changes:

Add an insiders-mode gate to prevent advertising agents MCP tools by default unless explicitly opted in (header/env var or include list).
Add X-Airbyte-Organization-Id / AIRBYTE_CLOUD_ORGANIZATION_ID support via a new MCP config arg and use it as a fallback for Agents organization-scoped operations.
Convert Agents 401/403 failures from exceptions into normal-shaped tool results with empty payloads and a human-actionable message (tests included).

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/unit_tests/test_mcp_tool_filters.py	Adds unit tests covering the insiders gate behavior and include/exclude precedence.
tests/unit_tests/test_mcp_agents.py	Extends MCP Agents tests for org-id fallback precedence and graceful 401/403 result shaping.
airbyte/mcp/server.py	Registers the new insiders and organization-id config args with the MCP server.
airbyte/mcp/agents.py	Implements org-id fallback plus graceful authorization failure shaping for Agents tools.
airbyte/mcp/_tool_utils.py	Adds `INSIDERS_CONFIG_ARG`, `ORGANIZATION_ID_CONFIG_ARG`, and updates the module filter to support insiders-gated modules.
airbyte/constants.py	Introduces constants for insiders gating and the organization-id header/config keys.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

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

coderabbitai · 2026-08-28T21:24:36Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 13e3515a-7555-434d-9ff8-38ba4b11c6a6

📥 Commits

Reviewing files that changed from the base of the PR and between a1ab4da and bd1e472.

📒 Files selected for processing (1)

airbyte/mcp/agents.py

Included review availability: Your plan provides up to 2 included reviews per hour; 1 remains after this review.

📝 Walkthrough

Walkthrough

The MCP server adds organization ID and insiders configuration. It filters insiders-only modules. Agents tools resolve organization scope and return structured results for 401 and 403 responses. Unit tests cover filtering, configuration precedence, and authorization handling.

Changes

MCP access controls

Layer / File(s)	Summary
MCP configuration and module filtering `airbyte/constants.py`, `airbyte/mcp/_tool_utils.py`, `airbyte/mcp/server.py`, `tests/unit_tests/test_mcp_tool_filters.py`	Adds organization and insiders configuration sources. Registers both settings with the MCP server. Hides the `agents` module unless insiders mode or explicit inclusion enables it.
Agents organization and authorization handling `airbyte/mcp/agents.py`, `tests/unit_tests/test_mcp_agents.py`	Adds organization-scoped Agents requests. Converts 401 and 403 errors into structured responses with messages. Re-raises unrelated errors. Tests configuration fallback and explicit organization precedence.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: ⚪ Minimal · up to bd1e4

The PR limits Agents tools to opted-in callers, supports per-request organization scoping, and makes authorization failures readable without changing successful behavior. No actionable merge-blocking risk remains after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant MCPTool
  participant AgentOrganization
  participant AgentsAPI
  MCPTool->>AgentOrganization: Resolve explicit or configured organization_id
  AgentOrganization->>AgentsAPI: Request workspace or connector data
  AgentsAPI-->>AgentOrganization: Return data or HTTP 401/403 error
  AgentOrganization-->>MCPTool: Return result or structured access-denied message

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main changes: gating Agents MCP tools behind insiders mode and adding an organization ID header.
Docstring Coverage	✅ Passed	Docstring coverage is 93.02% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 43 functions across 6 files.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch devin/1787935160-agents-optin-gate

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

github-code-quality · 2026-08-28T21:29:07Z

Code Coverage Overview

Languages: Python

Python / code-coverage/pytest-fast

The overall line coverage in commit bd1e472 in the devin/1787935160-age... branch is 71%. The line coverage in commit d9f652f in the main branch is 65%.

Show a line coverage summary of the most impacted files.

File	`main` d9f652f	`devin/1787935160-age...` bd1e472	+/-
`airbyte/agents/_api_util.py`	0%	86%	+86%
`airbyte/mcp/int..._registry_ui.py`	0%	92%	+92%
`airbyte/agents/...rganizations.py`	0%	93%	+93%
`airbyte/cloud/models.py`	0%	95%	+95%
`airbyte/mcp/http_main.py`	0%	95%	+95%
`airbyte/mcp/agents.py`	0%	96%	+96%
`airbyte/agents/workspaces.py`	0%	96%	+96%
`airbyte/mcp/int...nc_status_ui.py`	0%	97%	+97%
`airbyte/agents/models.py`	0%	99%	+99%
`airbyte/agents/connectors.py`	0%	100%	+100%

Python / code-coverage/pytest-no-creds

The overall line coverage in commit bd1e472 in the devin/1787935160-age... branch is 68%. The line coverage in commit d9f652f in the main branch is 65%.

Show a line coverage summary of the most impacted files.

File	`main` d9f652f	`devin/1787935160-age...` bd1e472	+/-
`airbyte/agents/_api_util.py`	0%	86%	+86%
`airbyte/mcp/int..._registry_ui.py`	0%	92%	+92%
`airbyte/agents/...rganizations.py`	0%	93%	+93%
`airbyte/cloud/models.py`	0%	95%	+95%
`airbyte/mcp/http_main.py`	0%	95%	+95%
`airbyte/mcp/agents.py`	0%	96%	+96%
`airbyte/agents/workspaces.py`	0%	96%	+96%
`airbyte/mcp/int...nc_status_ui.py`	0%	97%	+97%
`airbyte/agents/models.py`	0%	99%	+99%
`airbyte/agents/connectors.py`	0%	100%	+100%

Python / code-coverage/pytest

The overall line coverage in commit bd1e472 in the devin/1787935160-age... branch is 75%. The line coverage in commit d9f652f in the main branch is 71%.

Show a line coverage summary of the most impacted files.

File	`main` d9f652f	`devin/1787935160-age...` bd1e472	+/-
`airbyte/agents/_api_util.py`	0%	86%	+86%
`airbyte/mcp/int..._registry_ui.py`	0%	92%	+92%
`airbyte/agents/...rganizations.py`	0%	93%	+93%
`airbyte/cloud/models.py`	0%	95%	+95%
`airbyte/mcp/http_main.py`	0%	95%	+95%
`airbyte/mcp/agents.py`	0%	96%	+96%
`airbyte/agents/workspaces.py`	0%	96%	+96%
`airbyte/mcp/int...nc_status_ui.py`	0%	97%	+97%
`airbyte/agents/models.py`	0%	99%	+99%
`airbyte/agents/connectors.py`	0%	100%	+100%

_{Updated August 28, 2026 21:50 UTC}

devin-ai-integration Bot assigned Aaron ("AJ") Steers (aaronsteers) Aug 28, 2026

Airbyte Support Bot (airbyte-support-bot) requested a lite review from Copilot August 28, 2026 21:19

Copilot started reviewing on behalf of Airbyte Support Bot (airbyte-support-bot) August 28, 2026 21:20 View session

Copilot AI reviewed Aug 28, 2026

View reviewed changes

Comment thread airbyte/mcp/agents.py Outdated

refactor(mcp): preserve original traceback for non-auth Agents errors

bd1e472

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

coderabbitai Bot approved these changes Aug 28, 2026

View reviewed changes

Navigation Menu

Uh oh!

feat(mcp): gate Agents tools behind insiders mode, add org-id header - #1135

feat(mcp): gate Agents tools behind insiders mode, add org-id header#1135
Aaron ("AJ") Steers (aaronsteers) wants to merge 2 commits into
mainfrom
devin/1787935160-agents-optin-gate

Aaron ("AJ") Steers (aaronsteers) commented Aug 28, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

devin-ai-integration Bot commented Aug 28, 2026

Uh oh!

github-actions Bot commented Aug 28, 2026

Testing This PyAirbyte Version

PR Slash Commands

Helpful Resources

Community Support

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

coderabbitai Bot commented Aug 28, 2026 •

edited

Loading

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

github-code-quality Bot commented Aug 28, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

Aaron ("AJ") Steers (aaronsteers) commented Aug 28, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Summary by CodeRabbit

Uh oh!

devin-ai-integration Bot commented Aug 28, 2026

🤖 Devin AI Engineer

Uh oh!

github-actions Bot commented Aug 28, 2026

👋 Greetings, Airbyte Team Member!

Testing This PyAirbyte Version

PR Slash Commands

Helpful Resources

Community Support

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

coderabbitai Bot commented Aug 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

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

Uh oh!

Code Coverage Overview

Python / code-coverage/pytest-fast

Python / code-coverage/pytest-no-creds

Python / code-coverage/pytest

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Aaron ("AJ") Steers (aaronsteers) commented Aug 28, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Aug 28, 2026 •

edited

Loading

github-code-quality Bot commented Aug 28, 2026 •

edited

Loading