fix(cloud): default to sole instance workspace; MCP tool names in guidance by aaronsteers · Pull Request #1305 · airbytehq/PyAirbyte

Aaron ("AJ") Steers (aaronsteers) · 2026-10-02T01:34:34Z

Summary

Fixes two problems found while testing the local stdio MCP against Airbyte OSS 2.3.0 (abctl). Requested by AJ Steers.

Fresh self-managed installs have no default workspace. The default OSS user is an instance admin with no workspace memberships and no defaultWorkspaceId. resolve_default_workspace_id() therefore returned None, and every tool that needs a workspace failed. This PR adds a last fallback that applies only when the user has no direct workspace grants at all:
```
# CloudClient.resolve_default_workspace_id, after the direct-grant check
if live_workspaces or unvalidated_count:
    return None
return self._get_sole_instance_workspace_id()
# -> instance admins only: list_workspaces_by_user(limit=2, page_size=2); returns the ID if exactly one workspace exists, else None
```
api_util.list_workspaces_by_user gains an optional page_size (default 100, so existing callers are unchanged). The fallback therefore requests only two rows, even on Cloud.
In local MCP mode, the AirbyteMissingWorkspaceContextError guidance named tools that don't exist. MCP tool names (list_cloud_workspaces, ...) were used only when is_hosted_mcp_mode() was true. Local stdio MCP users were therefore told to call list_workspaces / list_organizations / get_default_context_for_user, which are Python method names. The check is now is_mcp_mode(), which is set for both stdio and HTTP. Python library users still get the method names.

