MCP 서버 객체 구조

예시

# Example MCP Servers Object Structure
mcpServers:
  everything:
    # type: sse # type can optionally be omitted
    url: http://localhost:3001/sse
  googlesheets:
    type: sse
    url: https://mcp.composio.dev/googlesheets/some-endpoint
    requiresOAuth: true
    headers:
      X-User-ID: '{{LIBRECHAT_USER_ID}}'
      X-API-Key: '${SOME_API_KEY}'
    serverInstructions: true # Use server-provided instructions
  puppeteer:
    type: stdio
    command: npx
    args:
      - -y
      - '@modelcontextprotocol/server-puppeteer'
    serverInstructions: 'Do not access any local files or local/internal IP addresses'
  filesystem:
    # type: stdio
    command: npx
    args:
      - -y
      - '@modelcontextprotocol/server-filesystem'
      - /home/user/LibreChat/
    iconPath: /home/user/LibreChat/client/public/assets/logo.svg
    # The “wrench” icon shows up if no icon is provided as it is the default rendering.
  mcp-obsidian:
    command: npx
    args:
      - -y
      - 'mcp-obsidian'
      - /path/to/obsidian/vault
  streamable-http-server:
    type: streamable-http
    url: https://example.com/api/
    proxy: '${MCP_PROXY_URL}'
  per-user-credentials-example:
    type: streamable-http
    url: 'https://example.com/api/'
    headers:
      X-Auth-Token: '{{MY_SERVICE_API_KEY}}'
    customUserVars:
      MY_SERVICE_API_KEY:
        title: 'My Service API Key'
        description: "Enter your personal API key for the service. You can generate one at <a href='https://myservice.example.com/developer/keys' target='_blank'>Service Developer Portal</a>."
        sensitive: true
      MY_SERVICE_PROJECT:
        title: 'Project ID'
        description: 'Enter the project ID used by this service.'
        sensitive: false
  oauth-example:
    type: streamable-http
    url: https://api.example.com/mcp/
    oauth:
      authorization_url: https://example.com/oauth/authorize
      token_url: https://example.com/oauth/token
      client_id: your_client_id
      client_secret: your_client_secret
      redirect_uri: http://localhost:3080/api/mcp/oauth-example/oauth/callback
      scope: 'read execute'
  obo-example:
    type: streamable-http
    url: https://api.example.com/mcp/
    obo:
      scopes: 'api://mcp-server-id/Mcp.Tools.ReadWrite'

<serverName>

키:

하위 키 (Subkeys)

title

• 유형: 문자열 (선택 사항)
• 설명: UI에서 MCP 서버에 표시될 사용자 지정 이름입니다. 지정하지 않으면 서버 키 이름이 사용됩니다.
• 예시:

  my-server:
    title: 'File System Access'
    command: npx
    args: ['-y', '@modelcontextprotocol/server-filesystem']

description

• 유형: 문자열 (선택 사항)
• Description: MCP 서버에 대한 설명으로, 사용자가 해당 서버의 목적과 기능을 이해할 수 있도록 UI에 표시됩니다.
• 예시:

  my-server:
    title: 'File System Access'
    description: 'Provides read/write access to local files and directories'
    command: npx
    args: ['-y', '@modelcontextprotocol/server-filesystem']

type

• 유형: String
• 설명: MCP 서버에 대한 연결 유형을 지정합니다. 유효한 옵션은 "stdio", "websocket", "streamable-http" 또는 "sse"입니다.
• 기본값: url 또는 command의 존재 여부와 형식에 따라 결정됩니다.

command

• 유형: String
• 설명: (stdio 유형의 경우) MCP 서버를 시작하기 위해 실행할 명령어 또는 실행 파일입니다.

args

• 유형: 문자열 배열
• 설명: (stdio 유형의 경우) command에 전달할 명령줄 인수입니다.

url

• 유형: String
• 설명: (websocket, streamable-http 또는 sse 유형의 경우) MCP 서버에 연결하기 위한 URL입니다. 동적 사용자 필드 플레이스홀더({{LIBRECHAT_USER_*}}) 및 환경 변수 치환(${ENV_VAR})을 지원합니다.
• 참고:
  • sse 유형의 경우, URL은 http:// 또는 https://로 시작해야 합니다.
  • streamable-http 유형의 경우, URL은 반드시 http:// 또는 https://로 시작해야 합니다.
  • websocket 유형의 경우, URL은 ws:// 또는 wss://로 시작해야 합니다.

proxy

