fix: Proper MCP / Oauth support

[erichare]

This pull request refactors the OAuth callback configuration by replacing the legacy oauth_callback_path field with a new, more descriptive oauth_callback_url field across the backend, frontend, documentation, and API schema. It also introduces backwards compatibility handling to ensure existing configurations remain functional while encouraging migration to the new field.

OAuth Callback Field Migration

• Added new oauth_callback_url field to backend models (AuthSettings), frontend types (AuthSettingsType), and API schemas (openapi.yaml, openapi.json), marking oauth_callback_path as deprecated and updating documentation to reflect the change. [1] [2] [3] [4] [5]
• Updated frontend logic in authModal/index.tsx to use oauth_callback_url, with fallback to oauth_callback_path for backwards compatibility, and revised UI labels from "Callback Path" to "Callback URL". [1] [2] [3] [4] [5] [6]
• Modified backend service startup (service.py) and environment variable mapping to use oauth_callback_url, with logic to fallback to oauth_callback_path if necessary. [1] [2]
• Implemented a post-init normalization method in the backend model so that if only the deprecated field is set, it is mapped to the new field automatically.
• Updated documentation and OpenAPI schema to indicate deprecation and guide users to use the new field. [1] [2] [3]

These changes ensure a smoother transition for users and developers, improve clarity, and maintain compatibility with existing configurations.

Summary by CodeRabbit

• New Features

  • Added Token URL, MCP Scope, and Provider Scope fields to OAuth configuration documentation.

• Bug Fixes

  • Renamed OAuth callback field from "Callback Path" to "Callback URL" to clarify it expects a full URL.
  • Updated OAuth callback configuration to enforce exact URL matching with providers.

• Documentation

  • Expanded OAuth configuration documentation with detailed field descriptions and examples.

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

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Walkthrough

This PR renames the OAuth callback field from oauth_callback_path to oauth_callback_url across backend, frontend, and OpenAPI specifications while maintaining backward compatibility. The deprecated field is marked in documentation and schemas, with fallback logic implemented in schemas and the MCP Composer service.

Changes

Cohort / File(s)	Summary
Documentation docs/docs/Agents/mcp-server.mdx	Updated OAuth configuration table: renamed "Callback Path" to "Callback URL" with clarification that it must be a full URL matching OAuth provider registration; added new rows for "Token URL", "MCP Scope", and "Provider Scope".
OpenAPI Specifications docs/openapi/openapi.json, docs/openapi/openapi.yaml	Added oauth_callback_url property to AuthSettings schema; marked oauth_callback_path as deprecated with guidance to use the new field instead.
Backend Schema src/backend/base/langflow/api/v1/schemas.py	Added oauth_callback_url: str | None = None field to AuthSettings; implemented model_post_init method with backward compatibility logic: if oauth_callback_url is not set, it is populated from oauth_callback_path, with oauth_callback_url taking precedence if both are provided.
Frontend UI & Types src/frontend/src/modals/authModal/index.tsx, src/frontend/src/types/mcp/index.ts	Renamed OAuth callback field throughout authModal component (state, effects, auto-sync, API payload); updated UI labels from "Callback Path" to "Callback URL"; added initialization fallback from oauth_callback_path for backward compatibility; marked oauth_callback_path as deprecated in AuthSettingsType.
MCP Composer Service src/lfx/src/lfx/services/mcp_composer/service.py	Updated environment variable mapping to use oauth_callback_url; added logic to populate oauth_callback_url from oauth_callback_path when the new field is not provided.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

• Changes follow a consistent pattern across multiple files (straightforward field rename with homogeneous backward-compatibility logic)
• Primary areas to verify: backward-compatibility fallback logic in schemas.py and service.py work as intended; frontend fallback on initialization and auto-sync use the correct field precedence

Possibly related PRs

• refactor: Update MCP composer auth to just api and oauth #9487: Modifies the same AuthSettings/authModal codepaths for OAuth-related field changes and MCP composer environment handling.
• feat: adds api key functionality onto mcp composer #9498: Also updates AuthSettings schema in src/backend/base/langflow/api/v1/schemas.py for OAuth-related configuration.
• refactor: Update mcp composer json #9158: Related MCP composer/server OAuth settings handling including callback naming and environment variable construction.

Suggested labels

documentation, needs-docs, lgtm

Suggested reviewers

• lucaseduoli
• mfortman11
• edwinjosechittilappilly

Pre-merge checks and finishing touches

Important

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