Not in this PR: the self-managed web URL fix (get_web_url_root, #563), which is being handled separately. The structured JSON returns for deploy and sync tools are tracked in #1306.

Tests: a new parametrized test in test_cloud_client.py covers an instance admin with one workspace, an instance admin with several, and a non-admin. A new test checks that list_workspaces_by_user honors page_size. test_exceptions.py was updated for the mode check. I also verified both fixes end to end against a fresh OSS install; details are in the PR comment.

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

…ol names in local MCP guidance Co-Authored-By: AJ Steers <aj@airbyte.io>

devin-ai-integration · 2026-10-02T01:34:37Z

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

github-actions · 2026-10-02T01:34:55Z

👋 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/1790904754-oss-mcp-workspace-defaults' pyairbyte --help

# Install PyAirbyte from this branch for development:
pip install 'git+https://github.com/airbytehq/PyAirbyte.git@devin/1790904754-oss-mcp-workspace-defaults'

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.

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

github-code-quality · 2026-10-02T01:45:50Z

Code Coverage Overview

Languages: Python

Python / code-coverage/pytest-no-creds

The overall line coverage in commit 93e122c in the devin/1790904754-oss... 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/1790904754-oss...` 93e122c	+/-
`airbyte/_util/api_util.py`	36%	61%	+25%
`airbyte/mcp/cloud.py`	52%	80%	+28%
`airbyte/cloud/connectors.py`	34%	73%	+39%
`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 93e122c in the devin/1790904754-oss... branch is 80%. 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/1790904754-oss...` 93e122c	+/-
`airbyte/cloud/connectors.py`	51%	78%	+27%
`airbyte/mcp/cloud.py`	52%	80%	+28%
`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 93e122c in the devin/1790904754-oss... branch is 74%. 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/1790904754-oss...` 93e122c	+/-
`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`	—	73%	—
`airbyte/shared/...ql_processor.py`	—	68%	—
`airbyte/_util/api_util.py`	—	61%	—

_{Updated October 02, 2026 01:53 UTC}

devin-ai-integration · 2026-10-02T01:54:50Z

E2E verification at 93e122c8: I tested against a fresh Airbyte OSS 2.3.0 install (abctl v0.30.4) through the real local stdio MCP (uv run airbyte-mcp), with AIRBYTE_CLOUD_WORKSPACE_ID unset and /setup never completed.

The test user was an instance admin with no direct workspace memberships and no stored default.

get_default_cloud_context({}) returned the sole "Default Workspace" (default_workspace_verified: true, configured_workspace_id: null, member_workspaces: []).
Without a workspace_id, list_cloud_connections({}) returned [] with no error, and deploy_noop_destination_to_cloud and a Faker source deploy both landed in that workspace.

After I created a second workspace, the default became unresolved, as expected. An implicit call then failed with:

Workspace ID is required but not provided. The authenticated user's default workspace was checked and none was available. `list_cloud_workspaces` returns direct workspace memberships by default; pass `organization_id`/`organization_name` or a broader `privilege_scope` for organization-wide discovery, or call `list_cloud_organizations` to search organizations by name. If exactly one workspace is found, use it; otherwise ask the user to choose. Call `get_default_cloud_context` to inspect your memberships.

The message uses MCP tool names only; none of the Python method names appear.

Selecting a workspace explicitly worked. After deleting the second workspace in cleanup, the sole-workspace default resolved again.

Not covered: creating a connection and running a sync. Connector discovery hit Docker Hub rate limits (HTTP 429) in the test environment, and neither is affected by this PR.

Written by Devin

devin-ai-integration

Devin Review found 1 potential issue.

1 flag not posted on this PR by your GitHub settings — view it in Devin Review. (Configure)

devin-ai-integration · 2026-10-02T17:24:00Z

_make_config_api_request

+        except (AirbyteError, exc.PyAirbyteInputError):
+            return None


🟡 Workspace lookup failures escape default resolution

If instance-wide discovery times out, _get_sole_instance_workspace_id propagates the transport error. _make_config_api_request leaves request failures unwrapped, so workspace-dependent calls fail instead of reporting missing workspace context.

Learn more

The fallback runs only after the user has no verified direct workspaces and has instance-admin permission. It calls the Config API through _make_config_api_request, which makes a requests.request call without converting connection or timeout failures to AirbyteError. Those failures bypass this handler, unlike Config API HTTP errors, so a failed optional lookup interrupts default resolution instead of returning None.

Example: An instance admin has no workspace memberships or stored default. The permissions lookup succeeds, then the workspace-list request times out. resolve_default_workspace_id() raises requests.Timeout rather than returning None; an MCP tool cannot raise its missing-workspace guidance.

Recommended fix: Catch the transport exceptions raised by _make_config_api_request in this optional fallback, or normalize them into AirbyteError at the API boundary. Preserve the current behavior for successful lookups and ambiguous workspace lists.

Was this helpful? React with 👍 or 👎 to provide feedback.

fix(cloud): default to an instance admin's sole workspace; use MCP to…

8a02755

…ol names in local MCP guidance Co-Authored-By: AJ Steers <aj@airbyte.io>

devin-ai-integration Bot assigned Aaron ("AJ") Steers (aaronsteers) Oct 2, 2026

Airbyte Support Bot (airbyte-support-bot) requested a balanced review from Copilot October 2, 2026 01:34

devin-ai-integration Bot mentioned this pull request Oct 2, 2026

MCP: return structured results from Cloud deploy/connection/sync tools instead of prose strings #1306

Open

Copilot started reviewing on behalf of Airbyte Support Bot (airbyte-support-bot) October 2, 2026 01:35 View session

This comment was marked as resolved.

Sign in to view

fix(cloud): request only two workspaces per page in sole-workspace fa…

93e122c

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

Aaron ("AJ") Steers (aaronsteers) marked this pull request as ready for review October 2, 2026 17:22

Aaron ("AJ") Steers (aaronsteers) merged commit b76087a into release-candidate/v1 Oct 2, 2026
24 checks passed

Aaron ("AJ") Steers (aaronsteers) deleted the devin/1790904754-oss-mcp-workspace-defaults branch October 2, 2026 17:22

devin-ai-integration Bot reviewed Oct 2, 2026

View reviewed changes

Navigation Menu

fix(cloud): default to sole instance workspace; MCP tool names in guidance - #1305

fix(cloud): default to sole instance workspace; MCP tool names in guidance#1305
Aaron ("AJ") Steers (aaronsteers) merged 2 commits into
release-candidate/v1from
devin/1790904754-oss-mcp-workspace-defaults

Aaron ("AJ") Steers (aaronsteers) commented Oct 2, 2026 •

edited by devin-ai-integration Bot

Loading

Uh oh!

devin-ai-integration Bot commented Oct 2, 2026

Uh oh!

github-actions Bot commented Oct 2, 2026

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 Oct 2, 2026 •

edited

Loading

Uh oh!

devin-ai-integration Bot commented Oct 2, 2026

Uh oh!

Uh oh!

devin-ai-integration Bot left a comment

Uh oh!

devin-ai-integration Bot Oct 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

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

Uh oh!

Summary

Uh oh!

devin-ai-integration Bot commented Oct 2, 2026

Uh oh!

github-actions Bot commented Oct 2, 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 Oct 2, 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!

devin-ai-integration Bot commented Oct 2, 2026

Uh oh!

Uh oh!

devin-ai-integration Bot left a comment

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration Bot Oct 2, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Aaron ("AJ") Steers (aaronsteers) commented Oct 2, 2026 •

edited by devin-ai-integration Bot

Loading

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

edited

Loading