• 유형: 문자열 (선택 사항, sse 및 streamable-http 유형의 경우)
• 설명: 이 원격 MCP 서버를 위한 아웃바운드 프록시 URL입니다. 값은 ${ENV_VAR}을 사용하여 환경 변수를 참조할 수 있습니다.
• 지원되는 프로토콜: http://, https://, socks://, 및 socks5://
• 보안 참고: proxy는 관리자가 제어합니다. 환경 변수는 해석하지만, {{LIBRECHAT_USER_ID}}나 customUserVars와 같이 사용자가 제어하는 플레이스홀더는 해석하지 않습니다.
• 예시:

  mcpServers:
    remote-api:
      type: streamable-http
      url: https://api.example.com/mcp
      proxy: '${MCP_PROXY_URL}'

headers

• 유형: Object (선택 사항, sse 및 streamable-http 유형의 경우)
• 설명: 요청과 함께 전송할 사용자 지정 헤더입니다. 동적 값 대체를 위한 다양한 플레이스홀더 유형을 지원합니다.
• Placeholder 지원:
  • {{LIBRECHAT_USER_ID}}: 현재 사용자의 ID로 대체되어 다중 사용자 지원을 활성화합니다.
  • {{LIBRECHAT_USER_*}}: 동적 사용자 필드 플레이스홀더입니다. *를 허용된 필드의 대문자 버전으로 바꾸십시오.
  • {{LIBRECHAT_OPENID_*}}: YAML로 정의된 서버를 위한 OpenID 토큰/세션 플레이스홀더입니다.
  • {{LIBRECHAT_GRAPH_*}}: YAML로 정의된 서버를 위한 Microsoft Graph 토큰 플레이스홀더입니다.
  • {{LIBRECHAT_BODY_*}}: YAML로 정의된 서버를 위한 요청 본문(request body) 플레이스홀더로, 현재의 conversationId, parentMessageId 또는 messageId 등이 포함됩니다.
  • {{CUSTOM_VARIABLE_NAME}}: customUserVars에 정의된 변수에 대해 사용자가 제공한 값으로 대체됩니다 (예: {{MY_API_KEY}}).
  • ${ENV_VAR}: {{ENV_VAR}} 환경 변수의 값으로 대체됩니다.

사용 가능한 사용자 필드 플레이스홀더:

참고: 누락된 필드는 빈 문자열로 대체됩니다.

{{LIBRECHAT_BODY_*}} 플레이스홀더는 요청 범위(request-scoped)로 지정됩니다. LibreChat은 활성 실행(active run)을 위해 MCP 연결을 생성하고, 해당 실행 내의 도구 호출 전반에서 이를 재사용하며, 요청이 종료되면 연결을 정리합니다. 요청 범위 서버는 영구 도구 캐시에서 제외되므로, 요청별 헤더와 URL이 활성 실행 외부에서 재사용되지 않습니다. {{LIBRECHAT_USER_*}}, {{LIBRECHAT_OPENID_*}}, 그리고 {{LIBRECHAT_GRAPH_*}} 플레이스홀더는 여전히 서버를 사용자 범위(user-scoped)로 만들지만, HTTP 전송은 각 도구 호출 전에 확인된 헤더를 새로 고치며, 자체적으로 재연결을 강제하지는 않습니다.

• 예시:

  headers:
    X-User-ID: '{{LIBRECHAT_USER_ID}}'
    X-User-Email: '{{LIBRECHAT_USER_EMAIL}}'
    X-User-Role: '{{LIBRECHAT_USER_ROLE}}'
    X-API-Key: '${SOME_API_KEY}'
    Authorization: 'Bearer ${SOME_AUTH_TOKEN}'

apiKey

• 유형: Object (선택 사항, sse 및 streamable-http 유형의 경우)

• 설명: MCP 서버를 위한 API 키 인증 구성입니다. API 키 기반 인증을 구성하는 구조화된 방법을 제공합니다.

• 하위 키:

  • source: String - API 키가 어디에서 오는지 나타냅니다. 옵션:
    • "admin": API 키가 관리자에 의해 (환경 변수 또는 설정 파일에) 구성됨
    • "user": API 키는 사용자가 UI를 통해 제공합니다
  • authorization_type: String - API 키가 요청에 전송되는 방식입니다. 옵션:
    • "bearer": Authorization: Bearer <key>로 전송됨
    • "basic": Authorization: Basic <key>로 전송됨
    • "custom": 사용자 지정 헤더로 전송됨 (custom_header 필요)
  • custom_header: String - (필수: authorization_type이 "custom"인 경우) API 키에 사용할 헤더 이름

