> 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/cli/mcp-server.md). # MCP server The Aximo CLI's `aximo mcp` command runs a Model Context Protocol (MCP) server over stdio, exposing your recorded sessions and test cases to MCP-capable clients such as Claude Code, Claude Desktop, and Cursor. ## Prerequisites 1. Install the CLI. ```bash npm i -g @autifyhq/aximo-cli ``` 2. Configure an API key. If you don't have one yet, see [API key management](/settings/api-key-management.md) to create one. ```bash aximo configure ``` Or set the `AXIMO_API_KEY` environment variable. The `aximo mcp` process reads the credential itself, so you never need to put a key in a client's config file. 3. Make sure `aximo` is on your `PATH`. If your client launches without inheriting your shell's `PATH`, use an absolute path for `command` (run `which aximo` to find it). ## Client-specific setup Set up the MCP server with the steps for the client you use. The entry is nearly identical everywhere — only the key name and file location change. ### Claude Code One command, no file editing: ```bash claude mcp add aximo -- aximo mcp ``` Add `--scope project` to write a shared `.mcp.json` checked into the repo, or `--scope user` to make it available across all your projects (the default scope is local to the current project). Verify with `claude mcp list`. ### Claude Desktop Edit `claude_desktop_config.json` (**Settings** > **Developer** > **Edit Config**), then restart the app. * macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` * Windows: `%APPDATA%\Claude\claude_desktop_config.json` ```json { "mcpServers": { "aximo": { "command": "aximo", "args": ["mcp"] } } } ``` ### Cursor Add the following to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project), using the same `mcpServers` shape as Claude Desktop. Enable the server under **Settings** > **MCP**. ### Windsurf Add the following to `~/.codeium/windsurf/mcp_config.json`, using the same `mcpServers` shape. Or use **Cascade** > plug icon > **Configure MCP**. ### VS Code (Copilot agent mode) Configure `.vscode/mcp.json` (workspace) or use the **MCP: Open User Configuration** command. Note that the top-level key is `servers`, not `mcpServers`. ```json { "servers": { "aximo": { "type": "stdio", "command": "aximo", "args": ["mcp"] } } } ``` ### Other clients Any MCP client that speaks stdio works — give it `command: aximo`, `args: ["mcp"]`. Codex CLI uses `~/.codex/config.toml` (`[mcp_servers.aximo]` with `command = "aximo"` and `args = ["mcp"]`). ## Available tools `aximo mcp` exposes 16 tools: 10 read-only and 6 that create or change test cases and plans. ### Read | Tool | What it does | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `aximo_list_projects` | List workspaces (projects) the API key can see. | | `aximo_list_sessions` | List recorded sessions; filter by `projectId`, `caseId`, `status`. | | `aximo_get_session` | Get status, summary, counts, and costs for one session. | | `aximo_get_session_messages` | Cursor-paginated tool calls and assistant turns for a session. | | `aximo_get_session_screenshots` | Cursor-paginated screenshots (presigned URLs). | | `aximo_get_session_timeline` | Recommended. A merged, ordered step list, each pairing a tool call with its screenshots. | | `aximo_get_session_capture` | CDP capture metadata: ordered events (actions, navigations, network, console, exceptions, snapshot triggers), browser context, and storage state. `snapshots[]` is metadata-only by default — pass `includeSnapshots: 'full'` to inline DOM/AX. Returns 404 if the org lacks CDP capture or the session ran without it. | | `aximo_get_session_snapshot` | Fetch one DOM + accessibility-tree snapshot by ID (from `aximo_get_session_capture`'s `snapshots[]`). | | `aximo_list_cases` | List saved test cases in a workspace. | | `aximo_get_case` | Get the full scenario text and metadata for a saved test case. | ### Write | Tool | What it does | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `aximo_create_case` | Create a saved test case in a workspace (API-enabled, so it's triggerable immediately). Returns the new `caseId`. | | `aximo_delete_case` | Delete a test case permanently. It's removed from any plans; past run sessions are kept but detached. | | `aximo_save_session_as_case` | Persist a finished session as a reusable test case and link the two. The session must be terminal and not already linked. Returns `caseId`. | | `aximo_create_plan` | Create an empty test plan. Returns the new `planId`. | | `aximo_add_case_to_plan` | Append a case to a plan (must be in the same workspace as the plan). | | `aximo_remove_case_from_plan` | Remove a case from a plan. Idempotent. | ## Playwright export prompt template When you want an agent to generate a Playwright spec from a session, prompt it roughly like this: > 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. The timeline gives the agent ordered actions with tool name, inputs, and screenshots. For higher-fidelity selectors, also fetch `aximo_get_session_capture` (and `aximo_get_session_snapshot` for individual DOM/AX snapshots) when CDP capture was enabled for the run — this requires the org's CDP capture feature flag and that the session was recorded with capture on, otherwise the call returns 404. ## Diagnostics * All non-protocol output goes to stderr — stdout is reserved for JSON-RPC. If you see unexpected output in your MCP client's logs, it's almost always something writing to stdout. * A missing API key exits with code 1 and prints `aximo mcp: No API key configured. Run aximo configure ...` to stderr. ## Smoke test (no MCP client required) ```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 ' ``` Expect a JSON-RPC response listing all 16 tools. ## Further reading * [API key management](/settings/api-key-management.md)