MCP Tools | AX Documentation

The MCP server mirrors the CLI nouns: same ids, same vocabulary. Org-scoped tools use the current MCP org (see mcp_org tools) unless you pass an org_id override. Arguments marked required must be supplied; everything else is optional.

Experiment tools

Tool	What it does	CLI equivalent
`experiment_list`	List experiments the org can access.	`ax experiment list`
`experiment_view`	One experiment's metadata, axes, and run counts.	`ax experiment view`
`experiment_versions`	List stored version fingerprints.	`ax experiment versions`
`experiment_pull`	Return stored YAML (latest or a version).	`ax experiment pull`
`experiment_push`	Validate and push a YAML version without running.	`ax experiment push`
`experiment_run`	Submit runs for a registered experiment.	`ax experiment run <id>`
`experiment_query`	Query results in experiment scope.	`ax experiment query`

experiment_list filters with search, owner, agents, models, products, environments, updated_since (RFC 3339), and limit. Same-axis values OR; different axes AND.

experiment_run accepts version, repeat, exact variant_ids, the axis selectors (prompt_ids, agents, models, product_ids, environment_ids), registered flags, and mock. Selectors are a union; no selector runs every variant. The response pins the version and returns its fingerprint, ordinal, selected variant ids, and the run request id.

experiment_query takes required experiment_id plus either raw sql (scoped to the experiment) or the experimental modeled fields (metrics, ordered group_by, stat (only mean today), dimension filters, version, and dimensions discovery; the surface may change). Both modes support limit (default 100, cap 1,000), dry_run, and save ({heading, slug?, description?, labels?, force?}); dry_run, save, and dimension discovery are mutually exclusive. Metrics are testPassRate, testsPassed, testsFailed, cost, wallClockTime, tokens, toolCalls, toolFailures.

Run tools

Tool	What it does	CLI equivalent
`run_list`	List runs with experiment, version, dimension, and status filters.	`ax run list`
`run_view`	View a run request or one run, optionally with tests.	`ax run view`
`run_cancel`	Cancel queued or running work for a request.	`ax run cancel`
`run_query`	Read-only SQL scoped to one run.	`ax run query`

run_list accepts experiment_id, version_scope, the dimension filters, exact variant_ids, statuses, created_by_ids, status_updated_since (when the run entered its current status, not creation), and limit.

run_view takes a request id or composite run id. Set tests: true for every captured test, or test_name for one test's exit code, duration, and output tails (composite run ids only; not both).

run_query takes required composite run_id and sql, plus limit, dry_run, and save with the same semantics as experiment_query.

Insight tools

Tool	What it does	CLI equivalent
`insight_list`	List insight metadata.	`ax insight list`
`insight_create`	Create a saved SQL insight.	`ax insight create`
`insight_view`	Execute an insight, or return its stored SQL.	`ax insight view`
`insight_edit`	Update heading, SQL, description, or labels.	`ax insight edit`
`insight_delete`	Delete by slug or id (idempotent).	`ax insight delete`

insight_create takes required heading and sql, plus slug, description, labels, and force (overwrite mutable content on slug collision; slugs are immutable). insight_view executes live unless sql_only: true. insight_edit is presence-aware: an empty description or labels array clears the field (clear_labels also works).

Secret tools

Tool	What it does	CLI equivalent
`secret_set`	Create or overwrite one secret; returns metadata, never the value.	`ax secret set`
`secret_list`	List slugs and audit metadata; never values.	`ax secret list`
`secret_delete`	Delete one secret by slug.	`ax secret delete`

Org context and CLI auth

Tool	What it does	CLI equivalent
`mcp_org_list`	List orgs available to the MCP user.	`ax org list`
`mcp_org_get_current`	The org context org-scoped tools use.	`ax org view`
`mcp_org_set_current`	Change that org context.	`ax org switch`
`cli_auth_start`	Mint a one-time code that signs in the local CLI.	`ax auth connect --code`

Legacy tools

Kept for compatibility; prefer experiment_query, run_query, and insight_* for new agent workflows.

Tool	What it does	Use instead
`results_query`	Org-wide read-only SQL.	`experiment_query` / `run_query`
`results_scatter`	Deterministic per-run point sample (capped at 2,000; `totalPoints` / `truncated` disclose sampling).	`experiment_query`
`results_share`	Mint a filtered public share URL (anyone with the URL can view).	No v0.6 equivalent yet
`analyze_`, `findings_`	Guided trace-analysis and persisted findings.	A fuller MCP refresh is planned

Not in MCP

Local authoring (ax experiment create / validate / schema / variants) and file staging stay CLI-side: an experiment_run whose registered YAML declares files: will fail; pull the YAML and use the CLI's --file. There is no watch tool (poll run_view with the request id), and insight export is a client-side CLI operation; agents can consume the structured rows the query and insight tools return.

Search documentation