feat(mcp): show search tools in insiders mode by girarda · Pull Request #1375 · airbytehq/PyAirbyte

Alexandre Girard (girarda) · 2026-10-14T04:27:09Z

Summary

👉 TL;DR: The connector search tools are no longer switched off in code. They are now hidden by default and become visible when the deployment or the caller turns on insiders mode. Specifically, this replaces the search tools' hard-coded `SEARCH_TOOLS_DISABLED` / `force_disabled` usage from #1348 with a per-tool `mcp_tool(insiders_only=True)` flag. That flag is enforced by a new `airbyte_insiders_tools_filter` that reuses the existing `AIRBYTE_MCP_INSIDERS` env var and `X-MCP-Insiders` header.

Requested by AJ (Aaron ("AJ") Steers (@aaronsteers)) to unblock semantic-search evals while the backend rolls out. Alexandre (Alexandre Girard (@girarda)) plans to enable search globally once the feature is ready.

Changes

ToolPolicy gains insiders_only: bool = False, and mcp_tool gains a matching insiders_only kwarg: the tool is registered, and whether it is shown is decided per request. force_disabled is kept unchanged (it still skips registration). It is no longer used by the search tools, and now has a unit test.
New airbyte_insiders_tools_filter, registered in server.py, behaves as not policy.insiders_only or _insiders_mode(app) is True.
execute_external_search_query and get_cloud_search_status are marked insiders_only=True.
scripts/generate_mcp_markdown.py adds an insidersOnly annotation to the report from _TOOL_POLICIES, so the generated docs show an "insiders only" availability badge on the two search tools.
Corrected the AIRBYTE_MCP_INSIDERS / X-MCP-Insiders docstrings: 1 on the env var is the default, and a caller can still narrow it with 0.
Restored the search-tool expectations that fix(mcp): hide search tools until the search backend is enabled #1348 removed from the arg-trace, annotation and policy tests, and added visibility tests.

Gating: `AIRBYTE_MCP_INSIDERS` / `X-MCP-Insiders` (default off)

The rules come from the existing _insiders_mode resolver and are unchanged:

`AIRBYTE_MCP_INSIDERS` (env, STDIO + HTTP)	`X-MCP-Insiders` (header)	Search tools
unset	unset / `0`	hidden
unset	`1`	shown
`1`	unset / `1`	shown
`1`	`0`	hidden (callers may narrow)
`0`	any	hidden

The header controls which tools are advertised. It is not an access control: each call is still authorized by the Cloud API, which returns "not enabled" for connectors without search indexing.

Follow-ups

To enable search globally later, delete the two insiders_only=True arguments.

Test plan

pytest tests/unit_tests/test_mcp_cloud.py test_mcp_arg_trace_parity.py test_mcp_tool_utils.py test_mcp_tool_annotations.py test_mcp_tool_filters.py: 253 passed.
ruff check . and pyrefly check are clean.
Ran the real server locally over HTTP and STDIO and compared list_tools against release-candidate/v1. Details are in the PR comment.

Link to Devin session: https://app.devin.ai/sessions/e6965897bf15489380e96ea10d3ee8dd
Open in Devin Desktop: https://app.devin.ai/desktop/session/e6965897bf15489380e96ea10d3ee8dd?variant=devin

Co-Authored-By: alexandre@airbyte.io <alexandre@airbyte.io>

devin-ai-integration · 2026-10-14T04:27:13Z

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

Disable automatic comment, CI, and merge conflict monitoring

octavia-bot · 2026-10-14T04:27:21Z

Note

📝 PR Converted to Draft

More info...

Thank you for creating this PR. As a policy to protect our engineers' time, Airbyte requires all PRs to be created first in draft status. Your PR has been automatically converted to draft status in respect for this policy.

As soon as your PR is ready for formal review, you can proceed to convert the PR to "ready for review" status by clicking the "Ready for review" button at the bottom of the PR page.

To skip draft status in future PRs, please include [ready] in your PR title or add the skip-draft-status label when creating your PR.

devin-ai-integration · 2026-10-14T04:27:22Z

Runtime check: real server, list_tools, this PR vs release-candidate/v1

Requested by AJ.

Method

Started the real airbyte.mcp.server.app with no auth configured: over HTTP using app.run(transport='http'), and over STDIO using the airbyte-mcp entry point.
Connected a fastmcp.Client and called list_tools().
For each run, recorded which of execute_external_search_query / get_cloud_search_status were advertised, plus the total tool count.
Nothing was mocked, but no Cloud credentials were used. This only checks which tools are advertised. It does not run a search against Cloud.

