AI 클라이언트 연결 (MCP)

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

작동 내용

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

두 개의 MCP 엔드포인트

/mcp은 고객 엔드포인트(고객 API 키, vk_; MCP server 참조)입니다. /mcp/admin은 여기에 설명된 관리자 엔드포인트입니다(관리자 키 ak_ 또는 OAuth). 둘은 절대 혼용되지 않습니다. 관리자 도구는 /mcp에 표시되지 않으며, /mcp/admin은 관리자 키만 허용합니다.

요구 사항

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

인프라 준비

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

bash

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

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

NexCMP에서 연결

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

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

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)

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

ChatGPT (developer mode)

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

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

비대화형 codex exec

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

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/mcp.json(또는 프로젝트 내 .cursor/mcp.json)에 추가:

json

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

설정 파일에 키 보관하지 않기

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

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

서버를 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)

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_...이(가) 필요합니다.

확인

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

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 결과입니다.

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

도구

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

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

개요 및 로그

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

설정, 브랜딩, 법적 고지, 모듈

도구	작동 내용	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`	예	아니오

이메일 및 알림

도구	작동 내용	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`	메시지 발송	아니오

결제 및 통화

도구	작동 내용	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`	예	수동 환율을 변경할 때

인프라 및 존

도구	작동 내용	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`	예	아니오

카탈로그 및 플랜

도구	작동 내용	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`	예	항상

고객 및 리셀러

도구	작동 내용	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 공급자

도구	작동 내용	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`	아니오	아니오

설정 파일

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

파일 형식은 Configuration as code을(를) 참조하세요.

프롬프트

서버는 클라이언트가 단축키로 표시할 수 있는 기성 프롬프트 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`)

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

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

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

자동 승인 금지

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

동작 방식

항목	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 호출과 정확히 동일하게 적용됩니다.

한도 및 참고 사항

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

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에서 확인하세요.

AI 클라이언트 연결 (MCP) ​

작동 내용 ​

요구 사항 ​

인프라 준비 ​

NexCMP에서 연결 ​

Claude Code ​

Claude Desktop ​

claude.ai (custom connector) ​

ChatGPT (developer mode) ​

Codex CLI ​

Gemini CLI ​

Cursor ​

OpenAI Agents SDK (Python) ​

OpenAI Responses API ​

기타 (일반 HTTP) ​

확인 ​

도구 ​

개요 및 로그 ​

설정, 브랜딩, 법적 고지, 모듈 ​

이메일 및 알림 ​

결제 및 통화 ​

인프라 및 존 ​

카탈로그 및 플랜 ​

고객 및 리셀러 ​

AI 공급자 ​

설정 파일 ​

프롬프트 ​

확인 (confirm_token) ​

동작 방식 ​

한도 및 참고 사항 ​

Troubleshooting ​

AI 클라이언트 연결 (MCP)

작동 내용

요구 사항

인프라 준비

NexCMP에서 연결

Claude Code

Claude Desktop

claude.ai (custom connector)

ChatGPT (developer mode)

Codex CLI

Gemini CLI

Cursor

OpenAI Agents SDK (Python)

OpenAI Responses API

기타 (일반 HTTP)

확인

도구

개요 및 로그

설정, 브랜딩, 법적 고지, 모듈

이메일 및 알림

결제 및 통화

인프라 및 존

카탈로그 및 플랜

고객 및 리셀러

AI 공급자

설정 파일

프롬프트

확인 (`confirm_token`)

동작 방식

한도 및 참고 사항

Troubleshooting