클라우드웨이즈 MCP: Access Token 권한과 Claude·Cursor 연결, AI로 서버 관리
클라우드웨이즈 MCP를 Claude Code에 연결해, 읽기 전용 Access Token으로 클라우드웨이즈 서버를 대화로 조회하는 설정을 마쳤습니다. 이름 때문에 클라우드웨이즈 서버에 무언가를 설치하는 것으로 착각할 수 있으며, 실제로 등록하는 곳은 AI 프로그램 쪽 설정 파일입니다.
같은 토큰으로 서버 목록과 서비스 상태, CPU 사용량을 조회했고, 캐시 비우기는 권한 오류로 거절되는 것까지 확인했습니다.
1️⃣ 클라우드웨이즈 MCP 작동 방식
클라우드웨이즈 MCP는 Claude·Cursor·ChatGPT 같은 AI 프로그램이 클라우드웨이즈 API를 대신 호출하게 하는 연결 서버이며, 모든 클라우드웨이즈 고객에게 추가 요금 없이 제공됩니다.
구성은 세 곳으로 나뉩니다. AI 프로그램(MCP 클라이언트)이 요청을 받아 사용할 도구를 고르고, 클라우드웨이즈가 운영하는 원격 MCP 서버(mcp.cloudways.com)가 그 요청을 클라우드웨이즈 API 호출로 바꿔 실행합니다. 관리 대상인 클라우드웨이즈 서버에는 아무것도 설치하지 않습니다.
등록은 Claude Code가 설치된 컴퓨터에서 하며, 윈도우 PC에서도 가능합니다. 이번에는 클라우드웨이즈 서버가 아니라, Claude Code를 설치해 이용하는 별도의 리눅스 서버에서 진행했습니다.
도구는 250개가 넘지만 AI 프로그램에 처음 보이는 것은 66개입니다. 나머지는 요청할 때 찾아서 실행하므로 따로 설정할 것은 없습니다.
2️⃣ Access Token 발급과 권한 범위
MCP 주소를 등록해도 Access Token이 없으면 클라우드웨이즈는 요청을 받지 않습니다. 토큰은 클라우드웨이즈 오른쪽 위 프로필 메뉴의 [API Integration]에서 만듭니다.
[Create Access Token]을 누르면 이름·만료 기간·권한 범위를 정하는 창이 열리며 이어서 진행합니다.
권한 범위(Scope)는 세 가지이며 기본값은 [Limited Access(Beta)]입니다. [Read-Only Access]는 서버 상태·애플리케이션 설정·사용량을 조회만 하고 만들기·변경·삭제는 할 수 없으며, [Full Access]는 계정 권한 안의 모든 API를 사용합니다. [Limited Access]는 고른 기능만 허용합니다.
처음 연결할 때는 [Read-Only Access]로 시작합니다. [Read-Only Access]는 실수로 지울 위험이 없지만, 캐시 비우기나 백업처럼 무언가를 실행하게 하려면 [Limited Access]로 그 기능만 열어야 합니다.
만료 기간은 1일부터 만료 없음까지 고를 수 있으며, 테스트에는 1개월을 사용했습니다.
토큰 값은 만들 때 한 번만 표시되며, 창을 닫으면 다시 볼 수 없어 폐기(Revoke) 후 새로 만들어야 하니 페이지 내에서 토큰 값을 미리 복사합니다.
기존 API Key 방식은 2026년 10월 중순에 종료되므로, API Key로 연결해 둔 MCP도 Access Token으로 바꿔야 합니다.
3️⃣ Claude·Cursor·VS Code 연결 설정
토큰을 만들어도 AI 프로그램에 등록하기 전까지는 대화에서 쓸 수 없습니다. Claude Code는 원격 HTTP MCP를 바로 지원해 명령 한 줄로 등록합니다. 이번에는 Claude Code를 설치해 이용하는 별도의 리눅스 서버(클라우드웨이즈 서버 아님) 터미널에서 실행했습니다.
claude mcp add --transport http --header "X-Access-Token: 토큰" --header "X-Mcp-Host: claude-code" -s user cloudways https://mcp.cloudways.com/mcp/명령의 [cloudways]는 등록 이름이고, [X-Access-Token]에는 발급한 Access Token을, [X-Mcp-Host]에는 사용하는 AI 프로그램 이름(claude-code)을 넣습니다. 토큰은 [cw_]로 시작하는 값만 넣으며, 안내문의 꺾쇠(< >)까지 함께 넣으면 토큰으로 인식되지 않습니다.
[-s user]로 등록하면 어느 폴더에서 claude를 실행해도 클라우드웨이즈 도구가 보이고, [-s local]은 명령을 실행한 폴더에서 실행할 때만 보입니다. 처음에는 작업 폴더에 local로 등록했지만 다른 폴더에서 실행하자 도구가 보이지 않아, user로 변경했습니다.
user로 등록해도 Claude Code는 도구 이름만 먼저 불러오고 설명은 사용할 때 불러오므로, local과 비교해 토큰 사용량에 큰 차이가 없습니다.
claude mcp list
cloudways: https://mcp.cloudways.com/mcp/ (HTTP) - ✔ Connected[claude mcp list]를 실행해 [cloudways] 줄 끝에 [Connected]가 표시되면 연결된 것입니다. 등록하자마자 지금 대화에서 쓸 수 있는 것은 아닙니다. MCP 도구는 세션을 시작할 때 불러오기 때문에, 새로 연 세션부터 클라우드웨이즈 도구가 보입니다.
등록 정보는 Claude Code 설정 파일인 홈 폴더의 [.claude.json]에 저장되며, 리눅스 root 계정이라면 [/root/.claude.json]입니다. user는 이 파일 맨 위의 [mcpServers]에, local은 [projects] 아래 해당 폴더 경로에 기록됩니다. 윈도우의 Claude Desktop은 [%APPDATA%\Claude\claude_desktop_config.json]에 같은 주소와 토큰을 넣습니다.
Cursor·VS Code 같은 다른 AI 프로그램도 설정 파일에 같은 주소와 토큰을 넣으며, 프로그램별 형식은 클라우드웨이즈 헬프센터 안내를 따릅니다.
4️⃣ 프롬프트로 실행 가능한 작업
Read-Only 토큰으로 연결한 상태에서 서버 목록, 서버 상세, 서비스 상태, CPU 사용량, 애플리케이션 목록, SSL 인증서 상태를 차례로 요청했으며, 조회 요청은 모두 결과를 받았습니다. 아래 응답 시간은 클라우드웨이즈 MCP 서버가 결과를 돌려준 시간이며, AI가 답변을 정리하는 시간은 포함하지 않습니다.
| 요청 | 실행되는 도구 | 응답 시간 | 응답 내용 |
|---|---|---|---|
| 내 서버 목록 보여 줘 | server_list | 0.72초 | 서버 1대, 실행 중(running), Vultr 서울 리전, 1GB, MariaDB 10.11 |
| 서버 상세 정보 알려 줘 | server_get | 0.68초 | Debian 12, 디스크 25GB, 설치된 애플리케이션 1개(WordPress) |
| 서비스 상태 확인해 줘 | service_status | 5.10초 | 실행 중 8개(Nginx·Apache·MySQL·PHP 8.2-FPM·Redis·Varnish·Memcached·Imunify360), 중지 1개(New Relic) |
| 최근 24시간 CPU 사용량 | monitoring_server_graph | 1.75초 | 5분 간격 288개 값, 평균 사용률 약 13%, 최고 약 30% |
| 애플리케이션 목록 보여 줘 | app_list | 0.67초 | WordPress 1개, 연결 도메인 cw.testpilotweb.com |
| SSL 인증서 상태 확인해 줘 | app_get | 3.04초 | Let's Encrypt 설치·확인 완료, 자동 갱신 사용 |
| 캐시 비워 줘 | app_purge_cache | 0.42초 | 실행 거절 — 403 insufficient_scope |
CPU 사용량은 유휴 CPU(Idle CPU) 비율로 응답하며, 평균 86.8%는 사용률 약 13%에 해당합니다. SSL 상태를 조회하는 전용 도구는 없어, 애플리케이션 상세 정보([app_get])의 Let’s Encrypt 항목으로 확인했습니다.
AI에게 요청하면 무엇이든 실행될 것 같지만, 실행 범위는 토큰 권한이 결정합니다. 캐시 비우기를 요청한 결과 [app_purge_cache] 도구가 실행되었지만, 클라우드웨이즈는 [Cloudways API error (403): This token does not have access to this endpoint — insufficient_scope] 오류로 거절했습니다.
어떤 도구가 쓰기 작업인지는 [get_write_tools] 도구가 돌려주는 목록으로 확인할 수 있습니다.
5️⃣ 연결 오류와 도구 목록 갱신
연결이 되지 않으면 [claude mcp list]에서 [cloudways] 줄이 [Connected]인지부터 확인합니다. 주소가 [https://mcp.cloudways.com/mcp/]와 끝의 슬래시까지 같지 않으면 오류 문구 없이 연결되지 않으며, [401 Unauthorized]가 나오면 토큰을 잘못 입력했거나 폐기·만료된 토큰입니다.
토큰을 바꿀 때는 [claude mcp remove cloudways -s user]로 등록을 삭제한 뒤 새 토큰으로 다시 등록하며, 터미널에서 [claude] 명령이 실행되지 않으면 Claude Code 실행 파일을 전체 경로로 지정해 실행합니다.
창을 닫았다가 다시 열면 도구 목록도 새로 고쳐진다고 생각하기 쉽지만, Claude Desktop·Cursor 같은 프로그램은 처음 연결할 때의 도구 목록을 저장해 두며 창을 닫아도 트레이에서 계속 실행됩니다. 클라우드웨이즈가 도구를 추가한 뒤 새 도구가 보이지 않으면 설정에서 cloudways 연결을 비활성화했다가 다시 활성화하거나, 프로그램을 완전히 종료(macOS Cmd+Q, 윈도우 트레이 아이콘의 종료)한 뒤 다시 실행합니다.
🔢 FAQ & 추천 콘텐츠
ℹ️ 제휴 안내
본 사이트의 콘텐츠에는 제휴 링크가 포함되어 있습니다. 방문자가 이 링크를 통해 상품 또는 서비스를 구매하면 본 사이트는 판매처로부터 수수료를 지급받습니다. 이 과정에서 구매자가 지불하는 금액(이벤트 할인 시 금액이 내려갑니다↓)은 오르지 않습니다. 게시된 가격·할인·재고 정보는 작성 시점 기준이며 실제와 다를 수 있으므로, 구매 전 판매처에서 최종 확인하시기 바랍니다. 상품 선정과 평가는 자체 기준에 따라 작성되며, 수수료 지급 여부가 소개 순서나 평가 내용에 영향을 주지 않습니다.