fix(mcp): guide Connector Builder agents through the credentials flow by aaronsteers · Pull Request #1410 · airbytehq/PyAirbyte

Aaron ("AJ") Steers (aaronsteers) · 2026-10-19T19:42:45Z

Summary

Guides agents building a connector that needs credentials. They create a draft test source up front, then ask the user to enter credentials in both the Connector Builder testing values and that test source, never in chat.

Builds on the Connector Builder tools from #1407.

create_connector_builder_project docstring: for a connector that needs credentials, put the spec in the initial manifest (secrets marked airbyte_secret) and set create_test_source. The test source is saved as a draft (deferred credentials), so an auth process that hasn't been tested yet doesn't block it.
Suggested spec shape, following the 39 certified manifests that use it: a credentials object whose oneOf options each have a constant auth_type (api_key, access_token, oauth2.0). When there is more than one option, use a SelectiveAuthenticator with authenticator_selection_path: ["credentials", "auth_type"].
The result always includes next_steps. With a test source, they ask the user to enter credentials at connector_builder_project_url, and at test_source_settings_url followed by test and save.
spec_missing_required now looks inside nested objects and oneOf options. The const values pick the option, a masked secret (**********) counts as present, and a field with a default stays optional. Readiness check 4 ("Ask the user to enter testing values, including secrets, in the Connector Builder UI") fails while a required value is missing, and its next step includes the project URL. create_test_source defers credentials on the same rule.

spec_missing_required(CREDENTIALS_ONE_OF_SPEC, {"credentials": {"auth_type": "api_key"}})  # True
spec_missing_required(CREDENTIALS_ONE_OF_SPEC, {"credentials": {"auth_type": "api_key", "api_key": "**********"}})  # False

Evidence

Recorded Goose Desktop (Opus 4.7) run against cloud-mcp-preview at d3415c07 (airbyte==0.71.2.dev141039313338033). Fresh chat, no nudges. The source was GitHub with 5 streams and a PAT that I entered only in the Cloud UI.

Object	Result
Initial manifest + `create_test_source=true`	✅ Spec up front. Draft test source, so nothing blocked on auth.
Credential request	✅ Asked for both places and gave both URLs. Told the user not to paste the token in chat. Waited for confirmation.
Test reads	✅ All 5 streams read to end with no errors (1 / 1,280 / 952 / 192 / 342 records).
Tool calls	9 calls, 0 errors, 2 readiness calls
`credentials` `oneOf` shape	❌ Not followed. It used a top-level `personal_access_token` with `BearerAuthenticator`.
Full sync to dev-null	⚠️ Job `111819009` was accepted and showed running, but was still at 0 records with no attempts 14 minutes later. Cause unknown.

Agent asks for both UI locations	Builder testing values stay masked

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

devin-ai-integration · 2026-10-19T19:42:49Z

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-19T19:43:05Z

👋 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/1792438676-connector-builder-credentials-flow' pyairbyte --help

# Install PyAirbyte from this branch for development:
pip install 'git+https://github.com/airbytehq/PyAirbyte.git@devin/1792438676-connector-builder-credentials-flow'

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
/evals - Runs the Cloud MCP evals that use the MCP tools this PR changed (/evals full=true runs the full suite)

📚 Show Repo Guidance

Helpful Resources

Community Support

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

📝 Edit this welcome message.

github-actions · 2026-10-19T19:43:37Z

Prerelease Build Started

Building and publishing prerelease package from this PR...
Check job output.
Prerelease Published to PyPI

Version: 0.71.2.dev141039313338033
View publish workflow

Install with:
pip install airbyte==0.71.2.dev141039313338033

github-code-quality · 2026-10-19T19:47:51Z

Code coverage overview

Languages: Python

Python / code-coverage/pytest-no-creds

release-candidate/v1 d9f652f	devin/1792438676-con... 710ad19	+/-
65%	80%	+15%

View coverage of the 10 most impacted files.

File	release-candidate/v1 d9f652f	devin/1792438676-con... 710ad19	+/-
`airbyte/_util/api_util.py`	36%	67%	+31%
`airbyte/mcp/cloud.py`	52%	85%	+33%
`airbyte/cloud/connectors.py`	34%	79%	+45%
`airbyte/mcp/_datadog.py`	0%	50%	+50%
`airbyte/mcp/_telemetry.py`	0%	94%	+94%
`airbyte/cloud/c...lder/project.py`	0%	94%	+94%
`airbyte/_direct...ctors/models.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

release-candidate/v1 d9f652f	devin/1792438676-con... 710ad19	+/-
71%	82%	+11%

View coverage of the 10 most impacted files.

File	release-candidate/v1 d9f652f	devin/1792438676-con... 710ad19	+/-
`airbyte/cloud/connectors.py`	51%	82%	+31%
`airbyte/mcp/cloud.py`	52%	85%	+33%
`airbyte/mcp/_datadog.py`	0%	50%	+50%
`airbyte/mcp/_user_identity.py`	0%	93%	+93%
`airbyte/mcp/_telemetry.py`	0%	94%	+94%
`airbyte/cloud/c...lder/project.py`	0%	94%	+94%
`airbyte/_direct...ctors/models.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

release-candidate/v1	devin/1792438676-con... 710ad19	+/-
—	77%	—

Line coverage data for the release-candidate/v1 branch is not yet available.

View coverage of the 10 most covered files.

