> For the complete documentation index, see [llms.txt](https://help.aximo.autify.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.aximo.autify.com/features-ko/cli/mcp-server.md). # MCP 서버 Aximo CLI의 `aximo mcp`는 stdio를 통해 MCP(Model Context Protocol) 서버를 실행하여, 기록된 세션과 테스트 케이스를 Claude Code, Claude Desktop, Cursor 등 MCP 지원 클라이언트에 공개합니다. ## 전제 조건 1. CLI를 설치합니다. ```bash npm i -g @autifyhq/aximo-cli ``` 2. API 키를 설정합니다. API 키가 아직 없다면 [API 키 관리](/features-ko/settings/api-key-management.md)를 참조하여 생성합니다. ```bash aximo configure ``` 또는 환경 변수 `AXIMO_API_KEY`를 설정합니다. `aximo mcp` 프로세스가 자격 증명을 직접 읽으므로, 클라이언트 설정 파일에 키를 기록할 필요가 없습니다. 3. `aximo` 명령이 `PATH`에 있는지 확인합니다. 클라이언트가 셸의 `PATH`를 상속하지 않고 실행되는 경우, `command`에 절대 경로를 지정합니다(`which aximo`로 확인할 수 있습니다). ## 클라이언트별 설정 절차 이용하는 클라이언트에 따라 다음 절차로 MCP 서버를 설정합니다. 키 이름과 설정 파일 위치만 다를 뿐 내용은 거의 동일합니다. ### Claude Code 터미널에서 다음 명령을 실행합니다(설정 파일 편집은 필요 없습니다). ```bash claude mcp add aximo -- aximo mcp ``` `--scope project`를 붙이면 저장소에 커밋되는 공유 `.mcp.json`에 기록되고, `--scope user`를 붙이면 모든 프로젝트에서 사용할 수 있습니다(기본값은 현재 프로젝트에만 적용되는 로컬 범위). `claude mcp list`로 등록을 확인할 수 있습니다. ### Claude Desktop `claude_desktop_config.json`을 편집하고(**설정** > **개발자** > **설정 편집**), 앱을 재시작합니다. * macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` * Windows: `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "aximo": { "command": "aximo", "args": ["mcp"] } } } ``` ### Cursor `~/.cursor/mcp.json`(전체 프로젝트 공통) 또는 `.cursor/mcp.json`(프로젝트 단위)에 Claude Desktop과 동일한 `mcpServers` 형식으로 추가합니다. **설정** > **MCP**에서 서버를 활성화합니다. ### Windsurf `~/.codeium/windsurf/mcp_config.json`에 동일한 `mcpServers` 형식으로 추가합니다. 또는 Cascade의 플러그 아이콘에서 **Configure MCP**를 사용합니다. ### VS Code(Copilot 에이전트 모드) `.vscode/mcp.json`(워크스페이스 단위)을 설정하거나 **MCP: Open User Configuration** 명령을 사용합니다. 최상위 키가 `mcpServers`가 아니라 `servers`인 점에 주의하십시오. ```json { "servers": { "aximo": { "type": "stdio", "command": "aximo", "args": ["mcp"] } } } ``` ### 기타 클라이언트 stdio를 지원하는 MCP 클라이언트라면 `command: aximo`, `args: ["mcp"]`를 지정하여 사용할 수 있습니다. Codex CLI는 `~/.codex/config.toml`의 `[mcp_servers.aximo]`에 `command = "aximo"`와 `args = ["mcp"]`를 설정합니다. ## 사용 가능한 도구 `aximo mcp`는 16개의 도구를 공개합니다. 읽기 전용이 10개, 테스트 케이스나 플랜을 생성·변경하는 쓰기 계열이 6개입니다. ### 읽기 전용 | 도구 | 내용 | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `aximo_list_projects` | API 키로 볼 수 있는 워크스페이스(프로젝트)를 나열합니다. | | `aximo_list_sessions` | 기록된 세션을 나열합니다. `projectId`, `caseId`, `status`로 필터링할 수 있습니다. | | `aximo_get_session` | 세션 1건의 상태, 요약, 건수, 비용을 가져옵니다. | | `aximo_get_session_messages` | 세션의 도구 호출과 어시스턴트 발화를 커서 페이지네이션으로 가져옵니다. | | `aximo_get_session_screenshots` | 세션의 스크린샷(서명된 URL)을 커서 페이지네이션으로 가져옵니다. | | `aximo_get_session_timeline` | 권장. 도구 호출과 스크린샷을 짝지은 시간순 단계 목록을 가져옵니다. | | `aximo_get_session_capture` | CDP 캡처 메타데이터(동작·이동·네트워크·콘솔·예외·스냅샷 트리거 이벤트 목록, 브라우저 컨텍스트, 스토리지 상태)를 가져옵니다. `snapshots[]`는 기본적으로 메타데이터만 포함하며, DOM/AX를 포함하려면 `includeSnapshots: 'full'`을 지정합니다. 조직에 CDP 캡처가 없거나 세션 실행 시 캡처가 꺼져 있었다면 404를 반환합니다. | | `aximo_get_session_snapshot` | `aximo_get_session_capture`의 `snapshots[]`에 있는 ID로 DOM + 접근성 트리 스냅샷을 1건 가져옵니다. | | `aximo_list_cases` | 워크스페이스에 저장된 테스트 케이스를 나열합니다. | | `aximo_get_case` | 저장된 테스트 케이스의 전체 시나리오 텍스트와 메타데이터를 가져옵니다. | ### 쓰기 | 도구 | 내용 | | ----------------------------- | ------------------------------------------------------------------------------------------ | | `aximo_create_case` | 워크스페이스에 테스트 케이스를 생성합니다(API 실행이 활성화된 상태로 생성되어 즉시 트리거할 수 있습니다). 새 `caseId`를 반환합니다. | | `aximo_delete_case` | 테스트 케이스를 영구히 삭제합니다. 속한 플랜에서는 제외되지만, 과거 실행 세션은 연결이 해제된 채로 남습니다. | | `aximo_save_session_as_case` | 완료된 세션을 재사용 가능한 테스트 케이스로 저장하고 둘을 연결합니다. 세션이 종료 상태이고 아직 케이스에 연결되지 않아야 합니다. `caseId`를 반환합니다. | | `aximo_create_plan` | 빈 테스트 플랜을 생성합니다. 새 `planId`를 반환합니다. | | `aximo_add_case_to_plan` | 플랜에 케이스를 추가합니다(플랜과 같은 워크스페이스의 케이스만 가능). | | `aximo_remove_case_from_plan` | 플랜에서 케이스를 제거합니다(멱등). | ## Playwright 익스포트 프롬프트 템플릿 세션에서 Playwright spec을 에이전트가 생성하도록 하려면 다음과 같은 프롬프트를 사용합니다. > Using the `aximo` MCP server, fetch `aximo_get_session_timeline` for session `` and write a Playwright test that reproduces the same flow. Selector priority: `getByRole(role, {name})` → `getByLabel(label)` → `getByTestId(value)` → `getByText(text)` → CSS only as a last resort. Start with `page.goto` from the first navigation. Emit `page.route(...)` mocks only for first-party XHRs visible in the timeline. timeline은 도구 이름·입력값·스크린샷과 함께 순서가 있는 동작을 에이전트에게 제공합니다. 더 정밀한 셀렉터가 필요하다면, 해당 실행에서 CDP 캡처가 활성화되어 있었을 때만 `aximo_get_session_capture`(개별 DOM/AX 스냅샷에는 `aximo_get_session_snapshot`)도 가져옵니다. 이를 위해서는 조직의 CDP 캡처 기능 플래그가 켜져 있고 세션이 캡처 활성화 상태로 기록되어 있어야 하며, 그렇지 않으면 404를 반환합니다. ## 진단 * 프로토콜 이외의 출력은 모두 stderr로 전송됩니다. stdout은 JSON-RPC 전용입니다. MCP 클라이언트 로그에 예기치 않은 출력이 섞여 있다면 대부분 무언가가 stdout에 쓰고 있는 것입니다. * API 키가 설정되지 않은 경우, stderr에 `aximo mcp: No API key configured. Run aximo configure ...`를 출력하고 종료 코드 1로 종료합니다. ## 스모크 테스트(MCP 클라이언트 불필요) ```bash env AXIMO_API_KEY=$AXIMO_API_KEY bash -c ' printf "%s\n%s\n%s\n" \ "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-06-18\",\"capabilities\":{},\"clientInfo\":{\"name\":\"smoke\",\"version\":\"0\"}}}" \ "{\"jsonrpc\":\"2.0\",\"method\":\"notifications/initialized\"}" \ "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\"}" \ | aximo mcp ' ``` 16개 도구가 모두 나열된 JSON-RPC 응답이 반환되면 성공입니다. ## 참고 자료 * [API 키 관리](/features-ko/settings/api-key-management.md)