🧭 docs: Document Port-Scoped allowedAddresses (#573)

Author: danny-avila

content/changelog/config_v1.3.10.mdx

@@ -0,0 +1,19 @@
+---
+date: 2026-05-08
+title: ⚙️ Config v1.3.10
+version: '1.3.10'
+---
+
+- Changed `allowedAddresses` entries to require an explicit port
+  - Applies to `actions.allowedAddresses`, `mcpSettings.allowedAddresses`, and `endpoints.allowedAddresses`
+  - Entries must use `host:port`, `private.ip:port`, or `[ipv6]:port`
+  - Bare hosts and IPs such as `localhost`, `127.0.0.1`, and `host.docker.internal` are rejected
+  - This scopes each SSRF exemption to one intended private service instead of every port on the same host
+
+- Preserved private-IP scoping for `allowedAddresses`
+  - URLs, paths, CIDR ranges, whitespace, invalid ports, and public IP literals remain invalid
+  - Hostname entries still trust whatever private IP that hostname resolves to on the listed port
+
+- Clarified how `allowedAddresses` interacts with `allowedDomains`
+  - `allowedAddresses` is used when `allowedDomains` is not configured
+  - When `allowedDomains` is configured, it acts as the authoritative strict whitelist

content/docs/configuration/librechat_yaml/object_structure/actions.mdx

@@ -12,14 +12,17 @@ More info: [Agents - Actions](/docs/features/agents#actions)
 ```yaml filename="Actions Object Structure"
 # Example Actions Object Structure
 actions:
-  allowedDomains:
-    - "swapi.dev"
-    - "librechat.ai"
-    - "google.com"
-    - "https://api.example.com:8443"  # With protocol and port
+  # Strict whitelist mode:
+  # allowedDomains:
+  #   - "swapi.dev"
+  #   - "librechat.ai"
+  #   - "google.com"
+  #   - "https://api.example.com:8443"  # With protocol and port
+
+  # Default SSRF mode with private service exemptions:
   allowedAddresses:
-    - "host.docker.internal"          # Permit one private host
-    - "10.0.0.5"                      # Permit one private IP
+    - "host.docker.internal:11434"    # Permit one private host on one port
+    - "10.0.0.5:8080"                 # Permit one private IP on one port
 ```
 
 ## allowedDomains
@@ -52,7 +55,7 @@ LibreChat includes SSRF (Server-Side Request Forgery) protection with the follow
 - **Internal TLDs** (`.internal`, `.local`, `.localhost`)
 - **Common internal service names** (`redis`, `mongodb`, `postgres`, `api`, etc.)
 
-If your actions need to access internal services, you **must explicitly add them** to `allowedDomains`.
+If your actions need to access internal services, either add them to the strict `allowedDomains` whitelist, or leave `allowedDomains` unset and add the exact private service to `allowedAddresses`.
 
 ### Pattern Formats
 
@@ -95,37 +98,38 @@ allowedDomains:
 
 ## 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 hosts without restricting what your Actions can reach in the public internet.
+`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 Actions 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 internal API also blocks every public action endpoint that you didn't also list.
 
-`allowedAddresses` is orthogonal: it permits specific private targets while leaving the rest of the public internet reachable through the default SSRF policy.
+`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.
 
 ```yaml filename="default SSRF + permitted private host"
 actions:
   allowedAddresses:
-    - "host.docker.internal"
-    - "10.0.0.5"
+    - "host.docker.internal:11434"
+    - "10.0.0.5:8080"
   # allowedDomains is intentionally not set — public destinations
-  # remain reachable, only listed private hosts are exempted.
+  # remain reachable, only listed private host:port services are exempted.
 ```
 
-You can also combine both: use `allowedDomains` as your strict whitelist and `allowedAddresses` to permit specific private hosts not covered by the domain rules.
+If `allowedDomains` is configured, it is authoritative: private services must be listed there instead of relying on `allowedAddresses`.
 
 ### Acceptable entries
 
-- **Bare hostnames**: `host.docker.internal`, `ollama.internal`, `localhost`
-- **Private IPv4 literals**: `10.0.0.5`, `127.0.0.1`, `192.168.1.10`, `169.254.169.254`
-- **Private IPv6 literals**: `::1`, `fc00::1`, `fe80::1`, `[::1]` (brackets are stripped)
+- **Hostnames with port**: `host.docker.internal:11434`, `ollama.internal:8080`, `localhost:11434`
+- **Private IPv4 literals with port**: `10.0.0.5:8080`, `127.0.0.1:11434`, `192.168.1.10:443`, `169.254.169.254:80`
+- **Bracketed private IPv6 literals with port**: `[::1]:11434`, `[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`
-- **Host with port**: `localhost:8080`, `[::1]:8080` — list the bare hostname or IP only
-- **Public IP literals**: `8.8.8.8`, `1.1.1.1`, `2001:4860::` — the field is scoped to private IP space; public IPs are not SSRF targets and a public-IP exemption has no defensive purpose
+- **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. 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.**
+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.**

content/docs/configuration/librechat_yaml/object_structure/config.mdx

@@ -10,7 +10,7 @@ icon: Settings
 
 <OptionTable
   options={[
-    ['version', 'String', 'Specifies the version of the configuration file.', 'version: 1.3.9' ],
+    ['version', 'String', 'Specifies the version of the configuration file.', 'version: 1.3.10' ],
   ]}
 />
 
@@ -441,7 +441,7 @@ see: [Summarization Object Structure](/docs/configuration/librechat_yaml/object_
 <OptionTable
   options={[
     ['allowedDomains', 'Array of Strings', 'Strict whitelist of domains for actions. When set, only listed domains are reachable.', ''],
-    ['allowedAddresses', 'Array of Strings', 'SSRF exemption list (private IP space only). Permits specific private hosts without restricting public destinations.', ''],
+    ['allowedAddresses', 'Array of Strings', 'SSRF exemption list (private IP space only). Permits specific private host:port services without restricting public destinations when `allowedDomains` is not configured.', ''],
   ]}
 />
 
@@ -526,13 +526,13 @@ see: [Model Specs Object Structure](/docs/configuration/librechat_yaml/object_st
     ['azureAssistants', 'Object', 'Azure Assistants endpoint-specific configuration.', ''],
     ['agents', 'Object', 'Agents endpoint-specific configuration.', ''],
     ['all', 'Object', 'Global endpoint settings that apply to all endpoints. See Shared Endpoint Settings.', ''],
-    ['allowedAddresses', 'Array of Strings', 'SSRF exemption list (private IP space only). Permits user-provided baseURLs to point at specific private hosts (e.g. self-hosted Ollama) without disabling SSRF protection for everything else.', ''],
+    ['allowedAddresses', 'Array of Strings', 'SSRF exemption list (private IP space only). Permits user-provided baseURLs to point at specific private host:port services (e.g. self-hosted Ollama) without disabling SSRF protection for everything else.', ''],
   ]}
 />
 
 > **Note:** All endpoints support [Shared Endpoint Settings](/docs/configuration/librechat_yaml/object_structure/shared_endpoint_settings) which include `streamRate`, `titleModel`, `titleMethod`, `titlePrompt`, `titlePromptTemplate`, `titleEndpoint`, and `maxToolResultChars`. These can be configured individually per endpoint or globally using the `all` key. The `all` key does not accept `baseURL`.
 
-> **Note:** `endpoints.allowedAddresses` applies to user-provided `baseURL` values (when an admin configures a custom endpoint with `apiKey: 'user_provided'` and `baseURL: 'user_provided'`). Each user-supplied baseURL is validated against the SSRF block at request time; entries listed here are exempted. See [`mcpSettings.allowedAddresses`](/docs/configuration/librechat_yaml/object_structure/mcp_settings#allowedaddresses) for the field semantics — same rules apply (private IP space only, no URLs/CIDR/ports).
+> **Note:** `endpoints.allowedAddresses` applies to user-provided `baseURL` values (when an admin configures a custom endpoint with `apiKey: 'user_provided'` and `baseURL: 'user_provided'`). Each user-supplied baseURL is validated against the SSRF block at request time; entries listed here are exempted. See [`mcpSettings.allowedAddresses`](/docs/configuration/librechat_yaml/object_structure/mcp_settings#allowedaddresses) for the field semantics — same rules apply (private IP space only, port required, no URLs/paths/CIDR/bare hosts/public IP literals).
 
 ## mcpSettings
 
@@ -547,29 +547,31 @@ see: [Model Specs Object Structure](/docs/configuration/librechat_yaml/object_st
 <OptionTable
   options={[
     ['allowedDomains', 'Array of Strings', 'Strict whitelist of domains for MCP server connections. When set, only listed entries are reachable.', ''],
-    ['allowedAddresses', 'Array of Strings', 'SSRF exemption list (private IP space only). Permits specific private hosts without flipping `allowedDomains` into strict-whitelist mode.', ''],
+    ['allowedAddresses', 'Array of Strings', 'SSRF exemption list (private IP space only). Permits specific private host:port services without flipping `allowedDomains` into strict-whitelist mode.', ''],
   ]}
 />
 
 - **Notes**:
   - This is a security feature to protect against abuse / misuse of internal addresses via MCP servers
   - By default, LibreChat restricts MCP servers from connecting to internal, local, or private network addresses
-  - MCP servers using local IP addresses or domains can either be added to the strict `allowedDomains` whitelist (which then becomes the only reachable set), or — to keep public destinations reachable — exempted via `allowedAddresses`
+  - MCP servers using local IP addresses or domains can either be added to the strict `allowedDomains` whitelist (which then becomes the only reachable set), or — to keep public destinations reachable — exempted as exact host:port services via `allowedAddresses`
   - As with all yaml configuration changes, a LibreChat restart is required to take effect
   - Supports domains, wildcard subdomains (`*.example.com`), docker domains, and IP addresses
 
 **Example:**
 
 ```yaml filename="mcpSettings"
 mcpSettings:
-  allowedDomains:
-    - "example.com"           # Specific domain
-    - "*.example.com"         # All subdomains
-    - "mcp-server"            # Local Docker domain
-    - "172.24.1.165"          # Internal network IP
+  # Strict whitelist mode:
+  # allowedDomains:
+  #   - "example.com"           # Specific domain
+  #   - "*.example.com"         # All subdomains
+  #   - "http://mcp-server:3000" # Internal service, explicitly whitelisted
+
+  # Default SSRF mode with private service exemptions:
   allowedAddresses:
-    - "host.docker.internal"  # Permit a single private host
-    - "10.0.0.5"              # Permit a single private IP
+    - "host.docker.internal:8080"  # Permit one private host on one port
+    - "10.0.0.5:8000"             # Permit one private IP on one port
 ```
 
 see: [MCP Settings Object Structure](/docs/configuration/librechat_yaml/object_structure/mcp_settings)

content/docs/configuration/librechat_yaml/object_structure/mcp_servers.mdx

@@ -403,22 +403,22 @@ mcpServers:
   - **`sse`**: Connects to an external MCP server via Server-Sent Events (SSE).
   - **`streamable-http`**: Connects to an external MCP server via HTTP with support for streaming responses.
 - **Internal/Local Addresses:**
-  - **Important**: MCP servers using internal IP addresses (e.g., `172.24.1.165`, `192.168.1.100`), or local domains (e.g., `mcp-server`, `host.docker.internal`) **must** be explicitly allowed in [`mcpSettings.allowedDomains`](/docs/configuration/librechat_yaml/object_structure/mcp_settings).
+  - **Important**: MCP servers using internal IP addresses (e.g., `172.24.1.165`, `192.168.1.100`), or local domains (e.g., `mcp-server`, `host.docker.internal`) **must** be explicitly allowed. Use [`mcpSettings.allowedAddresses`](/docs/configuration/librechat_yaml/object_structure/mcp_settings#allowedaddresses) for exact private host:port services when you want public destinations to remain reachable, or [`mcpSettings.allowedDomains`](/docs/configuration/librechat_yaml/object_structure/mcp_settings#alloweddomains) when you want a strict whitelist.
   - See [MCP Settings](/docs/configuration/librechat_yaml/object_structure/mcp_settings) for configuration details.
 
 ## Examples
 
 ### Configuration with Internal Addresses
 
-When using internal/local MCP servers, you must configure `mcpSettings.allowedDomains`:
+When using internal/local MCP servers and no strict domain whitelist is needed, configure `mcpSettings.allowedAddresses` with the exact host and port:
 
 ```yaml filename="Complete MCP Configuration with Internal Servers"
 # MCP Settings - Required for internal/local addresses
 mcpSettings:
-  allowedDomains:
-    - "172.24.1.165"          # Internal IP
-    - "mcp-prod"              # Docker container
-    - "host.docker.internal"  # Docker host
+  allowedAddresses:
+    - "172.24.1.165:8000"         # Internal IP and port
+    - "mcp-prod:8001"             # Docker container and port
+    - "host.docker.internal:8080" # Docker host and port
 
 # MCP Servers - Individual configurations
 mcpServers: