Skip to Content
사용자 가이드🎁 Special FeaturesCustom MCP ServerCustom MCP 서버 연동

Custom MCP 서버 연동

기업 내부에 이미 구축된 MCP 서버를 QueryPie AIP와 연결할 수 있습니다.

주요 기능

  • SSE(Server-Sent Events) 기반으로 Remote MCP 서버와 실시간 통신합니다.
  • 커스텀 헤더를 통한 인증을 지원합니다. 현재는 고정값으로만 인증 가능합니다.
  • OAuth 2.0 인증을 지원하여, 사용자가 개인 계정으로 안전하게 로그인하여 사용할 수 있습니다. 관리자가 OAuth 설정(Client ID, Secret 등)을 변경하더라도 기존 사용자의 인증이 유지되므로, 재인증 없이 계속 사용할 수 있습니다.
  • 동적 도구 스키마 로딩을 지원합니다.
  • 다양한 MCP 프로토콜 버전을 지원합니다.

인증 방식

Custom MCP 서버의 인증 요구사항에 따라 3가지 방식을 지원합니다.

인증 방식사용 시점설정 방법토큰 관리
OAuth 2.0사용자별 개인 계정 인증이 필요할 때MCP Server URL 입력 → OAuth 로그인사용자별 개별 토큰
헤더 기반 인증Bearer Token, API Key 등 고정 토큰을 사용할 때Headers에 직접 입력모든 사용자 공유
인증 없음공개 서버 또는 네트워크 수준 인증으로 충분할 때별도 설정 불필요—

OAuth 2.0은 각 사용자가 자신의 계정으로 로그인하여 개별 토큰을 발급받습니다. MCP 서버가 OAuth를 지원하면 URL 입력 시 AIP가 자동으로 감지합니다. 자세한 내용은 OAuth2 인증 및 DCR 가이드를 참조하세요.

헤더 기반 인증은 Headers for MCP server 섹션에 고정값을 입력하는 방식입니다. Authorization: Bearer {token} 또는 X-API-Key: {key} 형태로 설정하며, 입력된 헤더는 해당 MCP 서버를 사용하는 모든 사용자에게 동일하게 적용됩니다. 헤더에 Bearer Token이 설정되어 있으면 OAuth Discovery를 수행하지 않습니다.

인증 없음은 MCP 서버가 인증을 요구하지 않거나, VPN 등 네트워크 수준의 접근 제어로 충분한 경우에 해당합니다.

공용 인증과 개인 인증의 차이

관리자가 MCP 서버를 연동할 때, 공용 인증과 개인 인증 중 어느 방식으로 동작할지는 설정 방법에 따라 결정됩니다.

공용 인증 (헤더 기반) — 관리자가 연동 설정 시 Headers에 토큰을 입력하면, 해당 토큰은 모든 사용자에게 동일하게 적용됩니다. 사용자는 별도 로그인 없이 바로 MCP 서버를 사용할 수 있지만, 서버 측에서는 모든 요청이 동일한 계정으로 식별됩니다. 사용자별 권한 분리가 필요 없거나, 서비스 계정(Service Account) 하나로 충분한 경우에 적합합니다.

개인 인증 (OAuth 2.0) — Headers를 비워두고 MCP Server URL만 입력하면, AIP가 OAuth Discovery를 수행합니다. MCP 서버가 OAuth를 지원하면, 각 사용자에게 OAuth 로그인 팝업이 표시되고, 사용자마다 개별 토큰이 발급됩니다. 서버 측에서 사용자별로 다른 권한을 적용하거나, 누가 어떤 작업을 했는지 감사 추적(audit trail)이 필요한 경우에 적합합니다.

설정 방법 요약:

원하는 동작Headers 설정OAuth 지원 필요결과
공용 계정으로 모든 사용자 접근토큰 입력불필요모든 사용자가 동일 토큰 사용
사용자별 개인 계정 인증비워둠필요각 사용자가 OAuth 로그인

Headers에 Bearer Token이 설정되어 있으면 OAuth Discovery를 수행하지 않으므로, 개인 인증을 사용하려면 Headers를 비워두어야 합니다.

