MCP Servers - LibreChat

Overview

The MCP (Model Context Protocol) Servers API allows you to manage server integrations that provide additional tools and capabilities to AI agents. All MCP endpoints are prefixed with /api/mcp.

List MCP Servers

Retrieve accessible MCP servers:

GET /api/mcp/servers?limit=25&after=cursor_abc
Authorization: Bearer <token>

Query Parameters

limit

number

default:"25"

Maximum number of servers to return

after

string

Cursor for pagination

string

Search query for title/description

Response

{
  "data": [
    {
      "name": "github-mcp",
      "title": "GitHub MCP Server",
      "description": "Access GitHub repositories and issues",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      },
      "author": "user123",
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ],
  "has_more": false
}

Get MCP Server

Retrieve a specific MCP server configuration:

GET /api/mcp/servers/:serverName
Authorization: Bearer <token>

Path Parameters

serverName

string

required

MCP server name/identifier

Response

name

string

Unique server identifier

title

string

Display title

description

string

Server description

command

string

Command to execute (e.g., node, python, npx)

args

string[]

Command line arguments

env

object

Environment variables (values may reference user-provided vars)

author

string

User ID of creator

oauth

object

OAuth configuration (if applicable)

{
  "name": "github-mcp",
  "title": "GitHub MCP Server",
  "description": "Access GitHub repositories, issues, and pull requests",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {
    "GITHUB_TOKEN": "${GITHUB_TOKEN}"
  },
  "customUserVars": {
    "GITHUB_TOKEN": "GitHub Personal Access Token"
  },
  "author": "user123",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-16T09:00:00Z"
}

Create MCP Server

Create a new MCP server configuration:

POST /api/mcp/servers
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "my-custom-mcp",
  "title": "My Custom MCP",
  "description": "Custom MCP server for special tools",
  "command": "node",
  "args": ["/path/to/server.js"],
  "env": {
    "API_KEY": "${MY_API_KEY}"
  }
}

Request Body

name

string

required

Unique server identifier (lowercase, alphanumeric, hyphens)

title

string

required

Display title

description

string

Server description

command

string

required

Command to execute (e.g., node, python, npx)

args

string[]

required

Command line arguments

env

object

Environment variables (can reference $)

customUserVars

object

User-provided variables with descriptions

Response

Returns the created MCP server configuration with HTTP status 201.

Update MCP Server

Update an existing MCP server:

PATCH /api/mcp/servers/:serverName
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Updated Title",
  "description": "Updated description"
}

Path Parameters

serverName

string

required

MCP server identifier

Request Body

All fields are optional. Only include fields to update. Requires EDIT permission on the MCP server.

Delete MCP Server

Delete an MCP server:

DELETE /api/mcp/servers/:serverName
Authorization: Bearer <token>

Path Parameters

serverName

string

required

MCP server identifier to delete

Response

{
  "success": true,
  "message": "MCP server deleted successfully"
}

Requires DELETE permission on the MCP server.

Get MCP Tools

Retrieve all available MCP tools for the user:

GET /api/mcp/tools
Authorization: Bearer <token>

Response

Returns an array of tools from all connected MCP servers:

[
  {
    "name": "github_create_issue",
    "description": "Create a new GitHub issue",
    "inputSchema": {
      "type": "object",
      "properties": {
        "repo": {"type": "string"},
        "title": {"type": "string"},
        "body": {"type": "string"}
      },
      "required": ["repo", "title"]
    },
    "serverName": "github-mcp"
  }
]

Reinitialize MCP Server

Reconnect to an MCP server:

POST /api/mcp/:serverName/reinitialize
Authorization: Bearer <token>

Path Parameters

serverName

string

required

MCP server to reinitialize

Response

success

boolean

Whether reinitialization succeeded

message

string

Status message

oauthRequired

boolean

Whether OAuth authentication is required

oauthUrl

string

OAuth authorization URL (if required)

{
  "success": true,
  "message": "MCP server reinitialized successfully",
  "serverName": "github-mcp",
  "oauthRequired": false
}

Or if OAuth is required:

{
  "success": false,
  "message": "OAuth authentication required",
  "serverName": "github-mcp",
  "oauthRequired": true,
  "oauthUrl": "https://github.com/login/oauth/authorize?client_id=..."
}

Connection Status

Get connection status for all MCP servers:

GET /api/mcp/connection/status
Authorization: Bearer <token>

Response

{
  "success": true,
  "connectionStatus": {
    "github-mcp": {
      "connectionState": "connected",
      "requiresOAuth": true,
      "error": null
    },
    "filesystem-mcp": {
      "connectionState": "disconnected",
      "requiresOAuth": false,
      "error": "Connection timeout"
    }
  }
}

