---
title: MCP 서버
description: Claude, Cursor, VS Code 등의 AI 어시스턴트를 /mcp의 내장 MCP 엔드포인트를 통해 설치된 API에 연결하세요. 인증, 클라이언트 구성, 도구 및 안전 규칙을 제공합니다.
url: https://nexcmp.com/ko/docs/developers/mcp/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# MCP 서버 {#mcp-server}

> **포털 내 위치:** API reference › Tools (`https://<your-domain>/apidoc`)에서 엔드포인트와 클라이언트 스니펫을 확인할 수 있으며, 키는 API keys (`/api-keys`)에서 생성합니다. 관리자 설정은 별도로 존재하지 않으며, 엔드포인트는 패널에 내장되어 있습니다.

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

**Model Context Protocol (MCP)**을 사용하면 AI 어시스턴트가 도구를 호출할 수 있습니다. NexCMP는 `https://<your-domain>/mcp`에 MCP 엔드포인트를 제공합니다. 모든 공개 API 작업이 하나의 **도구**(`vm_list`, `vm_start`, `billing_wallet`, ...)가 되므로, 고객은 어시스턴트에게 "내 VM 중 어떤 것이 실행 중인가요?" 또는 "스테이징 VM을 중지해 줘"라고 요청할 수 있습니다. 어시스턴트는 고객 본인의 API 키와 권한으로만 동작합니다.

