MCP 서버

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

작동 내용

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

NexCMP 자체를 AI로 구성하시겠습니까?

이 페이지는 고객용 MCP 엔드포인트(/mcp)입니다. AI 어시스턴트가 관리자로서 패널을 구성하도록 하려면 Configure with AI(엔드포인트 /mcp/admin, 관리자 키 ak_)를 참조하세요.

요구 사항

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

인프라 준비

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

연결 (고객 측)

1. 어시스턴트가 사용할 스코프만 선택하고, 짧은 만료 시간 및 가능하면 IP 제한을 설정하여 포털(API keys › Create key)에서 API 키를 생성합니다.

2. 클라이언트에 서버를 추가합니다. cloud.example.com 및 키를 교체하세요.

   Claude Code

   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을(를) 설정):

   {
     "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 브리지 경유:

   {
     "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. 클라이언트를 재시작하고 도구 목록을 표시하도록 요청합니다.

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

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"}'

동작 방식

항목	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초.

안전 규칙

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

제한

제한	Default
키당 도구 호출	분당 60회
키당 MCP 요청	분당 240회
일반 키 및 계정 제한 외 추가 적용	REST API 참고

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

확인

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

한도 및 참고 사항

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

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 브리지를 사용하세요.