centersl/librechat.ai
1
0
Fork 0
mirror of https://github.com/LibreChat-AI/librechat.ai.git synced 2026-03-27 02:38:32 +07:00
Code Issues Packages Projects Releases Wiki Activity

docs: add MCP OAuth Callback URL (#471)

Browse Source 
* docs: add OAuth callback URL details in MCP documentation

* docs: update OAuth redirect URI examples in MCP servers documentation

* docs: improve readability & formatting
This commit is contained in:
bene-we
2025-12-26 02:45:44 +01:00
committed by GitHub
parent 5861e77975
commit 5d232d45fb
2 changed files with 78 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
pages/docs/configuration/librechat_yaml/object_structure/mcp_servers.mdx
View File

@@ -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"
```

94
pages/docs/features/mcp.mdx
View File

@@ -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
>
<source src="/videos/mcp_one_click_init.mp4" />
</video>
<source src="/videos/mcp_one_click_init.mp4" />
</video>
**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
<video
muted
controls
>
<source src="/videos/mcp_config_dialog_auth.mp4" />
</video>
**From MCP Settings Panel:**
<video
muted
controls
>
<source src="/videos/mcp_config_dialog_auth.mp4" />
</video>
**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
>
<source src="/videos/mcp_settings_init.mp4" />
</video>
<source src="/videos/mcp_settings_init.mp4" />
</video>
### 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.
<Callout type="info" title="OAuth Callback URL Example">
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`.
</Callout>
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.
**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.