From 5d232d45fb3251578259828704f190a2a892c7e4 Mon Sep 17 00:00:00 2001 From: bene-we <41572666+bene-we@users.noreply.github.com> Date: Fri, 26 Dec 2025 02:45:44 +0100 Subject: [PATCH] docs: add MCP OAuth Callback URL (#471) * docs: add OAuth callback URL details in MCP documentation * docs: update OAuth redirect URI examples in MCP servers documentation * docs: improve readability & formatting --- .../object_structure/mcp_servers.mdx | 10 +- pages/docs/features/mcp.mdx | 94 ++++++++++++++----- 2 files changed, 78 insertions(+), 26 deletions(-) diff --git a/pages/docs/configuration/librechat_yaml/object_structure/mcp_servers.mdx b/pages/docs/configuration/librechat_yaml/object_structure/mcp_servers.mdx index 28cef5a..685dfa2 100644 --- a/pages/docs/configuration/librechat_yaml/object_structure/mcp_servers.mdx +++ b/pages/docs/configuration/librechat_yaml/object_structure/mcp_servers.mdx @@ -58,7 +58,7 @@ mcpServers: token_url: https://example.com/oauth/token client_id: your_client_id client_secret: your_client_secret - redirect_uri: http://localhost:3080/oauth/callback + redirect_uri: http://localhost:3080/api/mcp/oauth-example/oauth/callback scope: "read execute" ``` @@ -284,7 +284,7 @@ mcpServers: - `token_url`: String - The OAuth token endpoint URL - `client_id`: String - OAuth client identifier - `client_secret`: String - OAuth client secret - - `redirect_uri`: String - OAuth redirect URI (eg. `http://localhost:3080/oauth/callback`) + - `redirect_uri`: String - [OAuth redirect URI](/docs/features/mcp#oauth-callback-url) (eg. `http://localhost:3080/api/mcp/${serverName}/oauth/callback`) - `scope`: String - OAuth scopes (space-separated) - **Optional Subkeys:** - `grant_types_supported`: Array of Strings - Supported grant types (defaults to `["authorization_code", "refresh_token"]`) @@ -293,12 +293,12 @@ mcpServers: - `code_challenge_methods_supported`: Array of Strings - Supported PKCE code challenge methods (defaults to `["S256", "plain"]`) - **Example:** ```yaml - oauth: + oauth-api-server: authorization_url: https://api.example.com/oauth/authorize token_url: https://api.example.com/oauth/token client_id: your_client_id client_secret: your_client_secret - redirect_uri: http://localhost:3080/oauth/callback + redirect_uri: http://localhost:3080/api/mcp/oauth-api-server/oauth/callback scope: "read execute" grant_types_supported: ["authorization_code", "refresh_token"] token_endpoint_auth_methods_supported: ["client_secret_post"] @@ -436,7 +436,7 @@ oauth-api-server: token_url: https://api.example.com/oauth/token client_id: your_client_id client_secret: your_client_secret - redirect_uri: http://localhost:3080/oauth/callback + redirect_uri: http://localhost:3080/api/mcp/oauth-api-server/oauth/callback scope: "read execute" ``` diff --git a/pages/docs/features/mcp.mdx b/pages/docs/features/mcp.mdx index 2eaf4ab..7bb9d63 100644 --- a/pages/docs/features/mcp.mdx +++ b/pages/docs/features/mcp.mdx @@ -20,7 +20,7 @@ LLMs are limited to their built-in capabilities. With MCP, LibreChat breaks down ## How MCP Works in LibreChat -LibreChat provides two ways to use MCP servers, either in the chat area or with agents. +LibreChat provides two ways to use MCP servers, either in the chat area or with agents. You can configure MCP servers manually in your `librechat.yaml` file or by using [smithery.ai](https://smithery.ai) to find and install MCP servers into `librechat.yaml` ([see example below](#basic-configuration)). Any time you add or edit an MCP server, you will need to restart LibreChat to initialize the connections. @@ -72,14 +72,14 @@ mcpServers: - -y - "@modelcontextprotocol/server-filesystem" - /path/to/your/documents - + # Web browser automation puppeteer: command: npx args: - -y - "@modelcontextprotocol/server-puppeteer" - + # Production-ready cloud service business-api: type: streamable-http @@ -96,26 +96,31 @@ mcpServers: Smithery.ai provides a streamlined way to discover and install MCP servers for LibreChat. Follow these steps to get started: #### Step 1: Search for MCP Servers + Visit [smithery.ai](https://smithery.ai) and search for the MCP server you want to add to your LibreChat instance. ![Smithery Search Interface](/images/mcp/mcp_smithery_search.png) #### Step 2: Select Your MCP Server + Click on the MCP server from the search results to view details and available tools. ![MCP Server Details Page](/images/mcp/mcp_smithery_mcp_server.png) #### Step 3: Configure for LibreChat + Navigate to the **Auto** tab in the **Connect** section and select **LibreChat** as your desired client. ![LibreChat Integration Setup](/images/mcp/mcp_smithery_librechat.png) #### Step 4: Install the MCP Server + Copy and run the generated command in your terminal to install the MCP server. ![Installation Command](/images/mcp/mcp_smithery_copy.png) #### Step 5: Restart and Verify + Your MCP server is now installed and configurable in `librechat.yaml`. Restart LibreChat to initialize the connections and start using your new MCP server. ![MCP Server Successfully Installed](/images/mcp/mcp_show_installed.png) @@ -123,6 +128,7 @@ Your MCP server is now installed and configurable in `librechat.yaml`. Restart L For detailed configuration options and examples, see: + - [MCP Servers Configuration](/docs/configuration/librechat_yaml/object_structure/mcp_servers) - [Agent Configuration](/docs/configuration/librechat_yaml/object_structure/agents) - [Advanced Agent Features](/docs/features/agents#model-context-protocol-mcp) @@ -138,10 +144,11 @@ LibreChat displays dynamic status icons showing the current state of each MCP se ![MCP Server Status Icons](/images/mcp/mcp_server_status_icons.png) **Status Types:** + - **Connected** (green gear): Server is connected and has configurable customUserVars - **OAuth Required** (amber key): Server requires OAuth authentication - **Disconnected** (orange plug): Server connection failed or lost -- **Initializing** (blue loader): Server is starting up or reconnecting +- **Initializing** (blue loader): Server is starting up or reconnecting - **Error** (red triangle): Server encountered an error - **Cancelling** (red x): OAuth flow is being cancelled @@ -150,6 +157,7 @@ LibreChat displays dynamic status icons showing the current state of each MCP se You can initialize or re-initialize MCP servers directly from the interface: **One click:** + - One-click initialization from the MCP server selection dropdown @@ -157,20 +165,23 @@ You can initialize or re-initialize MCP servers directly from the interface: muted controls > - - + + **From MCPConfigDialog:** + - Click the status icon next to an MCP server in the Chat Dropdown to open the MCPConfigDialog - Configure custom user variables and click the Authenticate/Initialize button depending on the server authentication type - -**From MCP Settings Panel:** + + + **From MCP Settings Panel:** + - Click any server in the server list section of MCP Settings Panel to access configuration and initialization controls - Configure custom user variables and click the Authenticate/Initialize button depending on the server authentication type @@ -178,9 +189,8 @@ You can initialize or re-initialize MCP servers directly from the interface: muted controls > - - - + + ### MCP Settings Panel Visibility @@ -190,17 +200,18 @@ The MCP Settings Panel appears in the right sidebar when LibreChat detects MCP s - **OAuth Authentication**: Server is detected as requiring OAuth authentication during startup - **Manual Initialization**: Server has `startup: false` configured, requiring manual initialization - ## LibreChat-Specific Features LibreChat's MCP implementation is designed for highly configurable, real-world, multi-user environments. ### User-Specific Connections + - Each user gets their own isolated connection to MCP servers - User authentication and permissions are respected - Personal data and context remain private ### Dynamic User Context + MCP servers can access user information through placeholders in **URLs and headers** (for SSE and Streamable HTTP transports): ```yaml @@ -216,6 +227,7 @@ mcpServers: ``` Available placeholders include: + - `{{LIBRECHAT_USER_ID}}` - Unique user identifier - `{{LIBRECHAT_USER_EMAIL}}` - User's email address - `{{LIBRECHAT_USER_ROLE}}` - User role (admin, user, etc.) @@ -239,6 +251,7 @@ mcpServers: ``` Options: + - `true`: Use server-provided instructions - `false`: Disable instructions - `string`: Custom instructions (shown above) @@ -276,21 +289,22 @@ mcpServers: ``` Users can configure these credentials: + - **From Chat Area**: Click the settings icon next to configurable MCP servers in the tool selection dropdown - **From MCP Settings Panel**: Access "MCP Settings" in the right panel to manage credentials for all configured servers - #### Reinitializing MCP Servers with User Credentials For MCP servers that require user-specific credentials before they can be used (e.g., `PAT_TOKEN`'s in [GitHub’s official MCP server](https://github.com/github/github-mcp-server)), LibreChat allows users to provide these credentials and then reinitialize the MCP server from within the UI without restarting the whole application: -1. When you select an MCP that uses `customUserVars`, you will be able to **Save** or **Revoke** a `customUserVar`'s value for the selected MCP server from within the MCP Panel. +1. When you select an MCP that uses `customUserVars`, you will be able to **Save** or **Revoke** a `customUserVar`'s value for the selected MCP server from within the MCP Panel. 2. After saving a value for a `customUserVar`, click the reinitialize button (an icon with circular arrows next to each server name in the MCP Panel). 3. LibreChat will attempt to connect to the server using your provided credentials and notify you with a toast whether the reinitialization process has succeeded or failed. > _Tip: If you know a server will require credentials not available at first startup, you can add `startup: false` to its configuration. This tells LibreChat to not attempt to connect to that server until it is manually reinitialized in the UI._ **Example:** + ```yaml mcpServers: github-mcp: @@ -312,6 +326,7 @@ LibreChat supports OAuth authentication for MCP servers, following Anthropic's r #### Supported OAuth Flows LibreChat MCP servers support OAuth 2.0 with: + - **Authorization Code Flow with PKCE**: Recommended for maximum security - **Client Discovery**: Automatic client registration when supported by the OAuth provider - **Refresh Tokens**: Automatic token renewal when available @@ -327,7 +342,7 @@ mcpServers: type: "sse" initTimeout: 150000 # higher timeout to allow for initial authentication url: "https://mcp.paypal.com/sse" - + # Example self-hosted remote MCP server for Spotify, uses OAuth Client Discovery # ✅ Refresh Tokens: refreshes token for authentication automatically # Hosted on Cloudflare Workers, more info: https://github.com/LibreChat-AI/spotify-mcp @@ -350,6 +365,39 @@ When you first configure an OAuth-enabled MCP server: 7. **Token Storage**: LibreChat securely stores the tokens for future use 8. **Connection Established**: Once you've authenticated, the MCP server will be connected and you can use it in your chat +#### OAuth Callback URL + +When an MCP server uses OAuth, LibreChat exposes a callback endpoint that the OAuth provider redirects to after successful authorization. + +The callback URL must follow this format: + +`${baseUrl}/api/mcp/${serverName}/oauth/callback` + +Where `${serverName}` is the MCP server key defined in your `librechat.yaml` configuration. LibreChat handles the redirect at this endpoint, completes the token exchange, and associates the credentials with the corresponding MCP server. + + +Given the following MCP server configuration: + +```yaml +mcpServers: + # Example self-hosted remote MCP server for Spotify, uses OAuth Client Discovery + # ✅ Refresh Tokens: refreshes token for authentication automatically + # Hosted on Cloudflare Workers, more info: https://github.com/LibreChat-AI/spotify-mcp + spotify: + type: 'streamable-http' + initTimeout: 150000 + url: 'https://mcp-spotify-oauth-example.account.workers.dev/mcp' +``` + + +The callback URL would be `${baseUrl}/api/mcp/spotify/oauth/callback`. + + +Note: + +- The callback URL must be registered exactly with the OAuth provider for the flow to work. +- Other paths such as `/api/oauth/callback` or `/api/oauth/openid/callback` are not valid for MCP OAuth flows. + #### Token Management LibreChat handles OAuth tokens intelligently: @@ -365,6 +413,7 @@ Each user will be prompted to authenticate with their own OAuth login when they > Note: The tokens shown during app startup are for app-level initialization only and are not used for individual user connections. Example of automatic token refresh: + ```bash [MCP][spotify] Access token missing [MCP][spotify] Attempting to refresh token @@ -386,13 +435,16 @@ Example of automatic token refresh: MCP servers can be configured to use different transport mechanisms: **STDIO Servers** + - Work wells for local, single-user environments - Not scalable for remote or cloud deployments **Server-Sent Events (SSE) Servers** + - Remote transport mechanism but not recommended for production environment **Streamable HTTP Servers** + - Uses HTTP POST for sending messages and supports streaming responses - Operates as an independent process that can handle multiple client connections - Supports both basic requests and streaming via Server-Sent Events (SSE) @@ -405,4 +457,4 @@ LibreChat is at the forefront of implementing flexible, scalable MCP server inte --- -**Ready to extend your AI capabilities?** Start by configuring your first MCP server and discover how LibreChat can connect to virtually any tool or service your organization needs. \ No newline at end of file +**Ready to extend your AI capabilities?** Start by configuring your first MCP server and discover how LibreChat can connect to virtually any tool or service your organization needs.