AI 앱에 연결하기 (MCP) · 도움말 · Onpod

MCP 는 AI 앱이 바깥 도구를 쓰는 표준이에요. onpod CLI 안에 MCP 서버가 들어 있어서, 설치한 CLI 를 AI 앱에 연결만 하면 돼요. 터미널이 없는 Claude Desktop 에서도 쓸 수 있고, 로그인·기능·요금은 CLI 와 똑같아요.

코딩 에이전트한테 이렇게 말하세요

“이 폴더 onpod 에 올려줘”

“내 앱들 지금 상태 보여줘”

“blog 앱 왜 안 떠? 로그 봐줘”

👉 설치 없이 URL 하나로 연결하는 「커넥터」(claude.ai·Claude 데스크톱 · 교육장용)는 Claude 에 연결해서 말로 배포하기 를 보세요. 이 페이지는 내 컴퓨터의 onpod CLI 를 연결하는 방법이에요(서버·DB 까지 전부).

연결하는 법

① CLI 를 설치하고 한 번 로그인해요 — 콘솔 「API 키」에서 받은 키로 onpod login --token …
② 쓰는 AI 앱에 아래 설정을 넣어요
③ AI 앱을 다시 시작하면 onpod 도구가 보여요

Claude Code · Codex · Gemini CLI (터미널에서 한 줄)

claude mcp add onpod -- onpod mcp
codex mcp add onpod -- onpod mcp
gemini mcp add onpod onpod mcp

Claude Desktop · Cursor · Windsurf

Claude Desktop 은 설정 › 개발자 › 설정 편집, Cursor 는 ~/.cursor/mcp.json, Windsurf 는 ~/.codeium/windsurf/mcp_config.json 에 넣어요.

{
  "mcpServers": {
    "onpod": { "command": "onpod", "args": ["mcp"] }
  }
}

VS Code

프로젝트의 .vscode/mcp.json 에 넣어요.

{
  "servers": {
    "onpod": { "type": "stdio", "command": "onpod", "args": ["mcp"] }
  }
}

CLI 를 설치하지 않고 (npx)

Node.js 만 있으면 돼요. 로그인 대신 설정의 env 에 API 키를 넣어요.

{
  "mcpServers": {
    "onpod": {
      "command": "npx",
      "args": ["-y", "onpod", "mcp"],
      "env": { "ONPOD_TOKEN": "opk_..." }
    }
  }
}

AI 앱이 「onpod 를 찾을 수 없다」고 하면 터미널에서 onpod mcp config 를 실행하세요. 이 컴퓨터에 설치된 onpod 의 정확한 경로를 넣은 설정을 앱별로 출력해 줘요(데스크톱 앱은 터미널과 찾는 경로가 달라서 생기는 일이에요).

AI 가 쓰는 도구

도구	하는 일	종류
manual	onpod 사용법 — 필요한 주제만 골라 읽어요	조회
whoami	연결된 계정·회사 확인	조회
apps	내 앱 목록·상태·주소 (이름으로 거르기)	조회
app_status	앱 하나의 자세한 상태·실패 원인	조회
logs	앱·서버 로그 마지막 N줄	조회
deploy_plan	폴더를 보고 배포 제안·월 요금 (아무것도 안 만들어요)	조회
deploy	제안대로 배포 → 공개 주소 확인	변경
exec	서버 안에서 명령 한 번 실행	변경
onpod	그 밖의 모든 CLI 명령 (DB·도메인·GPU·파일 저장소…)	변경
job	몇 분 걸리는 작업 기다리기·취소	조회

「변경」 도구는 AI 앱이 실행 전에 확인을 받아요. 배포는 지금처럼 제안 → 확인 → 실행 순서이고, 몇 분 걸리는 배포도 AI 앱의 시간 제한에 끊기지 않게 작업 번호(job_id)를 먼저 받고 뒤에서 끝까지 진행돼요 — AI 가 그 번호로 결과를 이어 받아요.

안전장치

로그인은 MCP 로 받지 않아요 — 키가 채팅 기록에 남지 않게 CLI 로그인이나 설정의 env 로만
결제 카드·자동 충전 설정과 운영자 명령은 열려 있지 않아요 (충전 링크 발급은 돼요)
~/.ssh·~/.aws 같은 비밀 폴더, 홈 폴더 통째 업로드는 거절해요. 팟에서 받은 파일은 지정한 작업 폴더 안에만 저장돼요
조회만 허용하려면 args 를 ["mcp", "--read-only"] 로 두세요 — 배포·명령 실행 도구가 아예 안 보여요
필요한 권한·만료일만 고른 API 키를 따로 만들어 MCP 에 넣으면 더 안전해요

요금

MCP 와 CLI 는 무료예요. 올린 앱·DB·GPU 같은 자원만 지금 요금 그대로 쓴 만큼 나가요.

회사(기업 계정)에서 쓸 때

기업용 API 키로 로그인(또는 env 에 기업용 키)하면 AI 가 만드는 것들이 처음부터 회사 자산이 되고 회사 지갑으로 결제돼요. CLI 버전 0.7.137 이상에서 써요.