Skip to main content
Glama

@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.17

  • A 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=true

Set 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 in assert.config.json)

  • ASSERT_PROJECT_ID: optional default project ID

  • ASSERT_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.json

  • assert.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 do

  • url: string — the starting URL

  • project_id?: string

  • save?: 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?: string

  • markdown?: string

  • project_id?: string

  • request_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?: string

  • cursor?: string

  • limit?: 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_KEY

  • SCENARIO_NOT_FOUND

  • RUN_NOT_FOUND

  • VALIDATION_ERROR

  • UPSTREAM_ERROR

License

MIT

Available Tools

4 tools
assert_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

    A4.3/5.0

    Scored across 4 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers