# MCP Settings Object Structure (https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/mcp_settings) ## Overview The `mcpSettings` configuration provides global settings for MCP (Model Context Protocol) server security and behavior. This configuration is separate from `mcpServers` and controls how MCP servers can connect to certain domains and IP addresses. ## Example ```yaml filename="MCP Settings Object Structure" # Example MCP Settings Configuration mcpSettings: # Strict whitelist mode: # allowedDomains: # - "example.com" # Specific domain # - "*.example.com" # All subdomains using wildcard # - "https://api.example.com:8443" # With protocol and port # - "http://mcp-server:3000" # Internal service, explicitly whitelisted # Default SSRF mode with private service exemptions: allowedAddresses: - "host.docker.internal:8080" # Permit one private host on one port - "10.0.0.5:8000" # Permit one private IP on one port ``` ## Configuration ### Subkeys ## allowedDomains ### Security Context (SSRF Protection) LibreChat includes SSRF (Server-Side Request Forgery) protection with the following behavior: **When `allowedDomains` is NOT configured:** - SSRF-prone targets are **blocked by default** - All other external domains are **allowed** **When `allowedDomains` IS configured:** - **Only** domains on the list are allowed - Internal/SSRF targets can be allowed by explicitly adding them to the list **Blocked SSRF targets include:** - **Localhost** addresses (`localhost`, `127.0.0.1`, `::1`) - **Private IP ranges** (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`) - **Link-local addresses** (`169.254.0.0/16`, includes cloud metadata IPs) - **Internal TLDs** (`.internal`, `.local`, `.localhost`) - **Common internal service names** (`redis`, `mongodb`, `postgres`, `api`, `rag_api`, etc.) If your MCP servers need to connect to internal services or Docker containers, either add them to the strict `allowedDomains` whitelist, or leave `allowedDomains` unset and add the exact private service to `allowedAddresses`. ### Pattern Formats The `allowedDomains` array supports several pattern formats: 1. **Exact Domain Match** ```yaml allowedDomains: - "example.com" ``` Only allows connections to exactly `example.com` (any protocol/port) 2. **Wildcard Subdomain Match** ```yaml allowedDomains: - "*.example.com" ``` Allows connections to all subdomains of `example.com` (e.g., `api.example.com`, `mcp.example.com`) 3. **Specific IP Address** ```yaml allowedDomains: - "192.168.1.100" - "172.24.1.165" ``` Allows connections to specific IP addresses 4. **Local Docker Domains** ```yaml allowedDomains: - "mcp-server" - "host.docker.internal" ``` Allows connections to Docker container names or special Docker domains 5. **With Protocol and Port** ```yaml allowedDomains: - "https://api.example.com:8443" - "http://internal-mcp:3000" ``` Restricts connections to specific protocol and port combinations ### Error Messages If you see errors like: ```bash error: [MCPServersRegistry] Failed to inspect server "my-mcp": Domain "http://172.24.1.165:8000" is not allowed error: [MCP][my-mcp] Failed to initialize: Domain "http://172.24.1.165:8000" is not allowed ``` This likely indicates that the MCP server's private host and port need to be added to `allowedAddresses`, unless you intentionally use `allowedDomains` as a strict whitelist: ```yaml mcpSettings: allowedAddresses: - "172.24.1.165:8000" # Add the private host/IP and MCP port ``` ## allowedAddresses `allowedAddresses` is an **exemption list** for the SSRF private-IP block — not a domain whitelist. It is the right tool when you want to permit one or two specific private/internal services without restricting what your MCP servers can reach in the public internet. ### When to use it instead of `allowedDomains` `allowedDomains` is a strict whitelist: when it is set, **only** listed entries are reachable. Adding a private IP there to permit, say, a self-hosted MCP server also blocks every public destination (`api.example.com`, `*.googleapis.com`, etc.) that you didn't also list. `allowedAddresses` is used only when `allowedDomains` is not configured. It permits specific private `host:port` targets while leaving the rest of the public internet reachable through the default SSRF policy. Common configuration: ```yaml filename="default SSRF + permitted private host" mcpSettings: allowedAddresses: - "host.docker.internal:8080" - "10.0.0.5:8000" # allowedDomains is intentionally not set — public destinations # remain reachable, only listed private host:port services are exempted. ``` If `allowedDomains` is configured, it is authoritative: private services must be listed there instead of relying on `allowedAddresses`. ### Acceptable entries - **Hostnames with port**: `host.docker.internal:8080`, `mcp-server:3000`, `localhost:3001` - **Private IPv4 literals with port**: `10.0.0.5:8000`, `127.0.0.1:3001`, `192.168.1.10:443`, `169.254.169.254:80` - **Bracketed private IPv6 literals with port**: `[::1]:3001`, `[fc00::1]:8080`, `[fe80::1]:8080` ### Rejected entries (validated at config load) - **URLs / paths / CIDR ranges**: `http://10.0.0.5`, `10.0.0.0/24`, `/path` - **Bare hostnames or IPs**: `localhost`, `10.0.0.5`, `::1`, `[::1]` — every entry must include a port - **Invalid ports**: `localhost:0`, `localhost:65536`, `localhost:http` - **Public IP literals**: `8.8.8.8:53`, `1.1.1.1:53`, `[2001:4860::8888]:443` — the field is scoped to private IP space; public IPs are not SSRF targets and a public-IP exemption has no defensive purpose ### Hostname trust A hostname entry trusts whatever IP that hostname resolves to at runtime on the listed port. If the DNS for a listed hostname is rotated or hijacked to point at a different private IP, the exemption follows. Only list hostnames whose DNS you control. **Prefer literal IPs when you can.** ## References - [MCP Servers Configuration](/docs/configuration/librechat_yaml/object_structure/mcp_servers) - [MCP Features](/docs/features/mcp) - [Actions allowedAddresses](/docs/configuration/librechat_yaml/object_structure/actions#allowedaddresses) (similar concept for Actions)