에이전트 규칙

MCP 서버가 에이전트에게 주는 안내문과, 에이전트가 XenoCI를 쓸 때 지켜야 할 규칙

코딩 에이전트가 XenoCI 도구를 안전하게 쓰도록 서버가 주는 안내와 응답 규칙을 정리했습니다. 에이전트용 시스템 프롬프트나 저장소 안내 파일(AGENTS.md, CLAUDE.md)에 옮겨 적을 수 있습니다

서버가 주는 안내문

xenocast mcp는 initialize 응답의 instructions로 다음을 전달합니다

XenoCast. Auth: an API key in XENOCI_API_KEY (or saved with xenocast config set api-key); there is no login.
build runs a script on a fresh macOS VM (destroyed afterwards) and returns the job id; status shows state, billed minutes, cost in USD and the last log lines;
cancel stops a job; logs writes the log (and artifacts) to files; whoami names the key's organization, workspace and permission;
credits shows the USD balance and the console top-up link; usage the spend in USD.
insufficient_credit, credit_exhausted, workspace_spend_limit, tier_monthly_limit or tier_concurrency_limit come back with user_message and topup_url: show them to the person. Never pay.

규칙

결제는 사람이 합니다. 어떤 도구도 충전하거나 결제하지 않습니다. 잔액 오류가 오면 user_message와 topup_url을 그대로 사람에게 보여 주고 멈춥니다
키를 출력하지 않습니다. whoami는 키를 돌려주지 않고, 응답과 로그의 xci_live_…는 [REDACTED]로 가려집니다. 에이전트도 키 값을 대화, 파일, 커밋, 빌드 스크립트에 쓰지 않습니다
잡 하나는 돈입니다. 접수된 잡은 시작한 분마다 과금됩니다. 같은 요청을 되풀이하지 말고 status로 확인합니다. 재시도가 필요하면 idempotency_key를 같은 값으로 보내 중복 접수를 막습니다
끝났으면 로그를 파일로 받습니다. logs 도구는 전체 로그를 응답에 넣지 않고 파일로 씁니다. 실패 원인은 failure_summary와 tail에서 먼저 찾습니다
기다리는 쪽을 정합니다. build에 wait: true를 주면 진행 알림(notifications/progress)으로 로그가 흐르고 끝나야 응답이 옵니다. 긴 잡은 wait: false로 접수한 뒤 status로 봅니다
멈출 때는 cancel. 필요 없어진 잡은 바로 취소합니다. 이미 시작한 분까지만 과금됩니다
대기열은 오류가 아닙니다. status가 queued이고 queued_reason이 tier_concurrency_limit이면 조직의 동시 실행 한도에 걸려 차례를 기다리는 중입니다. capacity이면 빈 슬롯을 기다리는 중입니다
한도 응답은 종류를 나눕니다. tier_concurrency_limit(429)만 retry_after_s 뒤 재시도가 뜻이 있고, 402 계열(insufficient_credit, workspace_spend_limit, tier_monthly_limit)은 재시도로 풀리지 않습니다

응답에서 봐야 할 필드

상황	필드
잡이 끝났는지	`status`가 `succeeded`, `failed`, `cancelled`, `credit_exhausted`, `platform_error`, `timed_out` 중 하나
성공 여부	`exit_code`(0이면 성공)
얼마 썼는지	`billed_minutes`, `amount_display`
잔액이 적은지	`credit_low`가 있으면 사람에게 알림, `credits`의 `low`
왜 거절됐는지	`error.code`, `error.user_message`
다음에 부를 도구	`next.tool`, `next.arguments`

저장소 안내 파일에 적을 예

## XenoCI 빌드
- macOS 빌드와 테스트는 MCP 서버 xenoci의 build 도구로 돌린다. script는 bash ci.sh, artifacts는 ["TestResults.xcresult"]
- 결과는 status로 확인하고 실패하면 logs로 로그를 받아 failure_summary부터 읽는다
- 잔액이나 한도 오류(user_message가 있는 오류)는 그대로 사람에게 전하고 결제는 시도하지 않는다
- 같은 커밋을 두 번 빌드하지 않는다. 재시도는 idempotency_key를 같은 값으로 보낸다

다음 단계

MCP 서버: 도구 입력과 응답 전체
지출 한도: 에이전트가 쓸 수 있는 금액에 상한 두기