MCP 서버 - LexQ Docs

MCP란?

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

“VIP 고객용 할인 규칙을 만들어줘”
“loyaltyTier=‘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 22+ 설치
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 + 액션 메타데이터 + 미등록 fact
Domain Templates	목록, 미리보기, 적용
Deploy	발행, 배포, 롤백, 배포 해제, 이력, 상세, 현황, 배포 가능 버전, 버전 비교
Analytics	드라이런, 비교, 필수 fact, 시뮬레이션, 데이터셋 업로드/템플릿, 데이터셋 파일 업로드(로컬 전용)
Profile	그룹 지연 개요, 규칙 상세
History	목록, 조회, 통계
Replay	단건 재실행, 윈도우 시작·상태·목록·취소
Provenance	출처 조회, PII 열람 감사
Logs	목록, 조회
Webhook 구독	목록, 조회, 저장, 삭제, 테스트

도구 이름은 리소스별로 묶인 일관된 lexq_ 네임스페이스를 사용합니다 (예: lexq_rules_create, lexq_versions_clone, lexq_deploy_rollback). 두 연결 방법은 같은 도구 모음을 제공합니다. 예외는 로컬 서버에만 있는 lexq_dataset_upload_file 하나입니다(아래). 파라미터를 포함한 전체 목록은 명령어 레퍼런스에 있습니다. PII 열람 도구는 의도적으로 없습니다. 평문 열람은 콘솔 전용이며 항상 감사됩니다. 실패 로그도 조회만 할 수 있고, 해결과 무시는 콘솔 전용입니다. 조직의 관리자(Admin)가 관리 → 실패 로그에서 처리합니다.

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

데이터셋 파일

lexq_dataset_upload_file은 로컬 서버가 도는 컴퓨터에 있는 CSV나 JSON 파일을 올립니다. 서버가 디스크에서 직접 읽으므로 파일 내용이 대화를 거치지 않습니다. 클라우드 서버에는 이 도구가 없습니다. 거기서 파일을 읽으면 사용자의 컴퓨터가 아니라 LexQ 서버의 파일을 읽게 됩니다.

file에는 절대 경로를 줍니다. 맨 앞의 ~/는 홈 디렉터리입니다.
파일 이름은 .csv나 .json으로 끝나야 합니다. 심볼릭 링크는 따라가며, 링크가 가리키는 파일의 이름도 .csv나 .json으로 끝나야 합니다.
.json 파일은 레코드 배열이어야 합니다. 엔진은 {"facts": {...}} 같은 단건 객체도 받지만 이 도구는 거절하므로, [ ]로 감싸서 올리세요.
크기와 인코딩 조건은 다른 데이터셋 업로드와 같습니다.

결과로 저장된 path와, lexq_simulation_start에 넘길 dataset 블록을 돌려줍니다. 두 서버에 모두 있는 lexq_dataset_upload는 내용을 도구 호출에 담아 보내므로 작은 데이터셋에 맞습니다. 클라우드 서버는 요청 크기도 제한합니다. Claude.ai에서 큰 파일을 쓰려면 콘솔이나 lexq analytics dataset upload로 올린 뒤, 돌려받은 path를 에이전트에게 주세요.

경로는 에이전트가 고릅니다. 에이전트가 읽은 웹 페이지나 파일에 숨은 지시가 있으면, 의도와 다른 .csv나 .json 파일을 올리게 될 수 있습니다. 클라이언트가 도구 실행 승인을 물으면 경로를 확인하세요.

에이전트 모범 사례

스킬 먼저 읽기. skills/lexq-shared/SKILL.md를 먼저 읽게 하세요.
표준 워크플로우 준수. 그룹 생성 → 버전 → fact → 규칙 → 드라이런 → 발행 → 배포.
발행 전 항상 드라이런.
응답 envelope 확인. result === "SUCCESS"이며 success === true가 아닙니다.
참조한 fact를 등록하세요. 액션 대상(SET_FACT·MUTATE_FACT의 targetVar)은 규칙을 저장하기 전에 등록해야 합니다. 등록하지 않으면 저장이 ACT-032로 거절됩니다. 규칙이 읽기만 하는 키가 fact 정의에 없으면 create/update 응답에 해당 키를 알리는 비차단 경고가 포함됩니다. lexq_facts_create로 등록해 타입 검증을 활성화하거나, lexq_facts_unregistered로 버전 전체를 점검하세요.
값 제약을 바꾼 뒤 알려 주는 규칙을 고치세요. lexq_facts_update가 fact의 값 제약을 바꿨는데 그 fact를 새 제약에 없는 값과 비교하는 규칙이 있으면, 결과 끝에 그 규칙을 버전별로 적은 경고가 붙습니다. 수정은 이미 저장됐습니다. 발행하기 전에 초안에서, 또는 배포 중인 버전을 복제한 초안에서 그 조건을 고치세요(자세히).
롤백 전에 그룹을 읽으세요. lexq_deploy_rollback은 expectedCurrentVersionId와 expectedCurrentDeploymentId를 필수로 받습니다. lexq_groups_get이 돌려준 currentVersionId와 currentDeploymentId를 넘기세요. 409의 P-062나 P-063은 그 뒤 그룹이 바뀌었다는 뜻입니다. 다시 읽고 사용자에게 확인한 뒤 다시 시도하세요(자세히).

문제 해결

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 22+ 설치를 확인하세요. 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 클라이언트

사용 가능한 도구

데이터셋 파일

에이전트 모범 사례

문제 해결

다음 단계