Connection States

connected: Server is connected and ready
disconnected: Server is not connected
error: Connection error occurred
connecting: Connection in progress

Get Single Server Status

Get connection status for a specific server:

GET /api/mcp/connection/status/:serverName
Authorization: Bearer <token>

Path Parameters

serverName

string

required

MCP server name

Response

{
  "success": true,
  "serverName": "github-mcp",
  "connectionStatus": "connected",
  "requiresOAuth": true
}

Check Auth Values

Check which authentication values are configured:

GET /api/mcp/:serverName/auth-values
Authorization: Bearer <token>

Path Parameters

serverName

string

required

MCP server name

Response

Returns boolean flags (not actual values):

{
  "success": true,
  "serverName": "github-mcp",
  "authValueFlags": {
    "GITHUB_TOKEN": true,
    "GITHUB_ORG": false
  }
}

OAuth Flow

Bind OAuth Flow

Set CSRF cookie before OAuth redirect:

POST /api/mcp/:serverName/oauth/bind
Authorization: Bearer <token>

Initiate OAuth

Start OAuth flow:

GET /api/mcp/:serverName/oauth/initiate?userId=user123&flowId=flow_abc
Authorization: Bearer <token>

Redirects to OAuth provider.

OAuth Callback

OAuth callback endpoint (handled automatically):

GET /api/mcp/:serverName/oauth/callback?code=abc&state=xyz

Redirects to success page after completion.

Cancel OAuth

Cancel pending OAuth flow:

POST /api/mcp/oauth/cancel/:serverName
Authorization: Bearer <token>

Popular MCP Servers

GitHub

{
  "name": "github",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {
    "GITHUB_TOKEN": "${GITHUB_TOKEN}"
  }
}

Filesystem

{
  "name": "filesystem",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
  "env": {}
}

Google Drive

{
  "name": "gdrive",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-gdrive"],
  "oauth": {
    "provider": "google",
    "scopes": ["https://www.googleapis.com/auth/drive.readonly"]
  }
}

Error Responses

Server Not Found

{
  "error": "MCP server 'server-name' not found in configuration"
}

HTTP Status: 404

Connection Failed

{
  "error": "Failed to connect to MCP server",
  "serverName": "github-mcp",
  "details": "Connection timeout"
}

HTTP Status: 500

OAuth Required

{
  "error": "OAuth authentication required",
  "oauthUrl": "https://..."
}

HTTP Status: 401

Permissions

MCP server access is controlled by permissions:

VIEW: Can view server configuration
EDIT: Can modify server configuration
DELETE: Can delete server
USE: Can use server tools in conversations

Best Practices

Use environment variables for sensitive data (API keys, tokens)
Test connections after creating/updating servers
Monitor server status to detect connection issues
Use OAuth when possible for better security
Document custom variables with clear descriptions
Set appropriate permissions to control server access
Handle disconnections gracefully in your application

Documentation Index

​Overview

​List MCP Servers

​Query Parameters

​Response

​Get MCP Server

​Path Parameters

​Response

​Create MCP Server

​Request Body

​Response

​Update MCP Server

​Path Parameters

​Request Body

​Delete MCP Server

​Path Parameters

​Response

​Get MCP Tools

​Response

​Reinitialize MCP Server

​Path Parameters

​Response

​Connection Status

​Response

​Connection States

​Get Single Server Status

​Path Parameters

​Response

​Check Auth Values

​Path Parameters

​Response

​OAuth Flow

​Bind OAuth Flow

​Initiate OAuth

​OAuth Callback

​Cancel OAuth

​Popular MCP Servers

​GitHub

​Filesystem

​Google Drive

​Error Responses

​Server Not Found

​Connection Failed

​OAuth Required

​Permissions

​Best Practices

Overview

List MCP Servers

Query Parameters

Response

Get MCP Server

Path Parameters

Response

Create MCP Server

Request Body

Response

Update MCP Server

Path Parameters

Request Body

Delete MCP Server

Path Parameters

Response

Get MCP Tools

Response

Reinitialize MCP Server

Path Parameters

Response

Connection Status

Response

Connection States

Get Single Server Status

Path Parameters

Response

Check Auth Values

Path Parameters

Response

OAuth Flow

Bind OAuth Flow

Initiate OAuth

OAuth Callback

Cancel OAuth

Popular MCP Servers

GitHub

Filesystem

Google Drive

Error Responses

Server Not Found

Connection Failed

OAuth Required

Permissions

Best Practices