::: tip NexCMP 자체를 AI로 구성하시겠습니까?
이 페이지는 **고객용** MCP 엔드포인트(`/mcp`)입니다. AI 어시스턴트가 관리자로서 패널을 구성하도록 하려면 [Configure with AI](https://nexcmp.com/ko/docs/configure-with-ai/mcp-admin/)(엔드포인트 `/mcp/admin`, 관리자 키 `ak_`)를 참조하세요.
:::

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| 서버 | 설치할 필요가 없습니다. 엔드포인트는 패널에서 직접 서비스하며 패널이 도달할 수 있는 곳이면 어디서나 접근 가능합니다. 리버스 프록시는 `/mcp`을(를) 패널로 전달해야 합니다. |
| Customer | 어시스턴트에 필요한 스코프가 포함된 [API key](https://nexcmp.com/ko/docs/developers/api-keys/)(`vk_...`). |
| 클라이언트 | **Streamable HTTP** 전송과 커스텀 `Authorization` 헤더를 지원하는 MCP 클라이언트: Claude Code, Claude Desktop(`mcp-remote` 브리지 경유), Cursor, Copilot 에이전트 모드가 있는 VS Code 등. |
| 프로토콜 버전 | 2025-11-25, 2025-06-18 및 2025-03-26. |

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

`https://<your-domain>/mcp`이(가) 방화벽이나 프록시 규칙에 의해 차단되지 않도록 하는 것 외에는 추가 조치가 필요 없습니다. 다른 오리진의 브라우저 기반 MCP 클라이언트는 해당 오리진이 허용되지 않은 경우 거부되며, 명령줄 및 데스크톱 클라이언트는 `Origin` 헤더를 전송하지 않으므로 그대로 작동합니다.

## 연결 (고객 측) {#connect-customer-side}

1. 어시스턴트가 사용할 스코프만 선택하고, 짧은 만료 시간 및 가능하면 IP 제한을 설정하여 포털(**API keys › Create key**)에서 API 키를 생성합니다.
2. 클라이언트에 서버를 추가합니다. `cloud.example.com` 및 키를 교체하세요.

   **Claude Code**

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

   **Cursor**(`~/.cursor/mcp.json` 또는 `.cursor/mcp.json`; Cursor가 시작되는 환경에 `CLOUD_API_KEY`을(를) 설정):

   ```json
   {
     "mcpServers": {
       "cloud": {
         "url": "https://cloud.example.com/mcp",
         "headers": { "Authorization": "Bearer ${env:CLOUD_API_KEY}" }
       }
     }
   }
   ```

   **Claude Desktop**(Node.js 18+ 필요; `claude_desktop_config.json`), `mcp-remote` 브리지 경유:

   ```json
   {
     "mcpServers": {
       "cloud": {
         "command": "npx",
         "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp", "--header", "Authorization:${CLOUD_AUTH_HEADER}"],
         "env": { "CLOUD_AUTH_HEADER": "Bearer vk_XXXX" }
       }
     }
   }
   ```

   콜론 뒤에 공백 없이 헤더를 작성하고 위와 같이 전체 값을 환경 변수에 입력하세요.

3. 클라이언트를 재시작하고 도구 목록을 표시하도록 요청합니다.


클라이언트 없이 연결을 확인합니다:

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

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

| 항목 | Detail |
|---|---|
| Endpoint | JSON-RPC 2.0 메시지가 포함된 `POST /mcp`; 응답은 `application/json`입니다. `GET /mcp`은(는) 405(서버-클라이언트 스트림 없음)를 반환하고, `DELETE /mcp`은(는) 세션을 종료합니다. |
| 인증 | `Authorization: Bearer vk_...`만 허용됩니다(세션 토큰, 쿠키, 관리자 키는 401 및 `WWW-Authenticate: Bearer` 헤더와 함께 거부됨). |
| 세션 | `Mcp-Session-Id`은(는) `initialize`에 의해 발급되며 해당 키에 바인딩되고 24시간 동안 유효합니다. 키당 최대 16개의 세션이 허용됩니다. |
| 도구 | 키에 표시되는 공개 API 작업당 하나씩 제공됩니다. 도구 이름은 공백과 대시 대신 `_`이(가) 들어간 CLI 명령(`vm firewall add`은(는) `vm_firewall_add`이(가) 됨)이며 OpenAPI `operationId`과(와) 일치합니다. 키에 해당 스코프가 있고 모듈이 활성화된 경우에만 도구가 나열됩니다. |
| 기능 | 도구만 지원(리소스나 프롬프트 없음). |
| 크기 | 요청 본문 최대 1 MB; 도구 결과 텍스트 최대 약 100 KB (초과분은 안내와 함께 잘림); 호출 시간 최대 55초. |

### 안전 규칙 {#safety-rules}

- **REST와 동일한 게이트.** 각 `tools/call` 요청은 패널 자체의 요청 파이프라인(범위, 사이트, IP 제한, 속도 제한, 멱등성, 소유권 검사(타인 리소스의 경우 404), 할당량)을 거칩니다. MCP는 키가 보유하지 않은 권한을 부여할 수 없습니다.
- **확인.** 비용이 발생하거나, 삭제를 수행하거나, 자격 증명(콘솔 티켓, kubeconfig, S3 또는 SSH 비밀번호, 비밀번호 초기화, 새 키)을 반환하는 도구는 `confirm: true` 인수가 필요합니다. 도구 설명은 사용자가 승인한 경우에만 이를 전달하도록 어시스턴트에 지시하므로 웹 페이지나 로그에 숨겨진 지시 사항이 임의로 실행될 수 없습니다.
- **멱등성.** 유료 도구는 `idempotency_key`을(를) 수락하며, 생략된 경우 도구 이름과 인수로부터 안정적인 키가 파생되므로 동일한 재시도로 인해 요금이 중복 청구되지 않습니다.
- **도구로 노출되지 않는 항목:** 스트리밍 엔드포인트(AI Agent 채팅), 일회성 SSH 또는 콘솔 WebSocket 티켓, 바이너리 다운로드, VPN 앱 엔드포인트(`/v1/ext/*`).
- **절대 불가능:** API는 잔액 충전, 비밀번호 변경, 계정 삭제 또는 키 생성을 절대 허용하지 않으므로 어시스턴트가 이를 수행할 수 없습니다.

### 제한 {#limits}

| 제한 | Default |
|---|---|
| 키당 도구 호출 | 분당 60회 |
| 키당 MCP 요청 | 분당 240회 |
| 일반 키 및 계정 제한 외 추가 적용 | [REST API](https://nexcmp.com/ko/docs/developers/api/#rate-limits) 참고 |

한도를 초과하면 엔드포인트는 JSON-RPC 오류 및 `Retry-After`과(와) 함께 HTTP 429를 응답합니다.

## 확인 {#verify}

1. 위의 `curl` 명령어는 `tools` 목록이 포함된 JSON-RPC 결과를 반환합니다. 키의 범위와 일치하는 도구만 표시됩니다.
2. 클라이언트에게 "내 VM 목록 보여줘"라고 요청하세요. 어시스턴트가 `vm_list`을(를) 호출하고 결과를 표시합니다.
3. 포털에서 키의 **Last used** 시간이 갱신되며, 쓰기 호출은 **Key usage log**에 표시됩니다.

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

- **브라우저 로그인(OAuth).** 참조 페이지에서는 MCP OAuth를 지원하는 클라이언트를 위한 브라우저 로그인 방법도 설명합니다. 설치된 NexCMP에서 지원 및 테스트된 방법은 API 키(또는 CLI의 경우 `cmp login`)입니다.
- **리셀러 사이트**에는 MCP 섹션이 표시되지 않으며, 고객은 API용 리셀러 도메인을 사용합니다.
- **최소 권한 원칙.** 읽기 범위가 포함된 전용 키를 어시스턴트별로 먼저 생성하고, 필요할 때만 쓰기 범위를 추가하세요.
- 어시스턴트의 액세스를 즉시 차단하려면 **API keys**에서 키를 취소하세요.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| `WWW-Authenticate: Bearer`과(와) 함께 발생하는 401 | 키가 없거나, 잘못되었거나, 세션 토큰인 경우 | `Authorization: Bearer vk_...`을(를) 전송하세요. |
| `Origin`과(와) 관련된 403 | 다른 오리진의 브라우저 페이지 | 데스크톱 또는 CLI 클라이언트를 사용하거나, 관리자에게 오리진(`mcp_allowed_origins`) 허용을 요청하세요. |
| `Mcp-Session-Id`이(가) 포함된 요청의 404 | 세션이 다른 키에 속해 있거나 만료됨 | `initialize`을(를) 다시 실행하세요. |
| `GET /mcp`에서 발생하는 405 | 예상된 동작: 서버에 이벤트 스트림이 없음 | POST만 사용하세요(클라이언트가 자동으로 처리합니다). |
| 도구 목록이 짧음 | 키 범위 또는 모듈 | 키에 범위를 추가하고 모듈을 활성화하세요. |
| `confirm: true`이(가) 필요하다고 응답하는 도구 | 유료, 삭제 또는 민감한 도구 | 사용자가 승인한 후 어시스턴트가 `confirm`을(를) 설정해야 합니다. |
| 429 | MCP 또는 키 속도 제한 | `Retry-After`을(를) 기다리세요. |
| 헤더로 클라이언트가 연결할 수 없음 | 사용자 지정 헤더를 지원하지 않는 클라이언트 | `mcp-remote` 브리지를 사용하세요. |