• 예시:

  # Admin-provided API key with Bearer auth
  my-server:
    type: streamable-http
    url: https://api.example.com/mcp
    apiKey:
      source: 'admin'
      authorization_type: 'bearer'
  
  # User-provided API key with custom header
  another-server:
    type: sse
    url: https://api.example.com/sse
    apiKey:
      source: 'user'
      authorization_type: 'custom'
      custom_header: 'X-API-Key'

iconPath

• 유형: 문자열 (선택 사항)
• 설명: 도구 선택 대화 상자에 표시되는 도구의 아이콘을 정의합니다.

chatMenu

• 유형: Boolean (선택 사항)
• 설명: false로 설정하면 채팅 영역 드롭다운(MCPSelect)에서 MCP 서버를 제외하여 빠르고 쉽게 액세스할 수 있습니다.
• 기본값: true (MCP 서버가 채팅 영역 드롭다운에 포함됩니다)

serverInstructions

• 유형: Boolean 또는 String (선택 사항)

• 설명: MCP 서버 지침이 에이전트 컨텍스트에 주입되는 방식을 제어합니다. 서버 지침은 개별 도구 설명을 보완하며, 전체 MCP 서버에 대한 상위 수준의 사용 지침을 제공합니다.

• 옵션:

  • undefined (기본값): 지침이 포함되지 않습니다.
  • true: 서버에서 제공하는 지침을 사용합니다(사용 가능한 경우). 포괄적인 가이드를 갖춘 잘 문서화된 서버에 이상적입니다.
  • false: 지침을 명시적으로 비활성화합니다. 컨텍스트 토큰을 절약하거나 도구가 자체적으로 설명 가능한 경우에 유용합니다.
  • string: 사용자 지정 지침(서버 제공 지침을 재정의함)을 사용합니다. 애플리케이션별 워크플로우나 서버 지침이 충분하지 않을 때 가장 적합합니다.

• 기본값: undefined (지침 포함 안 됨)

• 참고:

  • serverInstructions가 구성되어 있고 서버의 도구를 에이전트가 사용할 수 있을 때 지침이 자동으로 주입됩니다.
  • 여러 서버가 각각 에이전트 컨텍스트에 지침을 제공할 수 있습니다.

• 예시:

  # Use server-provided instructions
  serverInstructions: true
  
  # Use custom instructions
  serverInstructions: |
    When using this filesystem server:
    1. Always use absolute paths for file operations
    2. Check file permissions before attempting write operations
  
  # Explicitly disable instructions
  serverInstructions: false

env

• 유형: 객체 (선택 사항, stdio 유형만 해당)
• 설명: 프로세스를 생성할 때 사용할 환경 변수입니다.
• Placeholder 지원:
  • {{LIBRECHAT_USER_ID}}: 현재 사용자의 ID로 대체됩니다.
  • {{LIBRECHAT_USER_*}}: 동적 사용자 필드 플레이스홀더 (예: {{LIBRECHAT_USER_EMAIL}}).
  • {{CUSTOM_VARIABLE_NAME}}: customUserVars에 정의된 변수에 대해 사용자가 제공한 값으로 대체됩니다 (예: {{MY_API_KEY}}).
  • ${ENV_VAR}: 서버 측 환경 변수 {{ENV_VAR}}의 값으로 대체됩니다.

timeout

• 유형: 정수 (선택 사항)
• 설명: MCP 서버 요청에 대한 타임아웃(밀리초 단위)입니다. 음수가 아닌 정수여야 합니다.
• 기본값: 30000 (30초)

initTimeout

• 유형: 정수 (선택 사항)
• 설명: MCP 서버 초기화를 위한 타임아웃(밀리초 단위). 음수가 아닌 정수여야 합니다.
• 기본값: 10000 (10초)

requiresOAuth

