GenClass

@genclass/mcp

Your coding agent can see the race, replay it, and prove the fix.

An MCP server for Claude Code and other coding agents. It connects to the pages of your app running on your machine (through @genclass/runtime's agent link) and gives the agent:

• What happened, in order. Every click, request and response, the order the responses were delivered, what each response wrote into the app's state, and uncaught errors with the click and request that led to them.
• Bugs that never throw. A response that overwrote newer data (the classic stale search result or lost edit), the same order submitted twice by two clicks, and the on-device model's own detections.
• Races found before users find them. genclass_explore runs your steps again with the network answering in different orders (and slower, if you like) and reports what ends differently from the run where responses came back in order.
• Proof. genclass_replay delivers the exact order that produced a bug again, before your fix (reproduced) and after it (not reproduced), and genclass_explain writes a Playwright test that fails while the bug is there.

By default everything stays on your machine (see Privacy). No dependencies. The server is free. For developers who want the loop run for them, GenClass runs it as a service under Enterprise: the MCP server, collector and dashboard hosted by GenClass or inside your network (genclass.dev/enterprise).

Install

Pick your client. Every block pins this release, so the client starts exactly this version; npx -y @genclass/mcp@0.2.2 config prints the same lines, and genclass_setup prints the block for the client it runs in.

Claude Code

As a plugin (the server, a prompt hook that brings new findings to each prompt, and the genclass skill with the procedure):

/plugin marketplace add genclass-dev/genclass-plugin

/plugin install genclass@genclass

Or the server alone (--scope project writes .mcp.json for everyone on the project; --scope user for all your projects). init also writes the skill to .claude/skills/genclass/SKILL.md (--no-skill leaves it out):

claude mcp add --scope project genclass -- npx -y @genclass/mcp@0.2.2

or: npx -y @genclass/mcp@0.2.2 init --hook (.mcp.json and the skill, plus the prompt hook in .claude/settings.json)

Or just the skill (no server): npx skills add genclass-dev/genclass-plugin. (genclass-dev/genclass-plugin is this plugin at a repository root, assembled from this package; the marketplace in genclass-dev/GenClass lists the same plugin.)

Claude Desktop

Settings, Developer, Edit Config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{

"mcpServers": { "genclass": { "command": "npx", "args": [ "-y", "@genclass/mcp@0.2.2" ] } } }

Cursor

or cursor://anysphere.cursor-deeplink/mcp/install?name=genclass&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBnZW5jbGFzcy9tY3BAMC4yLjIiXX0%3D

Or .cursor/mcp.json in the project (~/.cursor/mcp.json for all projects):

{

"mcpServers": { "genclass": { "command": "npx", "args": [ "-y", "@genclass/mcp@0.2.2" ] } } }

VS Code

or from a terminal:

code --add-mcp '{"name":"genclass","command":"npx","args":["-y","@genclass/mcp@0.2.2"]}'

Or .mcp.json at the workspace root (the portable format; .vscode/mcp.json takes the same entry under servers):

{

"mcpServers": { "genclass": { "command": "npx", "args": [ "-y", "@genclass/mcp@0.2.2" ] } } }

Codex CLI

As a plugin (the server and the genclass skill):

codex plugin marketplace add genclass-dev/genclass-plugin

codex plugin add genclass@genclass

Or the server alone:

codex mcp add genclass -- npx -y @genclass/mcp@0.2.2

Or ~/.codex/config.toml (.codex/config.toml in a trusted project). The first start downloads the package, so allow more than the default 10 seconds:

[mcp_servers.genclass]

command = "npx" args = ["-y", "@genclass/mcp@0.2.2"] startup_timeout_sec = 30

Gemini CLI

As an extension (the server and the genclass skill):

gemini extensions install https://github.com/genclass-dev/genclass-plugin

Or the server alone:

gemini mcp add genclass npx -- -y @genclass/mcp@0.2.2   # -s user: for all projects

Or .gemini/settings.json in the project (~/.gemini/settings.json for all projects):

{

"mcpServers": { "genclass": { "command": "npx", "args": [ "-y", "@genclass/mcp@0.2.2" ] } } }

Windsurf (Devin Desktop)

~/.codeium/windsurf/mcp_config.json (Windsurf), ~/.config/devin/mcp_config.json (Devin Desktop's Cascade agent; %APPDATA%\devin\mcp_config.json on Windows):

{

"mcpServers": { "genclass": { "command": "npx", "args": [ "-y", "@genclass/mcp@0.2.2" ] } } }

Devin CLI and Devin Desktop's Devin Local agent:

devin mcp add -s user genclass -- npx -y @genclass/mcp@0.2.2

Cline

cline mcp add genclass --yes -- npx -y @genclass/mcp@0.2.2

Or MCP Servers, Configure, Configure MCP Servers (~/.cline/data/settings/cline_mcp_settings.json):

{

"mcpServers": { "genclass": { "command": "npx", "args": [ "-y", "@genclass/mcp@0.2.2" ] } } }

Goose

goose://extension?cmd=npx&arg=-y&arg=%40genclass%2Fmcp%400.2.2&id=genclass&name=genclass&description=Find%20race%20conditions%20by%20reordering%20responses%2C%20replay%20one%2C%20prove%20the%20fix (open it to install), or goose configure (Add Extension, Command-line Extension, command npx -y @genclass/mcp@0.2.2), or ~/.config/goose/config.yaml:

extensions:

genclass: type: stdio name: genclass enabled: true cmd: npx args: ["-y", "@genclass/mcp@0.2.2"] env_keys: [] envs: {} timeout: 300

Zed

~/.config/zed/settings.json (.zed/settings.json in the project), or Settings, AI, MCP Servers, Add Server:

{

"context_servers": { "genclass": { "command": "npx", "args": [ "-y", "@genclass/mcp@0.2.2" ] } } }

JetBrains IDEs

AI Assistant: Settings, Tools, AI Assistant, Model Context Protocol (MCP), Add, then this JSON. Junie: .junie/mcp/mcp.json in the project (~/.junie/mcp/mcp.json for all projects), same JSON:

{

"mcpServers": { "genclass": { "command": "npx", "args": [ "-y", "@genclass/mcp@0.2.2" ] } } }

OpenCode

opencode.json in the project (~/.config/opencode/opencode.json for all projects), or opencode mcp add:

{

"$schema": "https://opencode.ai/config.json", "mcp": { "genclass": { "type": "local", "command": [ "npx", "-y", "@genclass/mcp@0.2.2" ], "enabled": true } } }

Any other MCP client: a stdio server, command npx, arguments -y @genclass/mcp@0.2.2, no environment variables required.

The genclass skill

The server's instructions (sent when it connects) tell the agent when to reach for GenClass: the symptom words ("sometimes", "randomly", "only in production", "on slow connections", a value that "flips back", stale or old results, lost edits, double submits, sideways scrolling), the code changes that call for an explore, the scan before a UI change is done, and the first call for each. The procedure (the explore arguments, the Playwright pairing, how to read a report, what to say when done, what to do when the tools are missing) is the genclass skill, plugin/skills/genclass/SKILL.md. Three ways to get it:

• the plugin installs it with the server and the hook;
• npx -y @genclass/mcp@0.2.2 init writes it to .claude/skills/genclass/SKILL.md in the project (--no-skill leaves it out). The written file carries a genclass:init marker line: a rerun replaces a file with the marker and leaves one without it (yours, or edited), and says which;
• npx skills add genclass-dev/genclass-plugin (the skills CLI: Codex, Cursor, Copilot, Gemini CLI, Claude Code and others) or gh skill install genclass-dev/genclass-plugin genclass (GitHub CLI 2.90 or later, for Copilot) installs the skill alone, with no server (the skill then says how to add one). npx skills add genclass-dev/GenClass installs the same file from this repository's root copy, skills/genclass/SKILL.md.

To remove it: delete .claude/skills/genclass/ (or the directory the skill tool wrote to); with the plugin, /plugin uninstall genclass@genclass.

Then connect the app's development build (once). The agent link needs the newest runtime line, @genclass/runtime 0.3.0-beta.1 or later: npm install @genclass/runtime@0.3.0-beta.5, the version this release was tested with (npm's latest is the older 0.2.x, which has no agent entry):

import { GenClass } from "@genclass/runtime";

import { connectAgent } from "@genclass/runtime/agent";

// Next.js: process.env.NODE_ENV === "development" if (import.meta.env.DEV) { const rt = GenClass.init(); connectAgent(rt); }

A production build drops all of this (measured with Vite, esbuild and Next.js 15; the package's sideEffects list names neither entry). Load a page of the dev server and ask the agent for genclass_status. The agent can also ask genclass_setup, which reads your package.json and shows the lines for your framework.

The skill and the server's instructions tell the agent to show you each of these and wait for your yes: running that install or adding those lines; npx playwright install chromium and npm i -D playwright; genclass_scan with hosted: true; writing a fix or a test when you only asked what broke.

What the agent does with it

you:    the search results are sometimes for an older query; find out why and fix it

agent: genclass_findings → f1 [stale-write] /search: the response to GET /api/search "?q=reac" overwrote "search.results" after a newer GET /api/search had already written it genclass_explain f1 → steps, delivery order, a replay, a regression test genclass_replay arm f1 → (loads the page, types) → result: REPRODUCED (fixes the handler to keep only the latest answer, adds the test) genclass_replay arm f1 → result: not reproduced genclass_explore start {slow_ms: 600} → 9 runs → report: no race

On a real page in headless Chromium (the package's end-to-end check), explore found that race in 5 of 6 reordered runs of a page that never showed it on the developer's fast backend, the generated test failed on the buggy page and passed on the fixed one, and explore on the fixed page reported nothing. Details: docs/runtime/AGENT.md.

What it calls a race is what the page shows or writes, not the noise of a running page: an age that moved by