MCP 설정 객체 구조

개요

mcpSettings 구성은 MCP (Model Context Protocol) 서버 보안 및 동작에 대한 전역 설정을 제공합니다. 이 구성은 mcpServers와는 별개이며, MCP 서버가 특정 도메인 및 IP 주소에 연결하는 방식을 제어합니다.

예시

# 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

구성

하위 키 (Subkeys)

Key	Type	Description	Example
allowedDomains	Array of Strings	MCP 서버 연결을 위해 허용된 도메인을 지정하는 목록입니다.	When configured, only listed domains are allowed. When not configured, SSRF targets are blocked but all other domains are allowed.
allowedAddresses	Array of Strings	사설 IP 대역으로 범위가 지정된 SSRF 예외 목록입니다. 여기에 나열된 호스트 이름/IP 및 포트 쌍은 `allowedDomains`가 구성되지 않은 경우 기본 거부 SSRF 차단을 우회합니다.	Use when you want default SSRF protection AND specific internal MCP servers, without flipping `allowedDomains` into strict-whitelist mode.

보안 컨텍스트 (SSRF 보호)

LibreChat은 다음과 같은 동작을 포함하는 SSRF(Server-Side Request Forgery) 보호 기능을 제공합니다:

allowedDomains가 구성되지 않은 경우:

SSRF에 취약한 대상은 기본적으로 차단됩니다
기타 모든 외부 도메인은 허용됩니다

allowedDomains가 구성된 경우:

목록에 있는 도메인만 허용됩니다
내부/SSRF 대상은 목록에 명시적으로 추가하여 허용할 수 있습니다.

차단된 SSRF 대상은 다음과 같습니다:

Localhost 주소(localhost, 127.0.0.1, ::1)
사설 IP 대역 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
링크 로컬 주소 (169.254.0.0/16, 클라우드 메타데이터 IP 포함)
내부 TLD (.internal, .local, .localhost)
일반적인 내부 서비스 이름 (redis, mongodb, postgres, api, rag_api 등)

MCP 서버가 내부 서비스나 Docker 컨테이너에 연결해야 하는 경우, 엄격한 allowedDomains 화이트리스트에 해당 도메인을 추가하거나, allowedDomains를 설정하지 않은 상태로 두고 allowedAddresses에 정확한 사설 서비스를 추가하세요.

패턴 형식

allowedDomains 배열은 여러 패턴 형식을 지원합니다:

정확한 도메인 일치
```
allowedDomains:
  - "example.com"
```
example.com과 정확히 일치하는 연결만 허용합니다 (모든 프로토콜/포트).
와일드카드 서브도메인 일치
```
allowedDomains:
  - "*.example.com"
```
example.com의 모든 하위 도메인(예: api.example.com, mcp.example.com)에 대한 연결을 허용합니다.
특정 IP 주소
```
allowedDomains:
  - "192.168.1.100"
  - "172.24.1.165"
```
특정 IP 주소에 대한 연결을 허용합니다
로컬 Docker 도메인
```
allowedDomains:
  - "mcp-server"
  - "host.docker.internal"
```
Docker 컨테이너 이름이나 특수 Docker 도메인에 대한 연결을 허용합니다
프로토콜 및 포트 포함
```
allowedDomains:
  - "https://api.example.com:8443"
  - "http://internal-mcp:3000"
```
특정 프로토콜 및 포트 조합에 대한 연결을 제한합니다

오류 메시지

다음과 같은 오류가 표시되는 경우:

  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

이는 allowedDomains를 엄격한 화이트리스트로 의도적으로 사용하는 경우가 아니라면, MCP 서버의 비공개 호스트와 포트를 allowedAddresses에 추가해야 함을 의미할 가능성이 높습니다:

mcpSettings:
  allowedAddresses:
    - "172.24.1.165:8000"    # Add the private host/IP and MCP port

allowedAddresses

allowedAddresses는 SSRF 사설 IP 차단에 대한 예외 목록이며, 도메인 허용 목록이 아닙니다. 이 설정은 MCP 서버가 공용 인터넷에서 접근할 수 있는 범위를 제한하지 않으면서, 특정 사설/내부 서비스 한두 곳에 대한 접근을 허용하고자 할 때 적합한 도구입니다.

`allowedDomains` 대신 사용하는 경우

allowedDomains는 엄격한 화이트리스트입니다. 설정 시 목록에 있는 항목만 접근할 수 있습니다. 예를 들어, 자체 호스팅된 MCP 서버를 허용하기 위해 사설 IP를 추가하면, 목록에 포함하지 않은 모든 공용 대상(api.example.com, *.googleapis.com 등)도 차단됩니다.

allowedAddresses는 allowedDomains가 구성되지 않은 경우에만 사용됩니다. 이는 특정 사설 host:port 대상을 허용하면서, 나머지 공용 인터넷은 기본 SSRF 정책을 통해 접근할 수 있도록 유지합니다. 일반적인 구성은 다음과 같습니다:

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.

allowedDomains가 구성되어 있다면, 해당 설정이 우선합니다: 비공개 서비스는 allowedAddresses에 의존하는 대신 반드시 해당 목록에 명시되어야 합니다.

허용되는 항목

포트가 포함된 호스트 이름: host.docker.internal:8080, mcp-server:3000, localhost:3001
포트가 포함된 사설 IPv4 리터럴: 10.0.0.5:8000, 127.0.0.1:3001, 192.168.1.10:443, 169.254.169.254:80
포트가 포함된 대괄호로 묶인 사설 IPv6 리터럴: [::1]:3001, [fc00::1]:8080, [fe80::1]:8080

거부된 항목 (설정 로드 시 유효성 검사됨)

URL / 경로 / CIDR 범위: http://10.0.0.5, 10.0.0.0/24, /path
Bare hostnames or IPs: localhost, 10.0.0.5, ::1, [::1] — 모든 항목에는 포트가 포함되어야 합니다.
유효하지 않은 포트: localhost:0, localhost:65536, localhost:http
공용 IP 리터럴: 8.8.8.8:53, 1.1.1.1:53, [2001:4860::8888]:443 — 이 필드는 사설 IP 대역으로 범위가 제한됩니다. 공용 IP는 SSRF 대상이 아니며, 공용 IP 예외 처리는 방어적 목적을 갖지 않습니다.

Hostname trust

호스트 이름 항목은 런타임 시 해당 호스트 이름이 지정된 포트에서 확인되는 모든 IP를 신뢰합니다. 나열된 호스트 이름의 DNS가 순환되거나 하이재킹되어 다른 사설 IP를 가리키게 되면, 예외 사항도 이를 따르게 됩니다. 본인이 DNS를 제어하는 호스트 이름만 나열하십시오. 가능한 경우 리터럴 IP를 사용하는 것을 권장합니다.

참고 자료

MCP Servers 구성
MCP 기능
Actions allowedAddresses (Actions에 대한 유사한 개념)