❌ Failed checks (1 error, 2 warnings, 1 inconclusive)

Check name	Status	Explanation	Resolution
Test Coverage For New Implementations	❌ Error	PR makes significant changes across backend schemas, frontend components, and service layer without corresponding test files.	Add unit tests for AuthSettings.model_post_init(), frontend authModal component tests, and service layer tests for MCP Composer with backwards compatibility verification.
Test Quality And Coverage	⚠️ Warning	PR implements OAuth callback configuration changes (AuthSettings.oauth_callback_url, authModal refactoring, mcp_composer updates) but adds no corresponding tests for model_post_init normalization logic, backwards compatibility fallback behavior, component state management, or service integration.	Add tests validating: (1) AuthSettings.model_post_init precedence logic, (2) oauth_callback_path fallback behavior, (3) authModal oauth_callback_url state initialization and payload construction, (4) mcp_composer service environment variable mapping for both old/new field configurations to ensure backwards compatibility.
Test File Naming And Structure	⚠️ Warning	PR modifies OAuth callback configuration in backend schemas and frontend components without adding corresponding test files to verify the changes.	Add test files: test_schemas.py for AuthSettings model_post_init logic, tests for mcp_composer oauth_callback_url fallback, and authModal.test.tsx for component field renaming.
Title check	❓ Inconclusive	The title 'fix: Proper MCP / Oauth support' is vague and generic, lacking specificity about the actual change being made.	Consider a more specific title that captures the main change, such as 'refactor: Replace oauth_callback_path with oauth_callback_url' or 'fix: Rename OAuth callback field to use full URL instead of path'.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Excessive Mock Usage Warning	✅ Passed	The pull request contains only documentation, API specifications, and implementation code changes with no test files or test code modifications.

---

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.}

[codecov]

Codecov Report

❌ Patch coverage is 76.92308% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 32.97%. Comparing base (63141c1) to head (b8698f0).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
src/lfx/src/lfx/services/mcp_composer/service.py	0.00%	1 Missing and 1 partial ⚠️
src/frontend/src/modals/authModal/index.tsx	83.33%	0 Missing and 1 partial ⚠️

❌ Your project status has failed because the head coverage (39.26%) is below the target coverage (60.00%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #10965      +/-   ##
==========================================
+ Coverage   32.94%   32.97%   +0.02%     
==========================================
  Files        1387     1387              
  Lines       65371    65382      +11     
  Branches     9679     9681       +2     
==========================================
+ Hits        21539    21557      +18     
+ Misses      42736    42728       -8     
- Partials     1096     1097       +1     

Flag	Coverage Δ
backend	52.25% <100.00%> (+0.07%)	⬆️
frontend	15.16% <83.33%> (+<0.01%)	⬆️
lfx	39.26% <0.00%> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/backend/base/langflow/api/v1/schemas.py	96.21% <100.00%> (+0.05%)	⬆️
src/frontend/src/modals/authModal/index.tsx	81.25% <83.33%> (+0.19%)	⬆️
src/lfx/src/lfx/services/mcp_composer/service.py	57.50% <0.00%> (-0.18%)	⬇️

... and 5 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (5)

src/backend/base/langflow/api/v1/schemas.py (1)

438-443: Consider handling empty strings in normalization.

The model_post_init method only checks for None values, but the service layer (line 1305 in service.py) also treats empty strings as requiring fallback to oauth_callback_path. For consistency, consider normalizing empty strings as well:

 def model_post_init(self, __context, /) -> None:
     """Normalize oauth_callback_path to oauth_callback_url for backwards compatibility."""
     # If oauth_callback_url is not set but oauth_callback_path is, use the path value
-    if self.oauth_callback_url is None and self.oauth_callback_path is not None:
+    if (self.oauth_callback_url is None or not self.oauth_callback_url) and self.oauth_callback_path:
         self.oauth_callback_url = self.oauth_callback_path
-    # If both are set, oauth_callback_url takes precedence (already set correctly)

This ensures that both empty strings and None values trigger the backward compatibility fallback, matching the service layer logic.

docs/openapi/openapi.yaml (1)

4300-4311: AuthSettings: deprecation + new oauth_callback_url field look correct

The schema keeps oauth_callback_path with a clear deprecation notice and introduces oauth_callback_url with matching optional string/null typing, so existing clients remain valid while new ones can migrate to the URL-based field. Consider optionally adding format: uri on oauth_callback_url (and possibly the deprecated field) to better communicate expected semantics to tooling, but this is not required.

src/frontend/src/modals/authModal/index.tsx (1)

89-122: OAuth callback URL autosync works, with two small polish opportunities

The autosync logic for oauthCallbackUrl (including the regex guard and new URL construction) is reasonable and avoids overwriting customized values. Two minor nits you may want to consider:

• The comment on Line 96 still says “Callback Path”; updating it to “Callback URL” would better match the new behavior.
• When autosyncing, you always generate http://${host}:${port}/auth/idaas/callback. If users configure an HTTPS server URL, this will silently downgrade to http. You could optionally derive the scheme from oauthServerUrl (falling back to http if absent) to better respect secure setups.

UI wiring (label htmlFor, input id, value binding, and handleAuthFieldChange("oauthCallbackUrl", ...)) all line up correctly.

Also applies to: 280-297, 124-139

docs/openapi/openapi.json (2)

6971-6983: Clarify deprecation and enforce path-only semantics for legacy field.

Good deprecation. To prevent ambiguous values and guide migration, constrain the legacy field to a path and add an example/reason.

           "oauth_callback_path": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
+            "anyOf": [
+              {
+                "type": "string",
+                "pattern": "^/.*"
+              },
+              {
+                "type": "null"
+              }
+            ],
             "title": "Oauth Callback Path",
             "deprecated": true,
-            "description": "Deprecated: Use oauth_callback_url instead"
+            "description": "Deprecated: Use oauth_callback_url instead. This legacy field accepts only a path (e.g., '/oauth/callback').",
+            "examples": ["/oauth/callback"],
+            "x-deprecated-reason": "Replaced by oauth_callback_url; path-only value caused ambiguity behind proxies."
           },