• 유형: Boolean (선택 사항, 원격 전송 전용: sse, streamable-http, websocket)
• 설명: 이 서버가 OAuth 인증을 요구하는지 여부입니다. 지정하지 않으면 서버 시작 중에 자동으로 감지됩니다. 선택 사항이지만, 서버가 OAuth를 요구하는지 여부를 알고 있다면 이 값을 명시적으로 설정하는 것이 가장 좋습니다.
• 기본값: 지정되지 않은 경우 자동 감지됨
• 참고:
  • 원격(URL 기반) 전송 방식인 sse, streamable-http, websocket에 적용됩니다. 인증할 URL이 없는 stdio 서버에는 아무런 영향을 미치지 않습니다.
  • 자동 감지는 서버 시작 중에 발생하며, 이로 인해 초기화 시간이 추가될 수 있습니다.
  • 명시적 구성은 감지 단계를 건너뛰어 시작 성능을 향상시킵니다.
  • 정적 Authorization 헤더(예: Bearer API 키)로만 보호되는 서버의 경우 requiresOAuth: false로 설정하세요. 자동 감지 기능은 구성된 헤더 없이 서버를 프로브(probe)하므로, WWW-Authenticate: Bearer 챌린지와 함께 401 응답을 반환하는 서버는 OAuth 보호 서버로 잘못 분류될 수 있습니다. 이 플래그는 해당 프로브를 우회하여 정적 헤더가 연결을 정상적으로 인증할 수 있도록 합니다.
  • 향상된 연결 관리를 위해 MCP OAuth 환경 변수(MCP_OAUTH_ON_AUTH_ERROR, MCP_OAUTH_DETECTION_TIMEOUT, MCP_OAUTH_HANDLING_TIMEOUT, MCP_OAUTH_FLOW_TTL)와 함께 작동합니다.

stderr

• 유형: 문자열 또는 정수 (선택 사항, stdio 유형만 해당)
• 설명: 자식 프로세스의 stderr를 처리하는 방법입니다. 이는 Node의 child_process.spawn 의미론과 일치합니다. 유효한 문자열 값: "pipe", "ignore", "inherit". 또는 음수가 아닌 정수를 파일 디스크립터로 사용할 수 있습니다.
• 기본값: "inherit" ( stderr로 전송되는 메시지는 부모 프로세스의 stderr로 출력됩니다).

customUserVars

• 유형: 객체 (선택 사항)
• 설명: 이 MCP 서버에 대해 사용자가 설정할 수 있는 사용자 지정 변수를 정의합니다. 이를 통해 관리자는 각 사용자가 개별적으로 구성해야 하는 변수(예: API 키, URL)를 지정할 수 있습니다. 이렇게 사용자가 제공한 값은 headers 또는 env 구성에서 사용할 수 있습니다. customUserVars가 있는 서버는 앱 수준 연결에서 자동으로 제외되므로, 사용자별 자격 증명이 항상 런타임에 해결되도록 보장합니다.
• 구조:
  • customUserVars 객체는 키를 포함하며, 각 키는 변수 이름(예: MY_API_KEY)을 나타냅니다. 이 이름은 {{MY_API_KEY}}와 같은 플레이스홀더에 사용됩니다.
  • 각 변수 이름은 다음 하위 키를 포함하는 객체입니다:
    • title: String (Required) - 구성 UI에 표시되는 변수의 사용자 친화적인 제목입니다.
    • description: String (선택 사항) - 변수에 대한 설명 또는 지침으로, 사용자에게 안내하기 위해 UI에도 표시됩니다. 이 필드에는 HTML을 사용할 수 있습니다(예: 링크 생성: <a href="https://example.com" target="_blank">More info</a>).
    • sensitive: Boolean (선택 사항) - 값이 비밀로 취급되어 UI에서 마스킹될지 여부를 제어합니다. 생략 시 기본적으로 마스킹/비밀 처리되며, 프로젝트 ID나 기본 URL과 같이 비밀이 아닌 필드의 경우 false로 설정하십시오.
• headers 및 env에서의 사용법:
  • customUserVars 아래에 정의된 변수는 {{VARIABLE_NAME}} 구문을 사용하여 headers (sse 및 streamable-http 유형의 경우) 또는 env (stdio 유형의 경우) 섹션에서 참조할 수 있습니다.
  • 사용자는 UI를 통해 이러한 값을 제공합니다. 이러한 설정은 다음 두 가지 방법으로 액세스할 수 있습니다:
    • 어시스턴트 채팅 입력에서: 어시스턴트에 대해 MCP 도구를 선택할 때, 도구 선택 드롭다운의 구성 가능한 MCP 서버 옆에 설정 아이콘이 나타납니다. 이 아이콘을 클릭하면 해당 서버의 자격 증명을 관리할 수 있는 대화 상자가 열립니다.
    • 설정 패널에서: 오른쪽 패널에 있는 전용 "MCP Settings" 섹션에는 정의 가능한 사용자 지정 변수가 포함된 모든 MCP 서버가 나열됩니다. 사용자는 서버를 클릭하여 구성 대화 상자를 열고 해당 특정 MCP 서버에 대한 자격 증명을 설정하거나 업데이트할 수 있습니다.
  • 사용자가 제공한 이러한 값은 안전하게 저장되며, 개별 사용자 및 특정 MCP 서버와 연결되어 런타임에 대체됩니다.
