> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lexq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP 서버

> Claude, VS Code, Cursor 등 AI 도구를 MCP로 LexQ에 연결합니다.

## 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

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

### 설정

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

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

### 아키텍처

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

***

## 로컬 — stdio MCP 서버

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

### 사전 요구사항

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

### Claude Desktop

<Tabs>
  <Tab title="macOS">
    `~/Library/Application Support/Claude/claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "lexq": {
          "command": "npx",
          "args": ["-y", "@lexq/cli", "serve", "--mcp"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windows">
    `%APPDATA%\Claude\claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "lexq": {
          "command": "npx",
          "args": ["-y", "@lexq/cli", "serve", "--mcp"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

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

### VS Code / Cursor

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

```json theme={null}
{
  "servers": {
    "lexq": {
      "command": "npx",
      "args": ["-y", "@lexq/cli", "serve", "--mcp"]
    }
  }
}
```

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

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

```json theme={null}
{
  "mcpServers": {
    "lexq": {
      "command": "npx",
      "args": ["-y", "@lexq/cli", "serve", "--mcp"]
    }
  }
}
```

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

***

## 사용 가능한 도구

| 도메인                  | 도구                                             |
| -------------------- | ---------------------------------------------- |
| **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`. 두 연결 방법 모두 동일한 전체 도구 모음을 제공하며, 파라미터를 포함한 전체 목록은 [명령어 레퍼런스](/ko/cli/commands)에 있습니다. PII 열람 도구는 의도적으로 없습니다. 평문 열람은 콘솔 전용이며 항상 감사됩니다.

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

## 에이전트 모범 사례

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

## 문제 해결

<AccordionGroup>
  <Accordion title="Claude.ai: 'Authorization with the MCP server failed'">
    설정 → 커넥터에서 커넥터를 제거한 후 `https://mcp.lexq.io`를 다시 추가하세요. 로그인과 API Key 선택 단계를 모두 완료해야 합니다.
  </Accordion>

  <Accordion title="stdio: 'API key not found'">
    MCP 서버 시작 전에 `lexq auth login`으로 API 키를 저장하세요.
  </Accordion>

  <Accordion title="stdio: 'npx: command not found'">
    Node.js 18+ 설치를 확인하세요. `node --version`으로 확인합니다.
  </Accordion>

  <Accordion title="stdio: 설정 후 도구가 보이지 않음">
    MCP 설정 추가 후 AI 클라이언트(Claude Desktop, VS Code 등)를 재시작하세요.
  </Accordion>
</AccordionGroup>

## 다음 단계

<CardGroup cols={2}>
  <Card title="명령어 레퍼런스" icon="terminal" href="/ko/cli/commands">
    전체 CLI 명령어와 MCP 도구 매핑.
  </Card>

  <Card title="정책 규칙" icon="list-check" href="/ko/guides/policy-rules">
    조건 구문과 액션 타입.
  </Card>

  <Card title="드라이런" icon="flask-vial" href="/ko/guides/dry-run">
    발행 전 규칙 검증.
  </Card>
</CardGroup>