MCPLab

CLI

Command Reference

All mcplab commands and their flags in one place.

mcplab run

Run evaluation scenarios against one or more eval configs.

  • -c, --config <path> — Path to eval.yaml or a directory of eval configs. Required (or use --interactive).
  • -s, --scenario <id> — Run a single scenario by ID. Repeatable to run several.
  • -n, --runs <count> — Number of variance runs per scenario. Default: 1.
  • --agents <agents> — Comma-separated list of agent IDs to test.
  • --agents-all — Run all agents configured in the eval config plus any loaded from the library.
  • --interactive — Prompt for config path and agents at the terminal.
  • --bail — Stop after the first failed config when --config points to a directory.
  • --run-note <text> — Human-readable note attached to run metadata. Max 500 chars.
  • --runs-dir <path> — Output directory for run artifacts. Default: mcplab/results/evaluation-runs.
  • --oauth-token <server=token> — Pre-obtained OAuth bearer token for a named server. Repeatable.
  • --server-override-all <serverRef[,serverRef...]> — Override MCP server refs for all selected scenarios (runtime only).
  • --server-override <scenarioId=serverRef[,serverRef...]> — Override MCP server refs for one scenario. Repeatable. Higher priority than --server-override-all.
  • --open-browser — Open browser to the MCPLab UI when OAuth authentication is required.
usage
npx @inspectr/mcplab run [options]

mcplab results

Query evaluation run artifacts with LLM-first structured outputs.

  • list — List run directories and basic run metadata.
  • show --run <runId> — Show a run in json or markdown.
  • index [--rebuild] — Build/refresh local results index under mcplab/results/.index.
  • search <query> — Search indexed results/trace/summary and return compact hits.
  • context --run <runId> --scenario <id> — Fetch focused excerpt, optionally with --around for trace line windows.
  • search defaults: --status all, --source results,trace,summary, --limit 10, --format json.
usage
npx @inspectr/mcplab results <subcommand> [options]

mcplab report

Regenerate report.html from an existing run directory.

  • --input <runDir> — Path to the run directory containing results.json. Required unless --interactive.
  • --runs-dir <path> — Directory containing run artifacts. Default: mcplab/results/evaluation-runs.
  • --interactive — Pick a run directory from an interactive list.
usage
npx @inspectr/mcplab report [options]

mcplab app

Start the local web UI and API bridge.

  • --evals-dir <path> — Directory for eval YAML files. Default: mcplab/evals.
  • --runs-dir <path> — Directory for run artifacts. Default: mcplab/results/evaluation-runs.
  • --tool-analysis-results-dir <path> — Directory for tool analysis reports. Default: mcplab/results/tool-analysis.
  • --libraries-dir <path> — Bundle root for shared servers, agents, and test cases. Default: mcplab.
  • --port <number> — Port to bind the server to. Default: 8787.
  • --host <host> — Host to bind. Default: 127.0.0.1.
  • --open — Open the browser automatically after startup.
  • --dev — Proxy frontend requests to a Vite dev server. API remains local.
  • --interactive — Prompt for host, port, and directory paths before startup.
usage
npx @inspectr/mcplab app [options]