• 예시:

  customUserVars:
    MY_SERVICE_API_KEY:
      title: 'My Service API Key'
      description: "Your personal API access key for My Service. Find it at <a href='https://myservice.example.com/settings/api' target='_blank'>My Service API Settings</a>."
      sensitive: true
    SOME_OTHER_VAR:
      title: 'Some Other Variable'
      description: 'The specific value for some other configuration (e.g., a specific path or identifier).'
      sensitive: false

  headers에서의 사용법:

  headers:
    X-Auth-Token: '{{MY_SERVICE_API_KEY}}'
    X-Some-Other-Config: '{{SOME_OTHER_VAR}}'

  env에서의 사용법 (stdio 유형의 경우):

  env:
    API_KEY: '{{MY_SERVICE_API_KEY}}'

obo

• 유형: Object (선택 사항, sse 및 streamable-http 유형에만 해당)
• 설명: MCP 서버를 위한 OAuth 2.0 On-Behalf-Of 토큰 교환을 구성합니다. LibreChat은 로그인한 사용자의 OpenID 액세스 토큰을 구성된 범위(scope)를 가진 위임된 다운스트림 토큰으로 교환한 다음, 해당 토큰을 Authorization: Bearer ... 헤더로 MCP 서버에 전달합니다.
• 필수 하위 키:
  • scopes: String - 다운스트림 토큰 교환을 위해 요청된 비어 있지 않은 범위(scope)입니다.
• 유효성 검사:
  • obo는 sse 및 streamable-http MCP 서버에서만 유효합니다.
  • obo는 stdio 및 websocket 서버에서 거부됩니다.
  • 사용자는 이 필드를 구성하기 위해 MCP_SERVERS.CONFIGURE_OBO 역할 권한이 필요합니다. interface.mcpServers.configureObo를 사용하여 시드(seed)하거나 관리자 패널에서 관리할 수 있습니다.
• 사전 요구 사항:
  • OpenID 인증은 재사용 가능한 액세스 토큰으로 구성되어야 합니다.
  • 귀하의 ID 공급자 및 다운스트림 애플리케이션은 요청된 위임된 범위를 허용해야 합니다.
• 예시:

  mcpServers:
    enterprise-tools:
      type: streamable-http
      url: https://api.example.com/mcp/
      obo:
        scopes: 'api://mcp-server-id/Mcp.Tools.ReadWrite'

관련 토큰 재사용 및 위임된 토큰 설정에 대해서는 OpenID Connect Token Reuse 및 SharePoint Integration을 참조하세요.

oauth

