MCP 설정 가이드

Overview

QueryPie ACP (Access Control Platform) Community Edition 11.5.0에 Remote MCP (Model Context Protocol) Server 기능이 추가 되었습니다. 이제 다양한 AI 코딩 어시스턴트에서 LLM을 사용해서 다양한 작업을 QueryPie ACP의 접근통제하에 안전하게 수행할 수 있습니다.

지원하는 AI 코딩 어시스턴트

• Claude Code 
• gemini-cli 
• Cursor 
• Windsurf 

사전 요구사항

• 실행 중인 QueryPie ACP Community Edition 11.5.0 이상
• QueryPie ACP Community Edition에 생성된 유효한 사용자 계정

Integration

MCP Server URL

AI 코딩 어시스턴트를 설정하기 위해, MCP Server 역할을 수행하는 QueryPie ACP 의 URL 을 입력하여야 합니다. 이 MCP Server URL 을 설정하는 것은 여러 AI 코딩 어시스턴트에서 공통적으로 수행하여야 합니다.

{QueryPie_URL}/api/mcp

{QueryPie_URL} 은 실행 중인 QueryPie ACP Community Edition의 주소입니다.

예시) https://querypie.example.com/api/mcp

Claude Code

1. MCP 서버 주소를 추가합니다.

claude mcp add querypie --transport http {QuerPie_URL}/api/mcp

예) claude mcp add querypie --transport http https://querypie.example.com/api/mcp

2. OAuth 로그인을 수행합니다.

먼저, /mcp 를 입력하여, 현재 설정된 MCP Server 의 상태를 확인합니다.

목록에서 querypie를 선택합니다. 이후, Authenticate 를 선택합니다.

브라우저가 열리면 QueryPie 로그인 페이지에서 로그인합니다. 정상적으로 로그인 되면 브라우저에 “Authentication Successful” 메시지가 출력됩니다.

Claude Code에서도 “Authentication successful. Connect to querypie.” 메시지가 출력됩니다.

3. MCP 연결을 확인합니다.

claude code를 실행하지 않은 상태라면 claude mcp list 명령으로 mcp 연결을 확인할 수 있습니다.

질의를 통해 작업을 수행하여 봅니다.

사용가능한 툴 확인이 되면 진행에 대한 질의가 출력됩니다. ‘yes’ 또는 ‘yes, and don’t ask again for querypie -…’ 를 선택합니다.

인증관리 : claude code에서 /mcp 명령을 실행하여 인증상태를 관리할 수 있습니다. 인증 토큰은 자동으로 갱신됩니다. “Clear authentication” 옵션으로 인증을 해제할 수 있습니다.

gemini-cli

1. 설정파일을 편집하여 MCP 서버 주소를 추가합니다.

설정 파일 편집 : ~/.gemini/settings.json 파일을 편집합니다.

{
  "mcpServers": {
    "acp": {
      "httpUrl": "https://acp.example.com/api/mcp"
    }
  }
}

OAuth를 지원하는 서버는 자동으로 감지됩니다.

2. OAuth 로그인을 수행합니다.

Gemini CLI에서 /mcp auth 명령을 사용하여 인증을 진행합니다.

 /mcp auth acp

브라우저가 열리면 QueryPie 로그인 페이지에서 로그인합니다. 정상적으로 로그인 되면 브라우저에 “Authentication Successful” 메시지가 출력됩니다.

자동으로 브라우저가 열리지 않는 경우 위 그림과 같이 화면에 출력되는 주소를 브라우저에 붙여넣어 진행할 수도 있습니다.

Cursor

1. 설정파일을 편집하여 MCP 서버 주소를 추가합니다.

설정파일 편집 : ~/.cursor/mcp.json 파일을 생성하거나 편집합니다:

{
  "mcpServers": {
    "acp": {
      "url": "https://querypie.example.com/api/mcp"
    }
  }
}

2. OAuth 로그인을 수행합니다.

• Cursor를 재시작하거나 MCP 서버 목록을 새로고침합니다.
• MCP 서버 목록에서 acp 서버의 인증 버튼을 클릭합니다.
• 웹 브라우저가 열리고 ACP 의 로그인 페이지가 표시됩니다.
• ACP에서 인증을 완료하면 Cursor에서 MCP 기능을 사용할 수 있습니다.

3. MCP 연결을 확인합니다.

Cursor Settings에서 MCP 툴이 올바르게 연동 되는지 확인합니다.

Windsurf

1. 설정파일을 편집하여 MCP 서버 주소를 추가합니다.

설정 파일을 생성하거나 편집합니다 : ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "acp": {
      "serverUrl": "https://querypie.example.com/api/mcp"
    }
  }
}

2. OAuth 로그인을 수행합니다.

• Windsurf를 재시작하거나 MCP 서버 목록을 새로고침합니다.
• MCP 서버 목록에서 acp 서버의 인증 버튼을 클릭합니다.
• 웹 브라우저가 열리고 ACP 의 로그인 페이지가 표시됩니다.
• ACP에서 인증을 완료하면 Windsurf에서 MCP 기능을 사용할 수 있습니다.

3. MCP 연결을 확인합니다.

Windsurf Agents 화면에서 MCP 툴이 올바르게 연동 되는지 확인합니다.

QueryPie ACP Community Edition MCP server의 지원 Tool 목록

DAC (Database Access Control)

데이터베이스 접근 및 쿼리 실행 관련 도구입니다.

SAC (Server Access Control)

서버 접근 및 SSH 셸 세션 관련 도구입니다.

KAC (Kubernetes Access Control)

Kubernetes 클러스터 관리 및 리소스 조작 도구입니다.

User Tools

일반 사용자가 할당된 권한 내에서 사용할 수 있는 도구입니다.

Admin Tools

관리자 권한이 필요한 도구입니다.

권한 및 보안

• 각 Tool은 ACP 권한 체계를 따릅니다.
• ACP 에서 각 이용자에게 제공되는 DAC 의 DB 연결, Privilege Type 에 따른 접근 제어 정책, SAC 의 서버 접근 제어 정책, KAC 의 접근제어 정책에 따라, 자신에게 부여된 권한 범위 내에서만 Tool을 사용할 수 있습니다.
• 모든 Tool 호출은 ACP 의 감사 로그에 기록됩니다.
• ACP 의 IP 접근 제어 정책이 적용됩니다.

문제 해결

연결 실패

• ACP API 서버가 실행 중인지 확인
• 네트워크/방화벽 설정 확인

권한 오류

• 해당 Tool에 필요한 권한이 있는지 확인
• 역할이 올바르게 할당되었는지 확인
• IP 허용 목록에 현재 IP가 포함되어 있는지 확인