---
title: AI 클라이언트 연결 (MCP)
description: Claude Code, Codex CLI, Gemini CLI, Cursor, Claude Desktop, claude.ai, ChatGPT 또는 OpenAI SDK를 전체 도구 목록과 함께 패널의 관리자 MCP 엔드포인트에 연결합니다.
url: https://nexcmp.com/ko/docs/configure-with-ai/mcp-admin/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# AI 클라이언트 연결 (MCP) {#connect-an-ai-client-mcp}

> **관리자 위치:** System › Settings › API & AI agents (`/agent/keys`), **Connect an AI** 탭에 방금 만든 키로 채워진 엔드포인트 URL과 바로 복사할 수 있는 스니펫이 표시됩니다.

## 작동 내용 {#what-it-does}

**Model Context Protocol (MCP)**을 통해 AI 클라이언트가 도구를 호출할 수 있습니다. 패널은 `https://cloud.example.com/mcp/admin`에서 관리자 MCP 서버를 제공합니다. 자신의 AI 도구를 이에 연결하고 자연어로 질문하세요: "설정해야 할 남은 항목은 무엇인가요?", "Proxmox 클러스터 추가", "40% 마진으로 플랜 생성". 클라이언트는 아래 관리자 도구를 호출하며, 패널은 범위를 확인하고 위험한 작업 전 확인을 요청하며 모든 호출을 기록합니다.

