MCP 서버

xenocast mcp가 제공하는 도구 7개의 입력과 응답, Claude Code, Codex, Cursor와 그 밖 클라이언트 등록

xenocast mcp는 표준 입출력(stdio) MCP 서버입니다. 설치한 CLI 실행 파일이 그대로 서버이고, 인증은 CLI와 같은 API 키입니다

인증

서버는 환경 변수 XENOCI_API_KEY나 xenocast config set api-key로 저장한 키를 읽습니다. 환경 변수가 우선합니다. 로그인은 없고, 키가 없으면 도구 호출이 api_key_required로 실패합니다

클라이언트 설정 파일에 키를 적지 않아도 됩니다. 저장된 키를 쓰면 설정 파일에는 명령만 남습니다. 모드는 서버가 시작할 때 정해지므로 키를 넣거나 바꾼 뒤에는 에이전트를 다시 시작합니다

initialize 응답의 serverInfo.name은 xenocast이고, instructions에 에이전트용 안내가 들어 있습니다(에이전트 규칙)

등록

자동 등록

API 키를 넣은 설치 한 줄이 설치된 Claude Code, Codex, Cursor, OpenCode, OmO에 서버를 등록합니다. 설치 뒤에 에이전트를 새로 깔았다면 xenocast setup을 다시 실행합니다

curl -fsSL https://github.com/Xeno-CI/xenocast/releases/latest/download/install.sh | XENOCI_API_KEY=xci_live_... sh
xenocast setup

등록은 기존 설정을 지우지 않고 xenoci 항목만 더하며, 고치기 전 파일을 .bak-xenocast- 이름으로 백업하고, 이미 있으면 건너뜁니다(--force로 다시 씁니다). 설정에는 명령만 들어가고 키는 들어가지 않습니다. Cursor는 cursor-agent mcp enable xenoci도 실행합니다

직접 등록하려면 아래를 씁니다

Claude Code

claude mcp add --transport stdio --scope user xenoci -- "$(which xenocast)" mcp
claude mcp list

Codex

codex mcp add xenoci -- "$(which xenocast)" mcp

Cursor

~/.cursor/mcp.json(또는 저장소의 .cursor/mcp.json)

{
  "mcpServers": {
    "xenoci": { "command": "xenocast", "args": ["mcp"] }
  }
}

그 밖 클라이언트

stdio MCP를 지원하는 클라이언트라면 명령 xenocast, 인자 ["mcp"]로 등록합니다. 저장된 키 대신 환경 변수를 쓰려면 클라이언트의 env 설정에 XENOCI_API_KEY를 넣습니다

{
  "mcpServers": {
    "xenoci": {
      "command": "xenocast",
      "args": ["mcp"],
      "env": { "XENOCI_API_KEY": "xci_live_..." }
    }
  }
}

설정 파일에 키를 적으면 그 파일을 커밋하거나 공유하지 않도록 주의합니다

연결 확인

에이전트에게 "xenoci whoami 도구를 불러 줘"라고 합니다. 키의 조직, 워크스페이스, 권한이 보이면 됩니다. 오류가 나면 error.code를 봅니다

code	뜻	할 일
`api_key_required`	키가 없음	`XENOCI_API_KEY=xci_live_... xenocast setup`, 그 뒤 에이전트 재시작
`invalid_api_key_format`	`xci_live_…` 형식이 아님	콘솔에서 발급한 키를 그대로 넣기
`invalid_api_key`	폐기, 만료, 알 수 없는 키	콘솔 API 키에서 새 키 발급
`insufficient_permission`	`read` 키로 `build`나 `cancel` 호출	권한이 실행과 조회인 키 사용

도구

tools/list의 inputSchema가 기준입니다. 타입을 그대로 보내야 하며(wait: "true"나 lines: "2" 불가), 스키마에 없는 인수는 unknown_argument로 거절됩니다

build

새 macOS VM에서 스크립트를 실행하는 잡을 접수하고 ID를 돌려줍니다

인수	타입	설명
`script`	string, 필수	VM에서 실행할 셸. 예: `bash ci.sh`
`dir`	string	올릴 프로젝트 폴더(tar.gz). 기본 현재 작업 폴더
`repo`	string	`owner/name`. `dir` 없이 주면 `https://github.com/owner/name.git`을 받음(공개 저장소). `dir`와 함께 주면 사용량 표시용 이름
`repo_url`	string	올리는 대신 받을 공개 git https 주소
`ref`	string	`repo`, `repo_url`의 브랜치, 태그, 커밋
`xcode`	string	Xcode 버전. 기본은 베이스 이미지 기본값
`timeout_minutes`	integer 1~360	제한 시간, 기본 60
`artifacts`	string[] 50개까지	결과물 글롭. 예: `["build/*.ipa"]`
`idempotency_key`	string 200자까지	재시도 키. 같은 키와 같은 입력이면 같은 잡
`wait`	boolean, 기본 false	true면 끝날 때까지 기다림

응답(wait: false): 잡 객체와 next: { tool: "status", arguments: { id } }. 폴더를 올렸으면 upload: { id, files }가 붙습니다

응답(wait: true): 끝난 잡 객체, exit_code, balance(잔액 뷰). 기다리는 동안 로그가 notifications/progress로 흐릅니다. 스크립트가 0이 아니면 isError: true와 failure_excerpt가 붙습니다

