MCP 서버 - LexQ Docs

MCP란?

**Model Context Protocol (MCP)**은 AI 어시스턴트를 외부 도구에 연결하는 개방형 표준입니다. LexQ는 전체 정책 생명주기를 다루는 전체 MCP 도구 모음을 제공합니다. 연결하면 AI 에이전트가 정책을 직접 관리할 수 있습니다:

“VIP 고객용 할인 규칙을 만들어줘”
“loyalty_tier=‘PLATINUM’으로 이 버전을 드라이런 해줘”
“v3과 v4를 비교하는 Impact Simulation을 실행해줘”

두 가지 연결 방법

방법	적합한 환경	설정	인증
클라우드 (Custom Integration)	Claude.ai 웹/모바일	URL만 입력 — 설치 불필요	OAuth (자동)
로컬 (stdio)	Claude Desktop, VS Code, Cursor	npm 설치 필요	API Key (설정 파일)

클라우드 — Claude.ai Custom Integration

가장 빠른 연결 방법입니다. 설치도 터미널도 필요 없습니다.

설정

Claude.ai → 설정 → 커넥터로 이동
커스텀 커넥터 추가 클릭
https://mcp.lexq.io 입력
LexQ 로그인 페이지가 열립니다
Google, 이메일/비밀번호, 또는 API Key 직접 입력으로 로그인
API Key를 선택하거나 생성 → Authorize 클릭
완료 — 모든 대화에서 전체 도구 모음 사용 가능

Claude.ai가 전체 OAuth 플로우를 자동으로 처리합니다. API Key는 Bearer 토큰으로 안전하게 저장되며, 설정 파일이 필요하지 않습니다.

아키텍처

Claude.ai ──► mcp.lexq.io (OAuth + Streamable HTTP)
                   │
                   ▼
          LexQ Engine (api.lexq.io)

로컬 — stdio MCP 서버

로컬 MCP 서버를 지원하는 데스크톱 AI 도구용입니다.

사전 요구사항

Node.js 18+ 설치
lexq auth login으로 API 키 저장

Claude Desktop

macOS
Windows

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "lexq": {
      "command": "npx",
      "args": ["-y", "@lexq/cli", "serve", "--mcp"]
    }
  }
}

%APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "lexq": {
      "command": "npx",
      "args": ["-y", "@lexq/cli", "serve", "--mcp"]
    }
  }
}

설정 후 Claude Desktop을 재시작하세요.

VS Code / Cursor

.vscode/mcp.json (또는 .cursor/mcp.json):

{
  "servers": {
    "lexq": {
      "command": "npx",
      "args": ["-y", "@lexq/cli", "serve", "--mcp"]
    }
  }
}

Windsurf / Gemini CLI / 기타 MCP 클라이언트

stdio 전송을 지원하는 모든 MCP 호환 클라이언트:

{
  "mcpServers": {
    "lexq": {
      "command": "npx",
      "args": ["-y", "@lexq/cli", "serve", "--mcp"]
    }
  }
}

stdio 서버는 ~/.lexq/config.json에서 API 키를 읽습니다. 시작 전에 lexq auth login을 실행하세요.

사용 가능한 도구

도메인	도구
Status	`lexq_whoami` — 인증 확인
Groups	CRUD + A/B 테스트 (시작, 중지, 조정)
Versions	CRUD + 복제
Rules	CRUD + 순서 변경 + 토글
Facts	CRUD + 액션 메타데이터 + 미등록 팩트
Domain Templates	목록, 미리보기, 적용
Deploy	발행, 배포, 롤백, 배포 해제, 이력, 상세, 현황, 배포 가능 버전, 버전 비교
Analytics	드라이런, 비교, 필수 팩트, 시뮬레이션, 데이터셋 업로드/템플릿
Profile	그룹 지연 개요, 규칙 상세
History	목록, 조회, 통계
Replay	단건 재실행, 윈도우 시작·상태·목록·취소
Provenance	출처 조회, PII 열람 감사
Integrations	목록, 조회, 저장, 삭제, 스펙
Logs	목록, 조회, 액션, 일괄
Webhook 구독	목록, 조회, 저장, 삭제, 테스트

도구 이름은 리소스별로 묶인 일관된 lexq_ 네임스페이스를 사용합니다 — 예: lexq_rules_create, lexq_versions_clone, lexq_deploy_rollback. 두 연결 방법 모두 동일한 전체 도구 모음을 제공하며, 파라미터를 포함한 전체 목록은 명령어 레퍼런스에 있습니다. PII 열람 도구는 의도적으로 없습니다. 평문 열람은 콘솔 전용이며 항상 감사됩니다.

LexQ는 큰 MCP 도구 모음으로 이루어져 있습니다. 일부 MCP 클라이언트는 모델에 전달하는 활성 도구 수에 상한을 두거나, 도구 수가 늘수록 성능이 저하됩니다 — 상한을 넘는 도구는 경고만 표시된 채 제외되기도 합니다. 클라이언트가 도구 상한을 알리거나 에이전트가 기대한 도구를 찾지 못하면, 클라이언트의 MCP 설정에서 현재 필요 없는 LexQ 도구를 비활성화하세요.

에이전트 모범 사례

스킬 먼저 읽기. skills/lexq-shared/SKILL.md를 먼저 읽게 하세요.
표준 워크플로우 준수. 그룹 생성 → 버전 → 팩트 → 규칙 → 드라이런 → 발행 → 배포.
발행 전 항상 드라이런.
응답 envelope 확인. result === "SUCCESS" — success === true가 아닙니다.
참조한 팩트를 등록하세요. 규칙이 팩트 정의에 없는 키를 참조하면 create/update 응답에 해당 키를 알리는 비차단 경고가 포함됩니다. lexq_facts_create로 등록해 타입 검증을 활성화하거나, lexq_facts_unregistered로 버전 전체를 점검하세요.

문제 해결

Claude.ai: 'Authorization with the MCP server failed'

설정 → 커넥터에서 커넥터를 제거한 후 https://mcp.lexq.io를 다시 추가하세요. 로그인과 API Key 선택 단계를 모두 완료해야 합니다.

stdio: 'API key not found'

MCP 서버 시작 전에 lexq auth login으로 API 키를 저장하세요.

stdio: 'npx: command not found'

Node.js 18+ 설치를 확인하세요. node --version으로 확인합니다.

stdio: 설정 후 도구가 보이지 않음

MCP 설정 추가 후 AI 클라이언트(Claude Desktop, VS Code 등)를 재시작하세요.

다음 단계

명령어 레퍼런스

전체 CLI 명령어와 MCP 도구 매핑.

정책 규칙

조건 구문과 액션 타입.

드라이런

발행 전 규칙 검증.

​MCP란?

​두 가지 연결 방법

​클라우드 — Claude.ai Custom Integration

​설정

​아키텍처

​로컬 — stdio MCP 서버

​사전 요구사항

​Claude Desktop

​VS Code / Cursor

​Windsurf / Gemini CLI / 기타 MCP 클라이언트

​사용 가능한 도구

​에이전트 모범 사례

​문제 해결

​다음 단계

명령어 레퍼런스

정책 규칙

드라이런

MCP란?

두 가지 연결 방법

클라우드 — Claude.ai Custom Integration

설정

아키텍처

로컬 — stdio MCP 서버

사전 요구사항

Claude Desktop

VS Code / Cursor

Windsurf / Gemini CLI / 기타 MCP 클라이언트

사용 가능한 도구

에이전트 모범 사례

문제 해결

다음 단계