Assert
The Assert MCP server lets AI coding agents generate, execute, and inspect end-to-end (E2E) browser tests.
Generate tests (
assert_generate): Describe a user flow in plain English with a starting URL to produce a ready-to-run test scenario in Assert Markdown format. Optionally save it to your project for reuse.Run tests (
assert_run): Execute a saved scenario by ID or provide ad-hoc Markdown directly. Runs are asynchronous and return arun_idfor polling. Supports idempotency via a client-suppliedrequest_id.Inspect results (
assert_status): Poll a run for its status and retrieve step-level pass/fail results, error messages, and screenshot URLs for failed steps.List saved scenarios (
assert_list): Browse all scenarios visible to your API key, with pagination and optional project ID filtering — useful for auditing existing coverage before generating new tests.
@assert-click/mcp
MCP server for Assert — lets your AI coding agent generate, run, and inspect E2E tests without leaving the chat.
Describe a user flow in plain English. Assert generates a Playwright test, executes it in a real browser, and returns step-level results and failure screenshots — all from a single tool call in Cursor, Claude, Windsurf, or any MCP-compatible agent.
Sign up free at assert.click to get your API key and project ID before using this package.
What your agent can do
Generate — describe a flow, get back a Markdown scenario ready to save and run
Run — execute a saved scenario or ad-hoc Markdown against a real Chromium browser
Inspect — fetch step-level pass/fail, error messages, and failure screenshot URLs
List — browse saved scenarios visible to the API key
Related MCP server: deploytest MCP server
Requirements
Node.js
>=18.17A project-scoped Assert key — get one at assert.click
Setup
1. Create assert.config.json in your repo:
{
"projectApiKey": "assert_project_key_here",
"projectId": "project_123"
}2. Add the MCP server to your agent config:
{
"mcpServers": {
"assert": {
"command": "npx",
"args": ["-y", "@assert-click/mcp"],
"env": {
"ASSERT_CONFIG": "/absolute/path/to/assert.config.json"
}
}
}
}That's it. Your agent now has access to all four Assert tools.
Private URLs
Targets such as localhost, 127.0.0.1, and LAN or VPN IP addresses are blocked by default.
Use a public URL unless the machine executing the Assert run is intentionally configured to allow private targets with:
ALLOW_PRIVATE_TARGETS=trueSet that on the machine or process running Assert. Do not put it in assert.config.json.
Environment variables
ASSERT_API_KEY: API key (alternative to storing it inassert.config.json)ASSERT_PROJECT_ID: optional default project IDASSERT_CONFIG: optional path to a config file or directory
Config files
The MCP server will look for these files from the current directory upward:
assert.config.jsonassert.config.local.json
assert.config.local.json is merged on top of assert.config.json.
If you prefer env-based secrets instead of committing the key:
{
"projectApiKeyEnv": "ASSERT_API_KEY",
"projectId": "project_123"
}Tools
assert_generate
Generate a Markdown scenario from a plain-English description.
Input:
description: string— what the user should be able to dourl: string— the starting URLproject_id?: stringsave?: boolean— save to the project (default: false)
Returns:
{
"scenario_id": "scenario_123",
"markdown": "URL: https://example.com/login\nSCENARIO: Login\nPROCESS:\n - Fill \"email\" with \"user@example.com\"\nEXPECT: Dashboard",
"saved": true
}assert_run
Execute a saved scenario or ad-hoc Markdown in a real browser.
Input:
scenario_id?: stringmarkdown?: stringproject_id?: stringrequest_id?: string
Exactly one of scenario_id or markdown must be provided.
Returns:
{
"run_id": "run_123",
"status": "queued",
"estimated_duration_seconds": null
}assert_status
Fetch step-level results for a run.
Input:
run_id: string
Returns:
{
"run_id": "run_123",
"status": "passed",
"duration_ms": 4200,
"steps": [
{
"description": "Fill email",
"status": "passed",
"error": null,
"screenshot_url": null
}
],
"failure_summary": null,
"full_log_url": null
}assert_list
List saved scenarios visible to the API key.
Input:
project_id?: stringcursor?: stringlimit?: number
project_id is currently reserved for future filtering support. The current API lists all scenarios visible to the API key.
Returns:
{
"scenarios": [
{
"id": "scenario_123",
"name": "Login flow",
"project_id": null,
"last_run_status": "passed",
"last_run_at": "2026-03-31T10:00:00.000Z",
"url": "https://example.com/login"
}
],
"next_cursor": null
}Errors
Errors are returned as structured JSON:
{
"error": {
"code": "INVALID_API_KEY",
"message": "The ASSERT_API_KEY is invalid or missing.",
"field": null
}
}Common codes:
INVALID_API_KEYSCENARIO_NOT_FOUNDRUN_NOT_FOUNDVALIDATION_ERRORUPSTREAM_ERROR
License
MIT
Available Tools
4 toolsassert_generateA
Generate a ready-to-run E2E test scenario in Assert Markdown format from a plain-English description. Optionally save it to Assert for later execution.
Inputs: description (required), url (required), project_id, save.
assert_listA
List existing E2E test scenarios saved in Assert. Use this to audit coverage before generating new tests. Supports filtering by project and pagination.
Inputs: project_id, cursor, limit.
assert_runA
Execute a test scenario and return a run ID. Accepts either a saved scenario_id or ad-hoc markdown. Runs are async — use assert_status to poll for completion.
Inputs: scenario_id, markdown, project_id, request_id.
assert_statusA
Poll a test run for its current status and step-level results. Returns pass/fail with actionable failure details and screenshot URLs for failed steps.
Inputs: run_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose with no overlap: generate creates tests, list retrieves existing ones, run executes tests, and status checks results. The descriptions explicitly differentiate their functions, making it easy for an agent to select the right tool without confusion.
All tool names follow a consistent 'assert_verb' pattern (assert_generate, assert_list, assert_run, assert_status), using snake_case and clear action verbs. This predictability enhances usability and reduces cognitive load for agents.
With 4 tools, the server is well-scoped for E2E test management, covering the full lifecycle: generate, list, run, and status check. Each tool earns its place without bloat, making the set efficient and focused on its domain.
The toolset provides complete CRUD-like coverage for E2E test scenarios: create (generate), read (list), execute (run), and monitor (status). There are no obvious gaps, as it supports both saved and ad-hoc tests with actionable feedback, enabling seamless agent workflows.
Maintenance
Related MCP Connectors
Browser-based QA for AI-built software. Test pages with real browsers via agents.
Write, run and check natural-language browser tests of your web app from your AI assistant.
Approved test intent, reviewed Playwright automation and run evidence, inside your editor.
Website checker for AI coding agents. Measures your site in a real browser, with evidence.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables automated end-to-end testing powered by Playwright where test cases are defined in natural language and executed by AI. Uses lightweight snapshot analysis with vision mode fallback for sophisticated testing scenarios.3Apache 2.0
- AlicenseAqualityDmaintenanceEnables AI agents to run reusable Playwright test fixtures against live deployments, providing structured test results, screenshots, and assertions.3MIT
- AlicenseAqualityCmaintenanceAI-native browser testing, directly from your coding agent.3MIT
- AlicenseAqualityBmaintenanceEnables AI assistants to create, run, autocorrect, and monitor Playwright tests for your app with a local dashboard, credential vault, and public status page.16MIT