{"name":"build","arguments":{"dir":"/absolute/project","script":"bash ci.sh","artifacts":["build/*.xcresult"]}}

status

인수	타입	설명
`id`	string	잡 ID. 비우면 최근 잡 목록
`lines`	integer 0~200	마지막 로그 줄 수, 기본 40
`status`	string	목록 필터
`limit`	integer 1~200	목록 크기
`cursor`	string	이전 응답의 `next_cursor`

ID를 주면 잡 객체에 log_lines가 붙습니다. 비우면 { jobs: [...], next_cursor }입니다

cancel

인수	타입	설명
`id`	string, 필수	잡 ID

대기 중이거나 실행 중인 잡을 멈춥니다. 이미 시작한 분은 과금됩니다

logs

인수	타입	설명
`id`	string, 필수	잡 ID
`out`	string	저장할 폴더, 기본 `./xenocast-logs`
`artifacts`	boolean, 기본 false	true면 결과물도 내려받음

로그 전체를 <out>/<id>.log에 쓰고 파일 경로, 바이트, sha256, failure_summary, 마지막 40줄(tail)을 돌려줍니다. 로그 본문 전체는 응답에 넣지 않습니다

whoami

인수 없음. GET /v1/me 응답(인증 종류, 키 이름과 권한, 조직, 워크스페이스)을 돌려줍니다. 키 자체는 절대 돌려주지 않습니다

credits

인수 없음. 조직 잔액을 USD로 돌려줍니다

필드	설명
`balance_micro_usd`, `balance_display`	전체 잔액
`available_micro_usd`, `available_display`	사용 가능 잔액
`reserved_micro_usd`, `reserved_display`	실행 중 잡이 쓴 금액
`rate_micro_usd_per_min`, `rate_per_minute_display`	분당 요금
`low`	잔액 부족 기준 아래이면 true
`next_expiry`	다음에 만료될 크레딧과 시각
`topup_url`	콘솔 충전 링크
`note`	사람에게 링크를 보여 주라는 안내

금액은 정수 *_micro_usd(1 USD = 1,000,000)와 표시용 *_display($12.3457)를 함께 줍니다. 결제는 어떤 도구도 하지 않습니다

usage

인수	타입	설명
`from`	string	시작일 `YYYY-MM-DD`(UTC)
`to`	string	종료일 `YYYY-MM-DD`(UTC)
`group_by`	`day`, `workspace`, `api_key`	묶는 기준

GET /v1/usage 응답에 각 행과 합계의 amount_display를 더해 돌려줍니다

잡 객체

build, status, cancel이 돌려주는 모양입니다

{
  "id": "job_Ab12Cd34",
  "status": "succeeded",
  "queued_reason": null,
  "end_reason": "succeeded",
  "exit_code": 0,
  "created_at": "2026-10-11T03:00:00.000Z",
  "started_at": "2026-10-11T03:00:40.000Z",
  "ended_at": "2026-10-11T03:02:45.000Z",
  "run_seconds": 125,
  "billed_minutes": 3,
  "amount_micro_usd": 118800,
  "amount_display": "$0.1188",
  "rate_per_minute_display": "$0.0396"
}

오류

도구 오류는 isError: true와 error 객체로 옵니다. 프로토콜 오류는 JSON-RPC error입니다(없는 도구는 -32602)

코드	뜻
`invalid_request`	필수 인수, 타입, 범위 위반. `error.field`에 인수 이름
`unknown_argument`	스키마에 없는 인수. `error.arguments`에 목록
`insufficient_credit`, `credit_exhausted`, `workspace_spend_limit`, `tier_monthly_limit`, `tier_concurrency_limit`	잔액과 한도. `user_message`(사람에게 보여 줄 한국어 한 줄), `topup_url`, `next_action.show_user`가 함께 옵니다

잔액 오류 예

{"error":{"code":"insufficient_credit","message":"Available balance is below one minute at the current rate","retryable":false,"retry_after_s":null,"user_message":"잔액이 부족해 잡을 시작하지 않았습니다 (사용 가능 $0.0100, 1분 요금 $0.0396). 충전: https://xenoci.com/console/billing","topup_url":"https://xenoci.com/console/billing","next_action":{"show_user":"https://xenoci.com/console/billing","note":"A person tops up in the console. Never pay."}}}

응답과 진행 알림에 섞인 키 문자열은 [REDACTED]로 가립니다

첫 요청 예

이 폴더의 iOS 앱을 XenoCI에서 테스트하고 결과를 ./dist에 받아 줘

build: dir에 프로젝트 절대 경로, script에 xcodebuild -scheme App -destination 'platform=iOS Simulator,name=iPhone 16' CODE_SIGNING_ALLOWED=NO -resultBundlePath TestResults.xcresult test, artifacts: ["TestResults.xcresult"]
status(id)로 상태와 마지막 로그를 봅니다. 기다리려면 build에 wait: true
logs(id, out: "./dist", artifacts: true)로 로그와 결과물을 파일로 받습니다
멈추려면 cancel(id)

다음 단계

에이전트 규칙: 서버가 에이전트에게 주는 안내와 지켜야 할 규칙
xenocast CLI 레퍼런스: 같은 일을 터미널에서
결과물 내려받기: 결과물 보관과 받기