This PR (c703c56)

Transport	Server `AIRBYTE_MCP_INSIDERS`	Request `X-MCP-Insiders`	Search tools	Total tools
HTTP	unset	none	hidden	42
HTTP	unset	`1`	shown	44
HTTP	unset	`0`	hidden	42
HTTP	`1`	none	shown	44
HTTP	`1`	`1`	shown	44
HTTP	`1`	`0`	hidden	42
STDIO	unset	n/a	hidden	42
STDIO	`1`	n/a	shown	44

Base release-candidate/v1 (84c2f1c)

On base, the search tools were hidden and 42 tools were listed in all six HTTP combinations above, whether the server env was unset or 1.

Result: by default the advertised tools are exactly the same as on base (42). The two search tools show up only when the env var or the header turns them on, and an explicit 0 still hides them, as the existing insiders resolver specifies.

Written by Devin

github-actions · 2026-10-14T04:27:31Z

👋 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/1791951647-search-tools-opt-in' pyairbyte --help

# Install PyAirbyte from this branch for development:
pip install 'git+https://github.com/airbytehq/PyAirbyte.git@devin/1791951647-search-tools-opt-in'

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-10-14T04:32:15Z

Code Coverage Overview

Languages: Python

Python / code-coverage/pytest-no-creds

The overall line coverage in commit dddf984 in the devin/1791951647-sea... branch is 79%. 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/1791951647-sea...` dddf984	+/-
`airbyte/mcp/cloud.py`	52%	83%	+31%
`airbyte/_util/api_util.py`	36%	68%	+32%
`airbyte/cloud/connectors.py`	34%	75%	+41%
`airbyte/mcp/_datadog.py`	0%	50%	+50%
`airbyte/mcp/_user_identity.py`	0%	93%	+93%
`airbyte/_direct...ctors/models.py`	0%	94%	+94%
`airbyte/mcp/_telemetry.py`	0%	94%	+94%
`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 dddf984 in the devin/1791951647-sea... 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/1791951647-sea...` dddf984	+/-
`airbyte/cloud/connectors.py`	51%	80%	+29%
`airbyte/mcp/cloud.py`	52%	83%	+31%
`airbyte/mcp/_datadog.py`	0%	50%	+50%
`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%	94%	+94%
`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 dddf984 in the devin/1791951647-sea... branch is 76%. 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/1791951647-sea...` dddf984	+/-
`airbyte/cloud/models.py`	—	97%	—
`airbyte/mcp/_sso_auth.py`	—	96%	—
`airbyte/_direct...ctors/models.py`	—	94%	—
`airbyte/cloud/client.py`	—	90%	—
`airbyte/exceptions.py`	—	89%	—
`airbyte/mcp/cloud.py`	—	83%	—
`airbyte/progress.py`	—	80%	—
`airbyte/cloud/connectors.py`	—	75%	—
`airbyte/_util/api_util.py`	—	68%	—
`airbyte/shared/...ql_processor.py`	—	68%	—

_{Updated October 14, 2026 05:42 UTC}

Co-Authored-By: alexandre@airbyte.io <alexandre@airbyte.io>

Copilot

🟡 Changes recommended

Configuration precedence documentation is contradictory, and generated documentation omits per-tool insiders availability.

2 open findings

What changed in this PR

Adds per-tool insiders gating so Cloud search tools remain registered but are hidden unless insiders mode is enabled.

Changes:

Adds insiders_only tool policy and filter.
Gates two Cloud search tools.
Restores and expands related tests and tracing fixtures.

File	Description
`airbyte/constants.py`	Documents insiders configuration.
`airbyte/mcp/_tool_utils.py`	Adds per-tool insiders policy and filtering.
`airbyte/mcp/cloud.py`	Marks search tools insiders-only.
`airbyte/mcp/server.py`	Registers the insiders filter.
`tests/unit_tests/fixtures/arg_trace_plan.json`	Restores search tracing expectations.
`tests/unit_tests/test_mcp_arg_trace_parity.py`	Tests search argument tracing.
`tests/unit_tests/test_mcp_cloud.py`	Tests search-tool visibility.
`tests/unit_tests/test_mcp_tool_annotations.py`	Restores search annotation expectations.
`tests/unit_tests/test_mcp_tool_filters.py`	Tests insiders filter precedence.
`tests/unit_tests/test_mcp_tool_utils.py`	Verifies registered insiders policies.