---

6984-6994: Validate absolute URL and state precedence.

Add URI format, an example, and a brief precedence note to reduce misconfigurations.

           "oauth_callback_url": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ],
-            "title": "Oauth Callback Url"
+            "anyOf": [
+              {
+                "type": "string",
+                "format": "uri",
+                "minLength": 1
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Oauth Callback Url",
+            "description": "Absolute callback URL used as the OAuth redirect_uri. If both oauth_callback_url and oauth_callback_path are provided, oauth_callback_url takes precedence.",
+            "examples": ["https://app.example.com/api/oauth/callback"]
           },

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f3c08db and ead53b3.

📒 Files selected for processing (7)

• docs/docs/Agents/mcp-server.mdx (1 hunks)
• docs/openapi/openapi.json (1 hunks)
• docs/openapi/openapi.yaml (1 hunks)
• src/backend/base/langflow/api/v1/schemas.py (1 hunks)
• src/frontend/src/modals/authModal/index.tsx (6 hunks)
• src/frontend/src/types/mcp/index.ts (1 hunks)
• src/lfx/src/lfx/services/mcp_composer/service.py (2 hunks)

🧰 Additional context used

📓 Path-based instructions (6)

src/frontend/src/**/*.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/frontend_development.mdc)

src/frontend/src/**/*.{ts,tsx}: Use React 18 with TypeScript for frontend development
Use Zustand for state management

Files:

• src/frontend/src/types/mcp/index.ts
• src/frontend/src/modals/authModal/index.tsx

docs/docs/**/*.{md,mdx}

📄 CodeRabbit inference engine (.cursor/rules/docs_development.mdc)