Custom MCP 서버 연동 방법

MCP Integrations 페이지 접근

Integrations 메뉴의 All Integrations 탭을 클릭합니다.

MCP Integrations 페이지

사용자 정의 MCP 연동 설정 카드를 클릭하여, Install New MCP Integration 페이지로 이동합니다.

Integration 정보 입력

Custom SSE 설정

Integration Information 섹션에서 다음 정보를 입력합니다:

  • Name (필수): 연동할 MCP 서버의 이름 (예: Custom SSE)
  • Description (필수): MCP 서버에 대한 간단한 설명 (예: Connect to Custom MCP SSE endpoint)
  • MCP Server URL (SSE) (필수): MCP 서버의 SSE 엔드포인트 URL
    • 형식: https://mcp.example.com/sse
    • 실제 운영 중인 MCP 서버의 SSE 엔드포인트 URL을 입력합니다.

Headers for MCP server (선택) 섹션에서 인증이 필요한 경우 헤더를 설정합니다.

  • Key: 헤더 키 (예: Authorization, X-API-Key)
  • Value: 헤더 값 (예: Bearer your-token-here)
  • 추가 헤더가 필요한 경우 + 버튼을 클릭하여 더 많은 헤더를 추가할 수 있습니다.

모든 정보를 입력한 후 Install 버튼을 클릭합니다.

OAuth 인증을 제공하는 서비스에 한정하여 OAuth 인증 팝업이 표기되며 서비스에 따라 팝업이 나타나지 않을 수 있습니다.

연동 완료

Integration 정보 입력

연동이 성공하면 Installed Integrations 목록에서 확인할 수 있습니다.

연동된 MCP 서버의 도구들이 AI 채팅에서 자동으로 사용 가능해집니다.
MCP Preset을 생성하여 특정 워크플로우에 맞게 도구를 조합해서 사용할 수 있어요.

로컬 또는 사설 네트워크에서 실행되는 MCP 서버와 연결하기

MCP 서버가 로컬 또는 사설 네트워크에서 실행되고 있는 경우, Edge tunnel 기능을 사용하여 AIP를 Custom MCP로 등록한 MCP 서버에 연결할 수 있습니다.

Edge tunnel은 로컬 MCP 서버와 AIP 사이에 보안 연결을 생성하여, 로컬 MCP 서버를 인터넷에 노출하지 않고도 사용할 수 있게 합니다.

자세한 설정 방법은 Edge Tunnel 문서를 참조하세요.

문제 해결

OAuth 팝업이 표시되지 않는 경우

  1. Headers에 Bearer Token이 설정되어 있는지 확인합니다. Bearer Token이 있으면 OAuth Discovery가 자동으로 비활성화됩니다. 개인 인증(OAuth)을 사용하려면 Headers를 비워두세요.
  2. OAuth 메타데이터 Discovery가 정상 동작하는지 확인합니다. AIP는 먼저 Protected Resource Metadata(WWW-Authenticate 또는 /.well-known/oauth-protected-resource)를 확인하고, 이후 authorization_servers를 따라 Authorization Server Metadata를 조회합니다.
  3. 내부 네트워크 서버인 경우 Use Edge Tunnel 옵션을 체크했는지 확인합니다.

자세한 OAuth 트러블슈팅은 OAuth2 인증 및 DCR 가이드를 참조하세요.

연결 실패 시

  1. MCP 서버 URL이 올바른지 확인합니다.
  2. 방화벽 설정을 확인합니다.
  3. 커스텀 헤더 설정이 올바른지 확인합니다.
  4. MCP 서버가 정상적으로 동작하는지 확인합니다.

도구 로딩 실패 시

  1. MCP 서버가 올바른 도구 스키마를 반환하는지 확인합니다.
  2. JSON 형식이 올바른지 확인합니다.
  3. 서버 로그를 확인하여 오류 메시지를 분석합니다.
Last updated on
Smart Tool DiscoveryOAuth2 인증 및 DCR 가이드