🧠 Review effort: Balanced

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

… in generated docs Co-Authored-By: alexandre@airbyte.io <alexandre@airbyte.io>

feat(mcp): show search tools in insiders mode

c703c56

Co-Authored-By: alexandre@airbyte.io <alexandre@airbyte.io>

devin-ai-integration Bot assigned Alexandre Girard (girarda) Oct 14, 2026

octavia-bot Bot marked this pull request as draft October 14, 2026 04:27

Aaron ("AJ") Steers (aaronsteers) reviewed Oct 14, 2026

View reviewed changes

Comment thread airbyte/mcp/cloud.py Outdated

Aaron ("AJ") Steers (aaronsteers) marked this pull request as ready for review October 14, 2026 05:25

Copilot AI balanced review requested due to automatic review settings October 14, 2026 05:25

refactor(mcp): rename insiders kwarg to insiders_only

3da51c2

Co-Authored-By: alexandre@airbyte.io <alexandre@airbyte.io>

Copilot started reviewing on behalf of Aaron ("AJ") Steers (aaronsteers) October 14, 2026 05:25

View session

Aaron ("AJ") Steers (aaronsteers) reviewed Oct 14, 2026

View reviewed changes

Comment thread airbyte/mcp/_tool_utils.py

fix(mcp): keep force_disabled alongside insiders_only

a1b3cdd

Co-Authored-By: alexandre@airbyte.io <alexandre@airbyte.io>

Copilot AI reviewed Oct 14, 2026

View reviewed changes

Comment thread airbyte/constants.py Outdated

Comment thread airbyte/mcp/_tool_utils.py

Aaron ("AJ") Steers (aaronsteers) approved these changes Oct 14, 2026

View reviewed changes

docs(mcp): fix insiders precedence docs and badge insiders-only tools…

dddf984

… in generated docs Co-Authored-By: alexandre@airbyte.io <alexandre@airbyte.io>

Aaron ("AJ") Steers (aaronsteers) merged commit 8385aaa into release-candidate/v1 Oct 14, 2026
29 checks passed

Aaron ("AJ") Steers (aaronsteers) deleted the devin/1791951647-search-tools-opt-in branch October 14, 2026 17:23

Alexandre Girard (girarda) mentioned this pull request Oct 14, 2026

feat(mcp): show search tools to everyone, with links to enable search #1384

Merged

Navigation Menu

Repository navigation

feat(mcp): show search tools in insiders mode - #1375

feat(mcp): show search tools in insiders mode#1375
Aaron ("AJ") Steers (aaronsteers) merged 4 commits into
release-candidate/v1from
devin/1791951647-search-tools-opt-in

Alexandre Girard (girarda) commented Oct 14, 2026 •

edited by devin-ai-integration Bot

Loading

Uh oh!

devin-ai-integration Bot commented Oct 14, 2026

Uh oh!

octavia-bot Bot commented Oct 14, 2026

Uh oh!

devin-ai-integration Bot commented Oct 14, 2026

Uh oh!

github-actions Bot commented Oct 14, 2026

Testing This PyAirbyte Version

PR Slash Commands

Helpful Resources

Community Support

Uh oh!

github-code-quality Bot commented Oct 14, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Alexandre Girard (girarda) commented Oct 14, 2026 • edited by devin-ai-integration Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Gating: AIRBYTE_MCP_INSIDERS / X-MCP-Insiders (default off)

Follow-ups

Test plan

Uh oh!

devin-ai-integration Bot commented Oct 14, 2026

Uh oh!

octavia-bot Bot commented Oct 14, 2026

Uh oh!

devin-ai-integration Bot commented Oct 14, 2026

Uh oh!

github-actions Bot commented Oct 14, 2026

👋 Greetings, Airbyte Team Member!

Testing This PyAirbyte Version

PR Slash Commands

Helpful Resources

Community Support

Uh oh!

github-code-quality Bot commented Oct 14, 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!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Alexandre Girard (girarda) commented Oct 14, 2026 •

edited by devin-ai-integration Bot

Loading

Gating: `AIRBYTE_MCP_INSIDERS` / `X-MCP-Insiders` (default off)

github-code-quality Bot commented Oct 14, 2026 •

edited

Loading