docs/docs/**/*.{md,mdx}: Markdown files must include YAML frontmatter with title, description, and sidebar_position
Use Docusaurus admonitions (:::tip, :::warning, :::danger) for important information, warnings, and critical alerts
Code blocks must include a title attribute and specify the language (e.g., ```python title="filename.py")
All images must use descriptive alt text that clearly explains what the image shows
Use sentence case for headers and proper capitalization for terminology: Langflow, Component, Flow, API, JSON
Use bold formatting for UI elements, italic for emphasis, and backticks for inline code
Use second person ('you') for instructions and present tense for current features in documentation content
Tables in documentation must include columns for Input/Output name, Type, Required (if applicable), and Description
Internal links between documentation pages must be functional and properly formatted using Docusaurus link syntax

Files:

• docs/docs/Agents/mcp-server.mdx

src/backend/**/*.py

📄 CodeRabbit inference engine (.cursor/rules/backend_development.mdc)

src/backend/**/*.py: Use FastAPI async patterns with await for async operations in component execution methods
Use asyncio.create_task() for background tasks and implement proper cleanup with try/except for asyncio.CancelledError
Use queue.put_nowait() for non-blocking queue operations and asyncio.wait_for() with timeouts for controlled get operations

Files:

• src/backend/base/langflow/api/v1/schemas.py

src/backend/base/langflow/api/**/*.py

📄 CodeRabbit inference engine (.cursor/rules/backend_development.mdc)

Backend API endpoints should be organized by version (v1/, v2/) under src/backend/base/langflow/api/ with specific modules for features (chat.py, flows.py, users.py, etc.)

Files:

• src/backend/base/langflow/api/v1/schemas.py

src/frontend/src/**/*.{tsx,jsx,css,scss}

📄 CodeRabbit inference engine (.cursor/rules/frontend_development.mdc)

Use Tailwind CSS for styling

Files:

• src/frontend/src/modals/authModal/index.tsx

src/frontend/src/**/*.{tsx,jsx}

📄 CodeRabbit inference engine (.cursor/rules/frontend_development.mdc)

src/frontend/src/**/*.{tsx,jsx}: Implement dark mode support using the useDarkMode hook and dark store
Use Lucide React for icon components in the application

Files:

• src/frontend/src/modals/authModal/index.tsx

⏰ 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). (22)

• GitHub Check: Run Backend Tests / Unit Tests - Python 3.10 - Group 5
• GitHub Check: Run Backend Tests / Unit Tests - Python 3.10 - Group 2
• GitHub Check: Run Backend Tests / Unit Tests - Python 3.10 - Group 3
• GitHub Check: Run Backend Tests / Unit Tests - Python 3.10 - Group 1
• GitHub Check: Run Backend Tests / Unit Tests - Python 3.10 - Group 4
• GitHub Check: Lint Backend / Run Mypy (3.12)
• GitHub Check: Lint Backend / Run Mypy (3.11)
• GitHub Check: Test Docker Images / Test docker images
• GitHub Check: Lint Backend / Run Mypy (3.10)
• GitHub Check: Lint Backend / Run Mypy (3.13)
• GitHub Check: Run Frontend Unit Tests / Frontend Jest Unit Tests
• GitHub Check: Run Backend Tests / Integration Tests - Python 3.10
• GitHub Check: Run Backend Tests / Test CLI - Python 3.10
• GitHub Check: Run Backend Tests / LFX Tests - Python 3.10
• GitHub Check: Run Frontend Tests / Determine Test Suites and Shard Distribution
• GitHub Check: Test Docs Build / Test Docs Build
• GitHub Check: Test Starter Templates
• GitHub Check: Optimize new Python code in this PR
• GitHub Check: build-and-deploy
• GitHub Check: Run Ruff Check and Format
• GitHub Check: Update Starter Projects
• GitHub Check: Update Component Index

🔇 Additional comments (4)

src/lfx/src/lfx/services/mcp_composer/service.py (1)

1291-1308: LGTM! Backward compatibility properly implemented.

The environment variable mapping has been updated to use oauth_callback_url, and the backward compatibility logic correctly falls back to oauth_callback_path when the new field is not provided. The implementation checks for both absence and empty values, ensuring robust migration support.

docs/docs/Agents/mcp-server.mdx (1)

240-240: LGTM! Clear documentation update.

The field label and description have been updated to accurately reflect that a full callback URL is required, which must match exactly what is registered with the OAuth provider. This clarifies the migration from path to URL.

src/frontend/src/types/mcp/index.ts (1)

6-7: LGTM! Proper deprecation and new field addition.

The type definition correctly adds the new oauth_callback_url field and marks oauth_callback_path as deprecated with a clear inline comment guiding developers to use the new field.

src/frontend/src/modals/authModal/index.tsx (1)

33-59: Init/useEffect fallback from oauth_callback_path → oauth_callback_url is sound

State initialization and the useEffect correctly prefer oauth_callback_url and fall back to oauth_callback_path, so existing projects migrate seamlessly while new ones use the canonical field. No functional issues here.

Also applies to: 61-81

[github-actions]

Frontend Unit Test Coverage Report

Coverage Summary

Lines	Statements	Branches	Functions
	16.42% (4606/28038)	9.72% (2106/21646)	10.77% (664/6165)

Unit Test Results

Tests	Skipped	Failures	Errors	Time
1803	0 💤	0 ❌	0 🔥	23.966s ⏱️

[lucaseduoli]

LGTM

[github-actions]

Build successful! ✅
Deploying docs draft.
Deploy successful! View draft