MCP Setup

Assrt exposes AI-powered QA testing as native tools over the Model Context Protocol (MCP). Your coding agent (Claude Code, Cursor, Windsurf, VS Code) gets three tools it can call directly: run tests, generate test plans, and diagnose failures.

Install

Claude Code

claude mcp add assrt -- npx -y -p @m13v/assrt assrt-mcp

Restart Claude Code. You will see assrt in your MCP server list with three tools: assrt_test, assrt_plan, and assrt_diagnose.

Cursor / VS Code / Windsurf

Add to your editor's MCP config file (~/.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json, or VS Code settings):

{
  "mcpServers": {
    "assrt": {
      "command": "npx",
      "args": ["-y", "-p", "@m13v/assrt", "assrt-mcp"]
    }
  }
}

Authentication

On macOS, Assrt reads the Claude Code OAuth token from Keychain automatically. The token is read from the Claude Code-credentials keychain entry and authenticated via Authorization: Bearer with the anthropic-beta: oauth-2025-04-20 header.

On Linux or Windows (or if you prefer a separate key), set the ANTHROPIC_API_KEY environment variable instead.

Tools

Below is a quick overview of each tool. For full parameter details and response shapes, see the Tools Reference. For usage examples and common workflows, see Examples.

assrt_test

Run QA test scenarios against a URL. Launches a headless browser (1280x720 viewport), executes the test plan step by step using an AI agent, and returns a structured report with pass/fail results, assertions, evidence, and screenshots from each step.

The response includes JSON with passed, failedCount, scenarios[] (each with assertions and evidence), plus screenshots as image content blocks showing the browser state after each action.

assrt_plan

Auto-generate test scenarios by analyzing a URL. Launches a browser, takes screenshots at different scroll positions, reads the accessibility tree, and uses AI to create executable test cases.

Returns a test plan in #Case N: format that you can pass directly to assrt_test.

assrt_diagnose

Diagnose a failed test scenario. Analyzes the failure and provides root cause analysis, recommended fixes, and a corrected test scenario.

CLI

You can also run tests directly from the terminal or CI pipelines:

npx -y -p @m13v/assrt assrt run \
  --url http://localhost:3000 \
  --plan "#Case 1: Homepage loads
Navigate to the homepage.
Verify the main heading is visible."

Use --json for structured output and --plan-file to load scenarios from a file. Exit code 0 means all tests passed, 1 means failures.

Troubleshooting

• "No Claude Code credentials found": Run claude in your terminal and sign in. The OAuth token is stored in macOS Keychain under Claude Code-credentials.
• Browser not launching: Make sure Playwright browsers are installed: npx playwright install chromium
• macOS only for zero-auth: On Linux/Windows, set ANTHROPIC_API_KEY environment variable instead.