File	release-candidate/v1	devin/1792438676-con... 710ad19	+/-
`airbyte/cloud/models.py`	—	97%	—
`airbyte/mcp/_sso_auth.py`	—	96%	—
`airbyte/_direct...ctors/models.py`	—	95%	—
`airbyte/cloud/client.py`	—	90%	—
`airbyte/exceptions.py`	—	90%	—
`airbyte/mcp/cloud.py`	—	85%	—
`airbyte/progress.py`	—	80%	—
`airbyte/cloud/connectors.py`	—	79%	—
`airbyte/shared/...ql_processor.py`	—	68%	—
`airbyte/_util/api_util.py`	—	67%	—

ℹ️ Calculations represent line coverage. Results may change as calculations are updated.

_{Updated October 20, 2026 06:19 UTC}

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)

Copilot

🟢 Approval recommended

The focused changes match the intended credential flow, have targeted unit coverage, and have no identified blocking issues.

No open issues 🎉

What changed in this PR

Improves the hosted Connector Builder credential flow by directing users to enter secrets in the UI rather than chat.

Changes:

Adds credential setup guidance and next_steps to project creation.
Makes readiness checks detect missing required top-level values and include the project URL.
Adds unit coverage for setup guidance and testing-value checks.

File	Description
`tests/unit_tests/test_mcp_cloud.py`	Tests next steps with and without a test source.
`tests/unit_tests/test_cloud_connector_builder.py`	Covers missing values, masked secrets, defaults, and no-input specs.
`airbyte/mcp/connector_builder.py`	Documents credential setup and returns UI instructions.
`airbyte/cloud/connector_builder/_util.py`	Tightens testing-value checks and includes readiness details.

_{Review effort: Balanced}

Aaron ("AJ") Steers (aaronsteers) · 2026-10-20T06:05:27Z

Devin, update from main now that base pr has merged

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

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

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

devin-ai-integration · 2026-10-20T06:07:39Z

Done. I retargeted this PR to release-candidate/v1, since #1407 squash-merged there as 9edd3ce, and replayed this PR's 6 commits onto it. The new head is 710ad19. There were no conflicts, and the range-diff is identical commit for commit. Locally, 386 targeted tests pass, and Ruff and Pyrefly are clean. CI is running.

Written by Devin

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

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

View reviewed changes

Comment thread airbyte/mcp/connector_builder.py Outdated

Aaron ("AJ") Steers (aaronsteers) marked this pull request as ready for review October 20, 2026 02:33

Copilot AI balanced review requested due to automatic review settings October 20, 2026 02:33

Copilot started reviewing on behalf of Aaron ("AJ") Steers (aaronsteers) October 20, 2026 02:34

View session

devin-ai-integration Bot reviewed Oct 20, 2026

View reviewed changes

Comment thread airbyte/cloud/connector_builder/_util.py

Copilot AI reviewed Oct 20, 2026

View reviewed changes

devin-ai-integration Bot force-pushed the devin/1792438676-connector-builder-credentials-flow branch 3 times, most recently from 7355b1b to 10f264a Compare October 20, 2026 05:31

Base automatically changed from devin/1792350894-connector-builder-tools to release-candidate/v1 October 20, 2026 06:04

devin-ai-integration Bot and others added 6 commits October 20, 2026 06:06

fix(mcp): guide Connector Builder agents through the credentials flow

f507f38

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

docs(mcp): suggest a credentials oneOf shape for Connector Builder specs

49e812b

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

docs(mcp): say the draft test source keeps untested auth processes fr…

3c993bb

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

fix(mcp): check nested and oneOf required fields in testing values

d349719

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

style: wrap spec_missing_required docstring

a2e95ef

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

fix(mcp): adapt credentials flow to connector builder refactors

710ad19

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

devin-ai-integration Bot force-pushed the devin/1792438676-connector-builder-credentials-flow branch from 10f264a to 710ad19 Compare October 20, 2026 06:07

Aaron ("AJ") Steers (aaronsteers) merged commit 0cf49b3 into release-candidate/v1 Oct 20, 2026
30 checks passed

Aaron ("AJ") Steers (aaronsteers) deleted the devin/1792438676-connector-builder-credentials-flow branch October 20, 2026 06:39

Navigation Menu

Repository navigation

fix(mcp): guide Connector Builder agents through the credentials flow - #1410

fix(mcp): guide Connector Builder agents through the credentials flow#1410
Aaron ("AJ") Steers (aaronsteers) merged 6 commits into
release-candidate/v1from
devin/1792438676-connector-builder-credentials-flow

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

edited by devin-ai-integration Bot

Loading

Uh oh!

devin-ai-integration Bot commented Oct 19, 2026

Uh oh!

github-actions Bot commented Oct 19, 2026

Testing This PyAirbyte Version

PR Slash Commands

Helpful Resources

Community Support

Uh oh!

github-actions Bot commented Oct 19, 2026 •

edited

Loading

Uh oh!

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

edited

Loading

Uh oh!

Uh oh!

devin-ai-integration Bot left a comment

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

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

Uh oh!

devin-ai-integration Bot commented Oct 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

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

Uh oh!

Summary

Evidence

Uh oh!

devin-ai-integration Bot commented Oct 19, 2026

Uh oh!

github-actions Bot commented Oct 19, 2026

👋 Greetings, Airbyte Team Member!

Testing This PyAirbyte Version

PR Slash Commands

Helpful Resources

Community Support

Uh oh!

github-actions Bot commented Oct 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

devin-ai-integration Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

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

Uh oh!

devin-ai-integration Bot commented Oct 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

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

edited by devin-ai-integration Bot

Loading

github-actions Bot commented Oct 19, 2026 •

edited

Loading

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

edited

Loading