fix(mcp): Use Field() for optional params to fix MCP tool validation

[Aaron ("AJ") Steers (aaronsteers)]

Summary

Fixes a bug where optional parameters in MCP list tools were incorrectly marked as required in the tool schema. The issue was that using Annotated[type, "description"] = None doesn't properly register the default value with FastMCP/Pydantic - it needs to use Field(description=..., default=None) inside the Annotated type hint.

Affected tools:

• list_deployed_cloud_source_connectors
• list_deployed_cloud_destination_connectors
• list_deployed_cloud_connections
• list_cloud_workspaces

Before: Calling these tools without name_contains and max_items_limit would fail with:

ValidationError: Missing required keyword only argument

After: These parameters are properly optional as intended.

Review & Testing Checklist for Human

• Test the MCP tools end-to-end - Call list_deployed_cloud_source_connectors via MCP without providing name_contains or max_items_limit to verify the fix works
• Check for other instances - Search for other Annotated[..., "string"] = None patterns in the MCP code that may have been missed
• Verify the pattern is consistent with other working MCP tools in the same file (e.g., workspace_id parameter uses Field() correctly)

Notes

• Discovered while testing Coral MCP tools in workspace e8b14943-1b39-4ea5-8d08-4792a74090de
• Link to Devin run: https://app.devin.ai/sessions/1947ddc5a24d4d0e9742d78948c37df7
• Requested by: AJ Steers (Aaron ("AJ") Steers (@aaronsteers))

Summary by CodeRabbit

• Refactor
  • Improved parameter documentation standardization across cloud operation listing tools (deployed source/destination connectors, connections, and workspaces). Optional filtering and limit parameters now have consistent, structured documentation with clear default values and behaviors.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[devin-ai-integration]

Original prompt from AJ Steers

Received message in Slack channel #ask-devin-ai:

@Devin - Let's test your Coral MCP tools. Report any anomalies immediately and do not work around them. Do not get creative.

Start by checking my sources in workspace e8b14943-1b39-4ea5-8d08-4792a74090de?
Thread URL: https://airbytehq-team.slack.com/archives/C08BHPUMEPJ/p1764725276166589

[devin-ai-integration]

🤖 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 and CI monitoring

[github-actions]

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

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/1764726000-fix-mcp-optional-params' pyairbyte --help

# Install PyAirbyte from this branch for development:
pip install 'git+https://github.com/airbytehq/PyAirbyte.git@devin/1764726000-fix-mcp-optional-params'

Helpful Resources

• PyAirbyte Documentation
• API Reference

PR Slash Commands

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

• /fix-pr - Fixes most formatting and linting issues
• /poetry-lock - Updates poetry.lock file
• /test-pr - Runs tests with the updated PyAirbyte

Community Support

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

📝 Edit this welcome message.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR refactors parameter annotations in cloud operations tool functions by moving textual descriptions from inline strings within Annotated types to structured Field(description=..., default=...) metadata. The changes affect filtering and pagination parameters across four listing endpoints with no impact to runtime behavior or logic.

Changes

Cohort / File(s)

Summary

Parameter annotation refactoring airbyte/mcp/cloud_ops.py

Updated list_deployed_cloud_source_connectors, list_deployed_cloud_destination_connectors, list_deployed_cloud_connections, and list_cloud_workspaces to wrap parameter descriptions (name_contains, max_items_limit, with_connection_status, etc.) inside Field(description=..., default=...) instead of plain string literals in Annotated type hints, improving metadata structure and tooling compatibility.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

• Verify consistency across all four function signatures—the pattern should be applied uniformly
• Confirm that description text and default values are accurately preserved during the migration from inline strings to Field metadata
• Check that no functional behavior or type hints were inadvertently altered

Possibly related PRs

• feat(mcp): add list_cloud_workspaces and describe_cloud_organization tools #883: Adds list_cloud_workspaces function to cloud_ops.py; this PR updates its parameter annotations for consistency
• feat(mcp): Add optional workspace_id parameter to cloud tools with conditional schema hiding #876: Modifies the same cloud listing functions (list_deployed_cloud_source_connectors, etc.); these PRs work on complementary aspects of the same signatures
• feat: Return names and URLs in MCP Cloud list tools #874: Adjusts return types/models for MCP cloud listing functions; this PR complements that work by standardizing parameter metadata

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: wrapping optional parameters in Field() annotations to fix MCP tool validation, which aligns with the primary modifications across multiple cloud operations functions.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch devin/1764726000-fix-mcp-optional-params

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between cf60864 and 2d41a9e.

📒 Files selected for processing (1)

• airbyte/mcp/cloud_ops.py (4 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (6)

• GitHub Check: Pytest (All, Python 3.11, Ubuntu)
• GitHub Check: Pytest (All, Python 3.10, Ubuntu)
• GitHub Check: Pytest (All, Python 3.11, Windows)
• GitHub Check: Pytest (All, Python 3.10, Windows)
• GitHub Check: Pytest (No Creds)
• GitHub Check: Pytest (Fast)

🔇 Additional comments (4)

airbyte/mcp/cloud_ops.py (4)

655-668: Consistent refactoring applied.

The same Field() pattern is correctly applied here with context-appropriate descriptions ("destinations" instead of "sources"). Nice consistency across the listing functions!

---

968-981: Good consistency fix.

These parameters now match the Field() pattern used by with_connection_status and failing_connections_only in the same function. This unifies the parameter annotation approach across all optional params.

---

1197-1210: Refactoring complete across all listing functions.

This completes the systematic migration to Field() metadata for the filtering and pagination parameters. The description for name_contains appropriately notes "server-side filtering" which distinguishes this function's behavior.

---

600-613: The Field() refactoring for optional parameters is correct and already merged.

This change properly uses Pydantic's Field() pattern with structured metadata for optional parameters (name_contains and max_items_limit), which enables FastMCP to correctly validate and expose these parameters in MCP tool definitions. The pattern is consistently applied across all listing functions and matches the existing workspace_id parameter style.

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[github-actions]

PyTest Results (Fast Tests Only, No Creds)

320 tests  ±0   320 ✅ ±0   6m 3s ⏱️ -25s
  1 suites ±0     0 💤 ±0 
  1 files   ±0     0 ❌ ±0 

Results for commit 2d41a9e. ± Comparison against base commit cf60864.

[github-actions]

PyTest Results (Full)

388 tests  ±0   372 ✅ ±0   25m 44s ⏱️ -28s
  1 suites ±0    16 💤 ±0 
  1 files   ±0     0 ❌ ±0 

Results for commit 2d41a9e. ± Comparison against base commit cf60864.