• 유형: 객체 (선택 사항)
• 설명: MCP 서버 인증을 위한 OAuth2 구성입니다. 구성이 완료되면, 사용자는 MCP 서버를 사용하기 전에 OAuth 흐름을 통해 인증하라는 메시지를 받게 됩니다. 클라이언트 ID와 클라이언트 시크릿이 제공되지 않으면 동적 클라이언트 등록(DCR)이 사용됩니다.
• 필수 하위 키:
  • authorization_url: String - OAuth 인증 엔드포인트 URL
  • token_url: String - OAuth 토큰 endpoint URL
  • client_id: String - OAuth 클라이언트 식별자
  • client_secret: String - OAuth 클라이언트 시크릿
  • redirect_uri: String - OAuth 리다이렉트 URI (예: http://localhost:3080/api/mcp/${serverName}/oauth/callback)
  • scope: String - OAuth 스코프 (공백으로 구분)
• 선택적 하위 키:
  • grant_types_supported: 문자열 배열 - 지원되는 권한 부여 유형 (기본값: ["authorization_code", "refresh_token"])
  • token_endpoint_auth_methods_supported: 문자열 배열 - 지원되는 토큰 엔드포인트 인증 방식 (기본값: ["client_secret_basic", "client_secret_post"])
  • token_exchange_method: String - 토큰 교환 요청 메서드. OAuth 클라이언트 자격 증명을 POST 본문에 포함해야 하는 공급자의 경우 default_post를 사용하세요.
  • response_types_supported: 문자열 배열 - 지원되는 응답 유형 (기본값은 ["code"])
  • code_challenge_methods_supported: 문자열 배열 - 지원되는 PKCE 코드 챌린지 메서드 (기본값: ["S256", "plain"])
  • skip_code_challenge_check: Boolean - OAuth 제공자가 PKCE 지원을 알리는지 확인하는 과정을 건너뜁니다. S256을 지원하지만 메타데이터에서 이를 알리지 않는 AWS Cognito와 같은 제공자에게 유용합니다. (기본값: false)
• 환경 변수: authorization_url, token_url, redirect_uri, revocation_endpoint를 포함한 YAML 정의 OAuth URL 필드는 ${ENV_VAR} 참조를 사용할 수 있습니다. LibreChat은 URL 유효성 검사 전에 환경 값을 확인합니다. UI를 통해 제출된 사용자 관리 OAuth 엔드포인트 URL은 리터럴 URL이어야 하며 ${ENV_VAR} 플레이스홀더는 거부됩니다.
• 예시:

  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/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']
    token_exchange_method: default_post
    response_types_supported: ['code']
    code_challenge_methods_supported: ['S256', 'plain']

oauth_headers

• 유형: 객체 (선택 사항)
• 설명: OAuth 흐름 요청에 특별히 사용되는 헤더입니다. 이 헤더들은 동적 클라이언트 등록 및 토큰 교환과 같은 OAuth 인증 중에 사용되며, 일반적인 MCP 서버 통신 중에는 전송되지 않습니다.
• 일반적인 사용 사례:
  • Authorization: Bearer ${DCR_API_KEY}와 같은 동적 클라이언트 등록(dynamic client registration) 엔드포인트에 인증 추가하기
  • OAuth 흐름에 필요한 사용자 지정 공급자별 헤더 포함
  • OAuth 토큰 엔드포인트에 필요한 헤더 설정
• headers와의 주요 차이점:
  • headers: 인증이 완료된 후 일반 MCP 서버 요청과 함께 전송됩니다.
  • oauth_headers: OAuth 인증 흐름 중에만 전송됩니다
• 예시:

  oauth_headers:
    Authorization: "Bearer ${DCR_API_KEY}"
    X-Custom-Header: "custom_value"

startup

• 유형: Boolean (선택 사항)
• 설명: false로 설정하면, 이 MCP 서버는 애플리케이션 시작 시 연결되지 않습니다. 이는 연결 전에 사용자 입력이나 구성이 필요한 서버나, 서버 초기화 시점을 직접 제어하려는 경우에 유용합니다.
• 기본값: true
• 예시:

  mcpServers:
    my-mcp-server:
      type: streamable-http
      url: 'https://api.example.com/mcp/'
      startup: false

참고 사항

• 유형 추론(Type Inference):
  • type이 생략된 경우:
    • url이 지정되어 있고 http:// 또는 https://로 시작하는 경우, type은 기본적으로 sse로 설정됩니다.
    • url이 지정되어 있고 ws:// 또는 wss://로 시작하는 경우, type은 기본적으로 websocket으로 설정됩니다.
    • command가 지정된 경우, type은 기본적으로 stdio로 설정됩니다.
• 연결 유형:
  • stdio: MCP 서버를 자식 프로세스로 시작하고 표준 입출력(standard input/output)을 통해 통신합니다.
  • websocket: WebSocket을 통해 외부 MCP 서버에 연결합니다.
  • sse: Server-Sent Events(SSE)를 통해 외부 MCP 서버에 연결합니다.
  • streamable-http: 스트리밍 응답을 지원하며 HTTP를 통해 외부 MCP 서버에 연결합니다.
• 내부/로컬 주소:
  • 중요: 내부 IP 주소(예: 172.24.1.165, 192.168.1.100) 또는 로컬 도메인(예: mcp-server, host.docker.internal)을 사용하는 MCP 서버는 명시적으로 허용해야 합니다. 공개 대상에 대한 접근성을 유지하면서 특정 사설 host:port 서비스를 허용하려면 mcpSettings.allowedAddresses를 사용하고, 엄격한 화이트리스트가 필요한 경우에는 mcpSettings.allowedDomains를 사용하세요.
  • 구성 세부 정보는 MCP Settings를 참조하세요.

예시

내부 주소를 사용한 구성

내부/로컬 MCP 서버를 사용하고 엄격한 도메인 화이트리스트가 필요하지 않은 경우, mcpSettings.allowedAddresses를 정확한 호스트 및 포트로 구성하세요:

# MCP Settings - Required for internal/local addresses
mcpSettings:
  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:
  prod-mcp:
    type: streamable-http
    url: http://172.24.1.165:8000/mcp
    timeout: 120000

  test-mcp:
    type: streamable-http
    url: http://mcp-prod:8001/mcp
    timeout: 120000

stdio MCP Server

puppeteer:
  type: stdio
  command: npx
  args:
    - -y
    - '@modelcontextprotocol/server-puppeteer'
  timeout: 30000
  initTimeout: 10000
  env:
    NODE_ENV: 'production'
    USER_EMAIL: '{{LIBRECHAT_USER_EMAIL}}'
    USER_ROLE: '{{LIBRECHAT_USER_ROLE}}'
  stderr: inherit

sse MCP 서버

everything:
  url: http://localhost:3001/sse
  headers:
    X-User-ID: '{{LIBRECHAT_USER_ID}}'
    X-API-Key: '${SOME_API_KEY}'

websocket MCP Server

myWebSocketServer:
  url: ws://localhost:8080

streamable-http MCP 서버

streamable-http-server:
  type: streamable-http
  url: https://example.com/api/
  headers:
    X-User-ID: '{{LIBRECHAT_USER_ID}}'
    X-API-Key: '${SOME_API_KEY}'

동적 사용자 필드를 사용하는 MCP Server

user-aware-server:
  type: sse
  url: https://api.example.com/users/{{LIBRECHAT_USER_USERNAME}}/stream
  headers:
    X-User-ID: '{{LIBRECHAT_USER_ID}}'
    X-User-Email: '{{LIBRECHAT_USER_EMAIL}}'
    X-User-Role: '{{LIBRECHAT_USER_ROLE}}'
    X-Email-Verified: '{{LIBRECHAT_USER_EMAILVERIFIED}}'
    Authorization: 'Bearer ${API_TOKEN}'

customUserVars를 통한 사용자별 자격 증명이 포함된 MCP Server

my-mcp-server:
  type: streamable-http
  url: 'https://api.example-service.com/api/' # Example URL
  headers:
    X-Auth-Token: '{{API_KEY}}' # Uses the API_KEY defined below
  customUserVars:
    API_KEY: # This key will be used as {{API_KEY}} in headers/url
      title: 'API Key' # This is the label shown above the input field
      description: "Get your API key <a href='https://example.com/api-keys' target='_blank'>here</a>." # This description appears below the input

참고: UI 기반 서버 초기화에 대한 자세한 내용은 MCP Server Initialization을 참조하세요.

사용자 지정 아이콘이 있는 MCP Server

filesystem:
  command: npx
  args:
    - -y
    - '@modelcontextprotocol/server-filesystem'
    - /home/user/LibreChat/
  iconPath: /home/user/LibreChat/client/public/assets/logo.svg
  chatMenu: false # Exclude from chatarea dropdown

OAuth 인증을 사용하는 MCP Server

oauth-api-server:
  type: streamable-http
  url: https://api.example.com/mcp/
  oauth:
    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/api/mcp/oauth-api-server/oauth/callback
    scope: 'read execute'
  oauth_headers:
    X-Custom-Header: 'custom_value'

서버 지침이 포함된 MCP Server

# Server that uses its own provided instructions
web-search:
  type: streamable-http
  url: https://example.com/mcp/search
  serverInstructions: true

# Server with instructions explicitly disabled
filesystem:
  command: npx
  args:
    - -y
    - '@modelcontextprotocol/server-filesystem'
    - /home/user/documents/
  serverInstructions: false

# Server with custom instructions
puppeteer:
  type: stdio
  command: npx
  args:
    - -y
    - '@modelcontextprotocol/server-puppeteer'
  serverInstructions: |
    Browser automation security and best practices:
    1. Be cautious with local file access and internal IP addresses
    2. Take screenshots to verify successful page interactions
    3. Wait for page elements to load before interacting with them
    4. Use specific CSS selectors for reliable element targeting
    5. Check console logs for JavaScript errors when troubleshooting

OAuth가 활성화된 MCP 서버 (레거시 requiresOAuth)

composio-googlesheets:
  type: sse
  url: https://mcp.composio.dev/googlesheets/sse-endpoint
  requiresOAuth: true
  headers:
    X-User-ID: '{{LIBRECHAT_USER_ID}}'
    X-API-Key: '${COMPOSIO_API_KEY}'
  timeout: 45000
  initTimeout: 15000

관련 환경 변수 (선택 사항):

# OAuth configuration for MCP servers
MCP_OAUTH_ON_AUTH_ERROR=true
MCP_OAUTH_DETECTION_TIMEOUT=10000
MCP_OAUTH_HANDLING_TIMEOUT=600000
MCP_OAUTH_FLOW_TTL=900000

# API key for the service
COMPOSIO_API_KEY=your_composio_api_key_here

MCP 서버 구성 가져오기

mcpServers 구성을 통해 LibreChat은 다양한 MCP 서버와 동적으로 상호작용할 수 있으며, 이를 통해 애플리케이션 내에서 전문화된 작업을 수행하거나 특정 기능을 제공할 수 있습니다. 이러한 모듈식 접근 방식은 서버 구성을 간단히 추가하거나 수정함으로써 애플리케이션의 기능을 쉽게 확장할 수 있도록 합니다.

추가 정보

• 기본 동작:
  • 초기화는 시작 시점에 발생하며, 변경 사항을 적용하려면 앱을 다시 시작해야 합니다.
  • url과 command가 모두 지정된 경우, 모호함을 피하기 위해 type을 명시적으로 정의해야 합니다.
• 다중 사용자 지원:
  • MCPManager는 이제 사용자 수준 및 앱 수준의 개별 연결을 지원하여, 사용자별로 적절한 연결 관리가 가능해졌습니다.
  • 사용자 연결은 별도로 추적 및 관리되며, 적절한 설정과 정리 과정이 수행됩니다.
  • 헤더, URL 및 환경 변수에서 동적 사용자 필드 플레이스홀더를 사용하세요:
    • {{LIBRECHAT_USER_ID}} - 사용자의 고유 식별자
    • {{LIBRECHAT_USER_EMAIL}} - 사용자의 이메일 주소
    • {{LIBRECHAT_USER_USERNAME}} - 사용자의 사용자 이름
    • {{LIBRECHAT_USER_ROLE}} - 사용자의 역할 (예: "user", "admin")
    • 그리고 더 많은 필드들 (전체 목록은 헤더 섹션 참조)
• 사용자 유휴 상태 관리:
  • 사용자 연결은 활동 여부가 모니터링되며, 15분 동안 활동이 없으면 연결이 해제됩니다.
• 환경 변수:
  • env 내 ( stdio 유형의 경우): MCP 서버 프로세스에 필요한 특정 런타임 환경이나 구성을 설정하는 데 유용합니다.
  • headers 내 ( sse 및 streamable-http 유형의 경우): 헤더 값에서 환경 변수를 참조하려면 ${ENV_VAR} 구문을 사용하세요.
• 동적 사용자 필드(Dynamic User Fields):
  • 사용자 필드 플레이스홀더는 런타임에 인증된 사용자의 정보로 대체됩니다.
  • 민감하지 않은 필드만 사용할 수 있습니다 (비밀번호 및 기타 민감한 데이터는 제외됨)
  • 누락된 필드는 기본적으로 빈 문자열로 설정됩니다.
  • Boolean 필드는 문자열 표현("true" 또는 "false")으로 변환됩니다.
• 오류 처리 (stderr):
  • stderr를 구성하면 MCP 서버 프로세스에서 발생하는 오류 메시지를 처리하는 방법을 관리할 수 있습니다. 기본값인 "inherit"은 오류가 부모 프로세스의 stderr로 출력됨을 의미합니다.
• Server Instructions:
  • MCP 서버 도구가 사용될 때 지침이 에이전트의 시스템 메시지에 자동으로 삽입됩니다.
  • 사용자 지정 지침(문자열 값)이 서버에서 제공된 지침보다 우선합니다.
  • 여러 MCP 서버가 각각 자신의 지침을 에이전트 컨텍스트에 기여할 수 있습니다.
  • 지침은 해당 MCP 서버의 도구가 실제로 에이전트에게 사용 가능한 경우에만 포함됩니다.
• OAuth 인증:
  • MCP 서버와의 안전한 인증을 위해 OAuth2 flow가 지원됩니다.
  • MCP 서버를 사용하기 전에 사용자는 OAuth를 통해 인증하라는 메시지를 받게 됩니다.

참고 자료

• Model Context Protocol (MCP) 문서
• MCP Transports Specification
• Node.js child_process.spawn

librechat.yaml에서 mcpServers를 올바르게 구성하면 LibreChat의 기능을 향상시키고 사용자 지정 도구 및 서비스를 원활하게 통합할 수 있습니다.