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

# MCP AI 에이전트 연동

> Claude, Cursor, Antigravity 등 AI 에이전트로 실습 가이드를 즉시 생성하고 계정으로 임포트합니다.

외부 AI 에이전트(Claude Code, Cursor, Antigravity 및 기타 Model Context Protocol 지원 도구)를 xkat에 연결하세요. 자연어 프롬프트 한 번으로 AI 에이전트가 xkat의 실습 랩 환경을 파악하고, 도메인 규격에 맞는 대화형 실습 가이드를 작성한 뒤 계정의 비공개 초안으로 즉시 임포트할 수 있습니다.

## 주요 워크플로우

<Steps>
  <Step title="개인 액세스 토큰 발급 및 연결">
    [설정 → AI 토큰](https://xkat.space/ko/settings/ai-tokens)에서 액세스 토큰을 발급한 뒤, 사용 중인 AI 에이전트 설정 파일에 원격 MCP 엔드포인트(`https://mcp.xkat.space/mcp`)를 등록합니다.
  </Step>

  <Step title="AI 에이전트에게 자연어로 요청">
    에이전트에게 평소처럼 질문합니다: *"QEMU 기반 데비안 12 설치 실습 가이드 만들어줘."*
  </Step>

  <Step title="랩 환경 탐색 및 가이드 생성">
    에이전트가 `list_lab_profiles`와 `get_guide_spec`을 호출하여 지원 환경(`debian_qemu`)과 작성 규칙(카드당 1개 단일 명령, Mermaid 다이어그램, 플랫폼 내부 배관 은닉)을 파악하고 가이드를 구성합니다.
  </Step>

  <Step title="비공개 초안 임포트 및 플레이어 링크 수신">
    에이전트가 `import_draft_guide`를 실행해 사용자 계정의 비공개 초안으로 즉시 DB에 저장하고, 플레이어 직행 링크(`https://xkat.space/ko/player/<id>`)를 반환합니다.
  </Step>
</Steps>

## 클라이언트별 설정 방법

사용하는 AI 도구의 설정 파일에 xkat MCP 서버를 추가합니다:

<Tabs>
  <Tab title="Claude Code (.mcp.json)">
    ```json theme={null}
    {
      "mcpServers": {
        "xkat": {
          "type": "http",
          "url": "https://mcp.xkat.space/mcp",
          "headers": {
            "Authorization": "Bearer <YOUR_TOKEN>"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Cursor (.cursor/mcp.json)">
    ```json theme={null}
    {
      "mcpServers": {
        "xkat": {
          "url": "https://mcp.xkat.space/mcp",
          "headers": {
            "Authorization": "Bearer <YOUR_TOKEN>"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Antigravity (mcp_config.json)">
    ```json theme={null}
    {
      "mcpServers": {
        "xkat": {
          "serverUrl": "https://mcp.xkat.space/mcp",
          "headers": {
            "Authorization": "Bearer <YOUR_TOKEN>"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## 사용 가능한 MCP 도구

| 도구 | 설명 |
| :- | :- |
| `import_draft_guide` | 가이드(XML/YAML/JSON)를 검증 후 사용자 계정의 비공개 초안으로 즉시 임포트하고 플레이어 링크를 반환합니다. |
| `get_guide_spec` | OS 설치(`os-install`), 리눅스 CLI(`linux-cli`), 데이터베이스 SQL(`database-sql`) 등 도메인별 작성 규격을 반환합니다. |
| `list_plugins` | 지원되는 뷰어 플러그인(`desktop-viewer`, `linux-wasix`, `sql-viewer` 등) 목록을 조회합니다. |
| `list_lab_profiles` | 지원되는 랩 실행 환경(`debian_qemu`, `ubuntu_qemu` 등) 목록을 조회합니다. |
| `validate_course` | DB에 저장하지 않고 강의 구조 및 XML 스키마 유효성을 검증합니다. |
| `build_course` | 입력된 강의 내용을 검증하고 정형화된 XML로 변환하여 반환합니다 (DB 저장 없음). |

## 제공 리소스

| 리소스 URI | 설명 |
| :- | :- |
| `catalog://plugins` | 지원 뷰어 플러그인 및 런타임 기능 카탈로그입니다. |
| `catalog://lab-profiles` | 사용 가능한 랩 실행 환경 및 가상 머신/컨테이너 카탈로그입니다. |
| `spec://os-install` | 게스트 OS 설치 가이드 작성 규격 및 액션 뱃지 규칙입니다. |
| `schema://course` | 유효한 강의 파일을 정의하는 JSON Schema입니다. |
| `template://sample-course` | 에이전트가 참고할 수 있는 YAML 예제 강의 템플릿입니다. |

## 임포트 한도 및 주의사항

`import_draft_guide`를 통한 가이드 임포트는 멤버십 등급별 월간 임포트 한도를 공유합니다:

* **Free** — MCP 임포트 미지원 (검증 및 빌드는 가능).
* **Basic** — 월 5회.
* **Pro** — 월 10회.
* **Creator** — 무제한.

<Tip>
  MCP로 임포트된 가이드는 `isPublished: false`(비공개 초안) 상태로 저장되므로, 크리에이터 본인이 스튜디오에서 검토하고 발행하기 전까지는 외부에 공개되지 않습니다.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.