::: info 두 개의 MCP 엔드포인트
`/mcp`은 **고객** 엔드포인트(고객 API 키, `vk_`; [MCP server](https://nexcmp.com/ko/docs/developers/mcp/) 참조)입니다. `/mcp/admin`은 여기에 설명된 **관리자** 엔드포인트입니다(관리자 키 `ak_` 또는 OAuth). 둘은 절대 혼용되지 않습니다. 관리자 도구는 `/mcp`에 표시되지 않으며, `/mcp/admin`은 관리자 키만 허용합니다.
:::

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| Endpoint | 패널 자체 도메인의 `https://cloud.example.com/mcp/admin`입니다. **Connect an AI** 탭에서 정확한 URL을 복사하십시오. 동일한 페이지에 서버 자체에서 실행되는 도구용 로컬 URL(`http://127.0.0.1:<port>/mcp/admin`)도 나열되어 있습니다. |
| 자격 증명 | 원하는 범위가 설정된 [admin API key](https://nexcmp.com/ko/docs/configure-with-ai/admin-api-keys/)(`ak_...`), **또는** 웹 코넥터용 OAuth 로그인([OAuth connectors](https://nexcmp.com/ko/docs/configure-with-ai/oauth-connectors/)). |
| 클라이언트 | **Streamable HTTP** 전송과 사용자 지정 `Authorization` 헤더를 지원하는 모든 MCP 클라이언트. 프로토콜 버전 2025-11-25, 2025-06-18 및 2025-03-26. |
| 네트워크 | 패널 앞에 자체 리버스 프록시를 배치하는 경우 `/mcp/admin`을(를) 전달해야 합니다. 웹 코넥터(claude.ai, ChatGPT)는 공급업체의 서버에서 연결하므로 URL이 인터넷에서 도달 가능해야 합니다. |

## 인프라 준비 {#prepare-the-infrastructure}

서버에 설치할 것이 없습니다. IP로 키를 제한하는 경우, 클라이언트가 연결하는 주소가 해당 대역에 있는지 확인하세요. 먼저 연결 가능성을 테스트하세요:

```bash
curl -i -X POST https://cloud.example.com/mcp/admin
```

`401` 응답과 `WWW-Authenticate: Bearer ... resource_metadata=...` 헤더는 엔드포인트가 작동 중이며 자격 증명을 요구함을 의미합니다.

## NexCMP에서 연결 {#connect-in-nexcmp}

1. 키 생성: **System › Settings › API & AI agents › API keys › New key**. 처음 시도할 때는 `admin:read`만 사용하고, 필요할 때 쓰기 범위를 추가하세요. [Admin API keys](https://nexcmp.com/ko/docs/configure-with-ai/admin-api-keys/)를 참조하세요.
2. **Connect an AI** 탭을 엽니다. "key created" 대화상자가 열려 있는 동안에는 아래의 모든 스니펫에 실제 키가 이미 포함되어 있습니다. 그렇지 않은 경우 자리표시자 `ak_YOUR_KEY`가 표시됩니다.
3. 클라이언트에 맞는 스니펫을 복사하여 아래 설명된 대로 실행하거나 붙여넣습니다.

![MCP URL이 포함된 Connect an AI 탭과 클라이언트당 복사 버튼이 있는 카드 하나](https://nexcmp.com/ko/docs/images/configure-with-ai/mcp-admin-01-connect.webp)

### Claude Code {#claude-code}

```bash
claude mcp add --transport http nexcmp https://cloud.example.com/mcp/admin \
  --header "Authorization: Bearer ak_XXXX"
```

그런 다음 `claude`을(를) 시작하고 "list the tools from nexcmp" 또는 "what is left to set up?"이라고 질문합니다.

30/10/2026에 Claude Code 2.1로 확인됨: `claude mcp add --transport http …`은(는) 서버를 기록합니다(`-s project`을(를) 추가하여 프로젝트의 `.mcp.json`에 유지할 수 있으며 — Claude Code는 최초 실행 시 프로젝트 서버 승인을 요청합니다). 스크립트의 경우 `claude -p "…" --mcp-config .mcp.json --strict-mcp-config --allowedTools "mcp__nexcmp__*"`은(는) 승인 프롬프트 없이 실행되며 Claude가 패널의 도구만 사용하도록 합니다.

### Claude Desktop {#claude-desktop}

Node.js 18 이상이 필요합니다. 이를 `claude_desktop_config.json`에 추가하고(`mcp-remote` 브리지 사용) Claude Desktop을 재시작합니다:

```json
{
  "mcpServers": {
    "nexcmp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp/admin", "--header", "Authorization:Bearer ak_XXXX"]
    }
  }
}
```

시스템에서 헤더 인수의 공백이 손상되는 경우, 고객 엔드포인트와 동일하게 전체 값을 환경 변수에 입력하십시오: `"args": [..., "--header", "Authorization:${NEXCMP_AUTH_HEADER}"]` 및 `"env": { "NEXCMP_AUTH_HEADER": "Bearer ak_XXXX" }`.

### claude.ai (custom connector) {#claude-ai-custom-connector}

키가 필요하지 않습니다. OAuth로 로그인합니다. claude.ai에서 커넥터 설정으로 이동하여 커스텀 커넥터를 추가하고, `https://cloud.example.com/mcp/admin`을(를) 붙여넣은 다음, NexCMP 관리자 계정으로 로그인하고 동의 화면에서 권한을 선택합니다. 상세 정보: [OAuth connectors](https://nexcmp.com/ko/docs/configure-with-ai/oauth-connectors/).

### ChatGPT (developer mode) {#chatgpt-developer-mode}

키가 필요하지 않습니다. ChatGPT에서 개발자 모드를 켜고, URL `https://cloud.example.com/mcp/admin`(으)로 MCP 커넥터를 추가한 다음, OAuth를 선택하고 NexCMP 관리자 계정으로 로그인합니다. 상세 정보: [OAuth connectors](https://nexcmp.com/ko/docs/configure-with-ai/oauth-connectors/).

### Codex CLI {#codex-cli}

`~/.codex/config.toml`에 추가:

```toml
[mcp_servers.nexcmp]
url = "https://cloud.example.com/mcp/admin"
bearer_token_env_var = "NEXCMP_KEY"
```

그다음 Codex를 시작하는 셸에서 키를 내보냅니다:

```bash
export NEXCMP_KEY=ak_XXXX
codex
codex mcp list   # shows nexcmp with "Bearer token" auth
```

::: tip 비대화형 `codex exec`
`codex exec`(스크립트, CI)에서 Codex는 도구를 호출하기 전에 확인하지 않으며 데이터를 변경하는 도구는 건너뜁니다. `default_tools_approval_mode = "approve"`을(를) `[mcp_servers.nexcmp]` 아래에 추가하여 호출을 허용할 수 있습니다. 결제, 보안 및 삭제 작업에 대해서는 패널이 여전히 미리보기를 반환하고 확인을 요청합니다. 30/10/2026에 Codex CLI 0.166으로 확인되었습니다.
:::

### Gemini CLI {#gemini-cli}

`~/.gemini/settings.json`에 추가:

```json
{
  "mcpServers": {
    "nexcmp": {
      "httpUrl": "https://cloud.example.com/mcp/admin",
      "headers": { "Authorization": "Bearer ak_XXXX" }
    }
  }
}
```

Gemini CLI는 신뢰하지 않는 폴더에서 MCP 서버를 끕니다. 신뢰하는 폴더에서 시작하거나(또는 요청할 때 폴더를 신뢰) `gemini mcp list`(으)로 확인하세요. `nexcmp … Connected`이(가) 표시됩니다. `"Authorization": "Bearer $NEXCMP_KEY"`을(를) 사용하면 파일에 키를 넣지 않을 수 있습니다. 2026/10/30 기준 Gemini CLI 0.66에서 확인됨.

### Cursor {#cursor}

`~/.cursor/mcp.json`(또는 프로젝트 내 `.cursor/mcp.json`)에 추가:

```json
{
  "mcpServers": {
    "nexcmp": {
      "url": "https://cloud.example.com/mcp/admin",
      "headers": { "Authorization": "Bearer ak_XXXX" }
    }
  }
}
```

::: tip 설정 파일에 키 보관하지 않기
클라이언트가 지원하는 경우 파일에 쓰는 대신 환경 변수에서 키를 읽어옵니다. Codex는 기본적으로 이를 수행하며(`bearer_token_env_var`), Cursor는 `"Bearer ${env:NEXCMP_KEY}"`을(를) 허용합니다. 키가 포함된 파일은 절대 커밋하지 마세요.
:::

### OpenAI Agents SDK (Python) {#openai-agents-sdk-python}

```python
from agents.mcp import MCPServerStreamableHttp

nexcmp = MCPServerStreamableHttp(
    params={"url": "https://cloud.example.com/mcp/admin",
            "headers": {"Authorization": "Bearer ak_XXXX"}},
    name="nexcmp",
)
```

완전한 실행 (2026/10/30 기준 `openai-agents` 0.24에서 확인됨 — 읽기 도구, 그리고 확인 미리보기를 반환하고 `confirm_token`(으)로 두 번째 호출에서 적용된 잔액 변경):

```python
import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    async with MCPServerStreamableHttp(params={"url": "https://cloud.example.com/mcp/admin",
            "headers": {"Authorization": "Bearer ak_XXXX"}}, name="nexcmp") as nexcmp:
        agent = Agent(name="admin", model="gpt-5", mcp_servers=[nexcmp],
                      instructions="You operate a hosting panel through the nexcmp tools. Ask me before confirming money actions.")
        result = await Runner.run(agent, "Run system_health and summarise it in one line.")
        print(result.final_output)

asyncio.run(main())
```

### OpenAI Responses API {#openai-responses-api}

서버를 `mcp` 유형의 도구로 전달합니다. 프로그램이 매 호출 전에 확인을 요청하도록 `require_approval`을(를) `always`에 유지하십시오:

```json
{
  "type": "mcp",
  "server_label": "nexcmp",
  "server_url": "https://cloud.example.com/mcp/admin",
  "headers": { "Authorization": "Bearer ak_XXXX" },
  "require_approval": "always"
}
```

### 기타 (일반 HTTP) {#anything-else-plain-http}

MCP가 없는 클라이언트는 HTTP를 통해 동일한 도구를 호출할 수 있습니다. `GET /v1/admin/agent/tools`은(는) 목록을 표시하고, `POST /v1/admin/agent/tools/<name>`은(는) JSON 본문 인수로 하나를 실행하며, `GET /v1/admin/openapi.json`은(는) OpenAPI 3.1 설명을 반환합니다(각 도구는 하나의 작업). 모두 `Authorization: Bearer ak_...`이(가) 필요합니다.

## 확인 {#verify}

1. 클라이언트 없이 도구 나열:

   ```bash
   curl -s https://cloud.example.com/mcp/admin \
     -H "Authorization: Bearer ak_XXXX" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
   ```

   응답은 허용된 스코프가 가진 도구가 포함된 JSON-RPC 결과입니다.
2. 클라이언트에게 "run system_health"를 실행하도록 요청합니다. 경고, 연결된 인프라의 상태, 결제, 이메일, AI 및 라이선스 상태를 반환합니다.
3. **API & AI agents › Activity**를 엽니다. 클라이언트 이름 및 `mcp`과 함께 호출 목록이 표시됩니다.
4. 서버에서 `sudo nexcmp status`은(는) 엔드포인트가 응답할 때 `ready`이라고 말하는 "MCP admin" 줄을 출력합니다(키가 없는 HTTP 401은 정상 상태임).

## 도구 {#tools}

서버는 58개의 도구를 제공합니다. 클라이언트는 키의 스코프가 허용하는 도구만 볼 수 있습니다. 읽기 도구에는 `admin:read`이(가) 필요하고, 쓰기 도구에는 자체 스코프가 필요합니다. 쓰기 도구에는 선택적 `confirm_token` 인수도 제공됩니다([Confirmation](#confirmation-confirm-token) 참조). 인수는 각 도구의 스키마에 대해 검사되며, 알 수 없거나 오타가 있는 인수는 이름을 지정하는 메시지와 함께 거부됩니다.

가격은 USD 기준입니다. 플랜 가격은 시간당 달러(`hourly_usd`), 잔액은 센트 단위입니다. 보안 비밀은 설정할 수 있지만 절대 반환되지 않습니다.

### 개요 및 로그 {#overview-and-logs}

| 도구 | 작동 내용 | Scope | 데이터 변경 | 사용자에게 확인 |
|---|---|---|---|---|
| `system_health` | 주의가 필요한 경고, 인프라 상태, 결제, 이메일, AI, 라이선스 및 업데이트 상태. | `admin:read` | 아니오 | 아니오 |
| `setup_checklist` | 구성된 항목과 남은 항목: 라이선스, 인프라, 영역, OS 템플릿, 플랜, 결제, 이메일, 브랜딩, 법적 고지, 테스트 주문. | `admin:read` | 아니오 | 아니오 |
| `license_status` | 라이선스 상태 및 최신 NexCMP 버전 존재 여부. | `admin:read` | 아니오 | 아니오 |
| `audit_search` | 관리자 감사 로그 및 API 키 로그 검색. | `admin:read` | 아니오 | 아니오 |

### 설정, 브랜딩, 법적 고지, 모듈 {#settings-branding-legal-modules}

| 도구 | 작동 내용 | Scope | 데이터 변경 | 사용자에게 확인 |
|---|---|---|---|---|
| `settings_get` | 일반 설정 읽기(`keys` 필터; 후행 `*`은(는) 접두사와 일치함). | `admin:read` | 아니오 | 아니오 |
| `settings_update` | 플랫 `values` 객체에서 일반 설정을 변경합니다. `settings_get`에 나열된 키만 허용됩니다. | `settings:write` | 예 | 키가 결제, 로그인 보안, 사이트 전체 스위치 또는 가격에 영향을 미치는 경우 |
| `branding_get` | 브랜드 이름, 색상, 표시 통화, 판매자 이름, 로고 및 파비콘 URL. | `admin:read` | 아니오 | 아니오 |
| `branding_update` | 브랜드 이름(최대 60자), 색상(`#rrggbb`), 표시 통화(`usd` 또는 `vnd`) 및 판매자 이름을 설정합니다. | `settings:write` | 예 | 아니오 |
| `branding_logo_set` | https URL 또는 base64(PNG, JPEG, WEBP, ICO 또는 SVG, 최대 512 KB)를 통해 밝거나 어두운 로고 또는 파비콘을 업로드합니다. | `settings:write` | 예 | 아니오 |
| `legal_get` | 이용 약관 및 개인정보 처리방침(영어 및 베트남어)과 중립적인 기본값. | `admin:read` | 아니오 | 아니오 |
| `legal_update` | 약관 및 개인정보 텍스트(간단한 마크다운, HTML 없음, 각각 최대 50 KB)를 설정합니다. 빈 문자열은 기본값으로 복원합니다. | `settings:write` | 예 | 아니오 |
| `modules_get` | 어떤 선택적 모듈이 켜져 있고 어떤 것을 전환할 수 있는지. | `admin:read` | 아니오 | 아니오 |
| `module_set` | 선택적 모듈을 켜거나 끕니다(`key`은 `settable` 중 하나여야 함). | `settings:write` | 예 | 아니오 |

### 이메일 및 알림 {#email-and-alerts}

| 도구 | 작동 내용 | Scope | 데이터 변경 | 사용자에게 확인 |
|---|---|---|---|---|
| `smtp_get` | 발신 이메일 설정(비밀번호 마스킹됨) 및 큐 상태. | `admin:read` | 아니오 | 아니오 |
| `smtp_configure` | SMTP 서버를 설정합니다. 호스트, 포트 또는 보안을 변경하려면 비밀번호를 다시 입력해야 합니다. | `settings:write`(비밀번호의 경우 `secrets:write` 추가) | 예 | 아니오 |
| `smtp_test` | 저장된 설정으로 실제 테스트 이메일을 보냅니다. | `settings:write` | 이메일 발송 | 아니오 |
| `telegram_get` | 관리자 알림 채널(채팅 ID; 봇 토큰은 절대 반환되지 않음). | `admin:read` | 아니오 | 아니오 |
| `telegram_configure` | 텔레그램 알림 채널(봇 토큰 및 채팅 ID)을 추가 또는 업데이트하고 관리자 알림을 켜거나 끕니다. | `settings:write`(토큰의 경우 `secrets:write` 추가) | 예 | 아니오 |
| `telegram_test` | 텔레그램 채널로 테스트 메시지를 보냅니다. | `settings:write` | 메시지 발송 | 아니오 |

### 결제 및 통화 {#payments-and-currency}

| 도구 | 작동 내용 | Scope | 데이터 변경 | 사용자에게 확인 |
|---|---|---|---|---|
| `payments_get` | Stripe, PayPal, 암호화폐(USDT) 및 계좌 이체 상태와 활성화된 채널 및 수수료. | `admin:read` | 아니오 | 아니오 |
| `payment_configure` | 하나의 게이트웨이(`stripe`, `paypal`, `crypto` 또는 `bank`) 자격 증명을 설정합니다. | `billing:write` (+ `secrets:write`) | 예 | 항상 |
| `payment_test` | 제공업체에서 게이트웨이의 저장된 자격 증명을 확인합니다. | `billing:write` | 아니오 | 아니오 |
| `currency_get` | 표시 통화 및 USD 대 VND 환율(자동 또는 수동). | `admin:read` | 아니오 | 아니오 |
| `currency_set` | 표시 통화 및/또는 수동 환율을 설정합니다(0은 자동, 그 외에는 15000에서 50000 사이). | `billing:write` | 예 | 수동 환율을 변경할 때 |

### 인프라 및 존 {#infrastructure-and-zones}

| 도구 | 작동 내용 | Scope | 데이터 변경 | 사용자에게 확인 |
|---|---|---|---|---|
| `cloudstack_get` | 저장된 CloudStack 엔드포인트, 존 및 네트워크 ID(키 마스킹됨). | `admin:read` | 아니오 | 아니오 |
| `cloudstack_test` | 저장하지 않고 API 키와 시크릿으로 엔드포인트를 테스트하며 존을 나열합니다. | `infra:write`(키를 전달하므로 `secrets:write` 추가) | 아니오 | 아니오 |
| `cloudstack_connect` | CloudStack 연결을 저장합니다. | `infra:write` (+ `secrets:write`) | 예 | 항상 |
| `proxmox_list` | 소스 및 상태와 함께 추가된 Proxmox VE 클러스터. | `admin:read` | 아니오 | 아니오 |
| `proxmox_add` | API 토큰(`user@realm!tokenid`) 및 시크릿을 사용하여 Proxmox VE 클러스터를 추가합니다. | `infra:write` (+ `secrets:write`) | 예 | 아니오 |
| `proxmox_test` | ID로 클러스터에 연결합니다. 첫 번째 성공 시 TLS 인증서가 고정됩니다. | `infra:write` | 예 | 아니오 |
| `proxmox_attach_zone` | 기존 존에서 Proxmox 클러스터를 판매하며, 선택적으로 노드를 리전으로 지정할 수 있습니다. | `infra:write` | 예 | 아니오 |
| `zones_list` | 고객이 선택할 수 있는 존(위치). | `admin:read` | 아니오 | 아니오 |
| `zone_create` | 존을 생성합니다. | `infra:write` | 예 | 아니오 |

### 카탈로그 및 플랜 {#catalog-and-plans}

| 도구 | 작동 내용 | Scope | 데이터 변경 | 사용자에게 확인 |
|---|---|---|---|---|
| `templates_list` | 고객이 설치할 수 있는 OS 템플릿. | `admin:read` | 아니오 | 아니오 |
| `templates_sync` | CloudStack에서 OS 템플릿을 가져옵니다. | `catalog:write` | 예 | 아니오 |
| `template_update` | 템플릿을 활성화 또는 숨기거나, 이름을 변경하거나, 로그인 사용자 또는 순서를 설정합니다. | `catalog:write` | 예 | 아니오 |
| `offerings_list` | 플랜을 구축할 CloudStack 서비스 오퍼링(CPU, 메모리, 루트 디스크). | `admin:read` | 아니오 | 아니오 |
| `plans_list` | 시간당 및 월당 가격, 크기, 존, 그리고 이를 사용하는 서버 수를 갖춘 플랜. | `admin:read` | 아니오 | 아니오 |
| `plan_create` | 플랜을 생성합니다. 가격은 `hourly_usd` 형식으로 입력합니다. CloudStack 플랜에는 `cs_offering_id`이(가) 필요하고, Proxmox 플랜에는 `backend_id`이(가) 필요합니다. | `catalog:write` | 예 | 아니오 |
| `plan_update` | 플랜의 이름 변경, 표시 또는 숨기기, 활성화 또는 비활성화, 재가격 지정을 수행합니다. 사용 중인 플랜의 크기 변경에는 복사가 필요합니다. | `catalog:write` | 예 | 가격이 변경될 때 |
| `plans_from_offerings` | 비용과 마진율을 사용하여 제공 상품(또는 Proxmox 크기)을 기반으로 스타터 플랜 테이블을 빌드합니다. 미리보기를 반환하며, 플랜을 생성하려면 `apply=true`과(와) 함께 다시 호출하세요. | `catalog:write` | `apply=true` 사용 | 항상 적용 시 |
| `quota_defaults_get` | 기본 고객 한도입니다. | `admin:read` | 아니오 | 아니오 |
| `quota_defaults_set` | `quota_*` 설정을 변경합니다. | `catalog:write` | 예 | 아니오 |
| `coupons_list` | 할인 및 기프트 코드 배치입니다. | `admin:read` | 아니오 | 아니오 |
| `coupon_create` | 코드 배치를 생성합니다: `money`(USD 센트 단위의 액면가) 또는 `percent`(1~100개, 최대 할인율 적용) 중 하나를 지정하세요. | `catalog:write` | 예 | 항상 |

### 고객 및 리셀러 {#customers-and-resellers}

| 도구 | 작동 내용 | Scope | 데이터 변경 | 사용자에게 확인 |
|---|---|---|---|---|
| `customers_search` | 이메일, 이름 또는 IP로 고객을 찾습니다. | `admin:read` | 아니오 | 아니오 |
| `customer_get` | 고객 한 명의 계정, 잔액, 서버 및 최근 결제 내역입니다. | `admin:read` | 아니오 | 아니오 |
| `customer_adjust_balance` | USD 센트 단위로 크레딧을 추가(양수)하거나 제거(음수)합니다. 사유가 필수입니다. | `billing:write` | 예 | 항상 |
| `customer_block` | 고객을 차단하고, 선택적으로 서버를 중지합니다. 사유가 필수입니다. | `customers:write` | 예 | 항상 |
| `customer_unblock` | 고객 차단을 해제합니다. | `customers:write` | 예 | 아니오 |
| `resellers_list` | 월렛 및 상태가 포함된 리셀러입니다. | `admin:read` | 아니오 | 아니오 |
| `reseller_get` | 리셀러 한 명의 사이트, 월렛, 사용자 및 게이트웨이입니다. | `admin:read` | 아니오 | 아니오 |

### AI 공급자 {#ai-provider}

| 도구 | 작동 내용 | Scope | 데이터 변경 | 사용자에게 확인 |
|---|---|---|---|---|
| `ai_provider_get` | 고객 AI Chat 및 AI Agent가 사용하는 OpenAI 호환 제공자입니다(키 마스킹됨). | `admin:read` | 아니오 | 아니오 |
| `ai_provider_set` | 제공자 설정: 기본 URL, 모델, API 키, 대체 모델, 추론 노력도, 활성화 여부. | `ai:write` (키의 경우 `secrets:write` 추가) | 예 | 아니오 |
| `ai_provider_test` | 작동하는지 확인하기 위해 저장된 제공자에게 질문을 하나 합니다. | `ai:write` | 아니오 | 아니오 |

### 설정 파일 {#configuration-files}

| 도구 | 작동 내용 | Scope | 데이터 변경 | 사용자에게 확인 |
|---|---|---|---|---|
| `config_export` | 설정을 YAML로 내보냅니다(비밀 값은 `secret://` 참조로 변경됨). | `admin:read` | 아니오 | 아니오 |
| `config_plan` | YAML 설정과 라이브 패널을 비교하고 변경될 내용을 나열합니다. | `admin:read` | 아니오 | 아니오 |
| `config_apply` | YAML 설정을 섹션별로 적용합니다. 각 변경 사항은 일반적인 범위 및 확인 규칙을 따릅니다. | `admin:read` + 모든 변경 사항의 범위 | 예 | 변경 당 |

파일 형식은 [Configuration as code](https://nexcmp.com/ko/docs/configure-with-ai/config-as-code/)을(를) 참조하세요.

## 프롬프트 {#prompts}

서버는 클라이언트가 단축키로 표시할 수 있는 기성 프롬프트 3개도 제공합니다.

| 프롬프트 | 인수 | AI에게 수행하도록 요청하는 작업 |
|---|---|---|
| `initial-setup` | none | `setup_checklist`을(를) 호출하고, 열려 있는 각 단계를 한 문장으로 설명하고, 필요한 정보를 요청하고, 일치하는 도구로 단계를 수행하고, 금액 또는 보안 변경 사항을 미리 보고, `system_health`(으)로 완료합니다. |
| `add-proxmox` | `endpoint` (선택 사항, `https://host:8006`) | API 토큰을 요청한 다음 `proxmox_add`, `proxmox_test`, 존 도구 및 `proxmox_attach_zone`을(를) 수행하고, `plans_from_offerings`(으)로 플랜을 제안하고 승인을 기다립니다. |
| `launch-pricing` | `margin_pct` (선택 사항, 기본값 40) | vCPU당, RAM 1GB당, 디스크 1GB당 월 비용을 요청하고, 비용, 월별 가격 및 시간당 가격이 포함된 미리보기 테이블을 표시하고, 승인 후 플랜을 생성합니다. |

## 확인 (`confirm_token`) {#confirmation-confirm-token}

자금을 이동하거나, 데이터를 삭제하거나, 결제 자격 증명을 변경하거나, 로그인 보안을 변경하는 작업은 2단계로 진행됩니다.

1. 첫 번째 호출에서는 아무것도 변경되지 않습니다. 도구 결과는 "CONFIRMATION REQUIRED"로 시작하며 **미리보기**(호출될 내용, 민감한 이유, 새 값 및 현재 값)와 `confirm_token`을(를) 포함합니다.
2. 클라이언트는 사용자에게 미리보기를 표시해야 합니다. 사용자가 승인한 경우에만 동일한 인수에 `confirm_token`을(를) 더하여 동일한 도구를 다시 호출합니다.
3. 토큰은 정확히 해당 요청에 한해 한 번만 작동하며 5분 후에 만료됩니다.

AI가 도구 결과를 지침이 아닌 데이터로 취급하고, 승인하지 않은 토큰으로 호출을 다시 반복하지 않도록 서버 지침에 설정되어 있습니다. 사용자가 보안의 마지막 보루이므로 미리보기를 확인하세요.

::: warning 자동 승인 금지
일부 클라이언트는 모든 도구 호출을 자동으로 승인할 수 있습니다. 쓰기 도구의 경우 호출별 승인을 유지하거나 읽기 전용 키를 사용하여 AI의 잘못된 계획이 패널에 무단으로 적용되지 않도록 하세요.
:::

## 동작 방식 {#how-it-works}

| 항목 | Detail |
|---|---|
| 전송 | `POST /mcp/admin`(JSON-RPC 2.0 메시지 포함), 응답은 `application/json`입니다. 배치당 최대 20개의 메시지입니다. `GET /mcp/admin`는 405(서버 스트림 없음)를 반환하고, `DELETE /mcp/admin`은 세션을 종료합니다. |
| 인증 | `Authorization: Bearer ak_...`(수동 키 또는 OAuth 액세스 토큰). 자격 증명이 누락되거나 잘못된 경우 `WWW-Authenticate: Bearer ... resource_metadata=...`과 함께 401 오류가 반환되어 OAuth 클라이언트가 자체적으로 로그인을 시작할 수 있습니다. |
| 세션 | `Mcp-Session-Id`은 `initialize`에서 발급되며, 해당 키에 바인딩되고 24시간 동안 유효합니다. |
| 기능 | 도구 및 프롬프트. 리소스는 없음. |
| 크기 | 요청 본문은 최대 1 MB이며, 도구 결과는 약 100 KB 이후 잘립니다. |
| 출처 | 다른 사이트에서 `Origin` 헤더를 포함하여 보낸 요청은 거부됩니다(`origin_not_allowed`). 명령줄 및 데스크톱 클라이언트는 헤더를 보내지 않습니다. |
| REST와 동일한 관문 | 각 도구 호출은 사용자의 키를 사용하여 패널 자체의 요청 파이프라인을 통해 다시 전송되므로, 범위, IP 대역, 속도 제한, 확인 및 활동 로그가 직접 API 호출과 정확히 동일하게 적용됩니다. |

## 한도 및 참고 사항 {#limits-notes}

- 볼 수 없는 도구는 권한을 부여하지 않은 범위입니다. 새 키에 해당 범위를 추가하세요.
- AI 클라이언트를 통해 비밀번호나 API 키를 설정한다는 것은 해당 비밀번호나 API 키가 해당 AI를 거쳐간다는 뜻입니다. 원하시는 경우 `secrets:write`을 끄고 관리자 페이지에서 직접 비밀번호를 입력하거나, AI Chat **Secret** 필드(관리자 페이지의 [AI Chat](https://nexcmp.com/ko/docs/configure-with-ai/ai-chat-in-admin/#secrets)) 또는 `secret://` 참조([Configuration as code](https://nexcmp.com/ko/docs/configure-with-ai/config-as-code/#secrets))를 사용하세요.
- 클라이언트는 세션을 공유하지 않으며, 각 연결은 `initialize`으로 시작합니다.
- AI 클라이언트의 연결을 즉시 차단하려면 **API & AI agents**에서 키를 취소하세요.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 401 `invalid_key` | 잘못되었거나 잘렸거나 관리자 권한이 아닌 키(예: `vk_` 키) | `ak_` 키를 사용하세요. |
| 401 `key_expired` 또는 `key_revoked` | 키가 만료되었거나 취소됨 | 새 키를 생성하세요. |
| 403 `ip_not_allowed` | 사용자의 IP가 키의 허용 IP 대역에 포함되지 않음 | 허용된 IP에서 연결하세요. |
| 403 `origin_not_allowed` | 다른 출처의 브라우저 페이지가 엔드포인트를 호출함 | 데스크톱 또는 CLI 클라이언트를 사용하세요. |
| `Mcp-Session-Id`이(가) 포함된 요청의 404 | 세션이 다른 키에 속해 있거나 만료됨 | `initialize`을 다시 보내세요. |
| 400 지원되지 않는 `MCP-Protocol-Version` | 클라이언트가 서버에서 인식하지 못하는 버전을 사용 중임 | 클라이언트를 업데이트하세요. 지원되는 버전: 2025-11-25, 2025-06-18, 2025-03-26. |
| 도구 목록이 짧음 | 키 범위 | 더 넓은 범위의 키를 생성하세요. |
| 호출 시 `insufficient_scope` | 도구에 두 번째 범위가 필요함(예: `secrets:write`) | 새 키에 해당 범위를 추가하세요. |
| 429 `rate_limited` | 키가 허용하는 분당 호출 횟수를 초과함 | `Retry-After` 동안 대기하거나 새 키에서 한도를 높이세요. |
| claude.ai 또는 ChatGPT 연결 불가 | 인터넷에서 URL에 접근할 수 없거나 프록시가 `/mcp/admin` 또는 `/oauth-admin/`을 차단함 | DNS, TLS 및 리버스 프록시를 확인하세요. |

모든 오류 코드는 [Admin API keys](https://nexcmp.com/ko/docs/configure-with-ai/admin-api-keys/#errors)에서 확인하세요.