How do I use cowork-qa-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@cowork-qa-mcp Start a session to find the cheapest 14-inch MacBook Pro on apple.com" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

cowork-qa-mcp

by inSideos-designs

Overview Schema Related Servers Score Discussions

JavaScript

Local

cowork-qa-mcp

demo

A Model Context Protocol server that gives an LLM a real Chromium browser, records every action it takes toward a stated goal, and hands back a structured trace so the LLM (or a second LLM) can decide whether the goal was actually achieved.

Built on Playwright. Five tools, one binary, no cloud dependency.

Why

Most browser-tool MCP servers are stateless — the LLM clicks, gets HTML back, repeats. There's no record of what happened, no way to grade the run after the fact, and no goal context.

cowork-qa-mcp flips that:

Every session starts with a goal in plain English.
Every action (goto, click, fill, press, eval) is recorded with timestamps, the URL after, and the page's aria-snapshot.
When the session ends, a JSON trace is persisted to disk and exposed via a single qa_get_trace call.

The orchestrating LLM can then reason over the trace ("did this run actually fulfill the goal, or did it click the wrong button?") instead of trusting the run-time chatter.

Related MCP server: Playwright MCP

Tools

Tool	What it does
`session_start`	Open a fresh tab, optional starting URL, return a session id
`session_act`	Run one of: `goto`, `click`, `fill`, `press`, `eval`. Records the step.
`session_observe`	Return current URL + full aria-snapshot of the page
`session_end`	Close the tab, persist the trace to disk, return the file path
`qa_get_trace`	Return the goal, every step, final URL, and final aria-snapshot — formatted for an LLM to read

Install

Requires Node 20+. The package is on npm — no clone needed.

# Try it once, no install
npx cowork-qa-mcp

# Or install globally
npm install -g cowork-qa-mcp

The first install pulls Chromium via Playwright's postinstall (~150 MB).

Wire into your MCP-compatible client

Claude Code

claude mcp add cowork-qa --scope user -- npx -y cowork-qa-mcp

To watch the browser instead of running headless:

claude mcp add cowork-qa --scope user \
  -e COWORK_QA_HEADED=1 \
  -- npx -y cowork-qa-mcp

Verify with /mcp inside a fresh claude session — you should see cowork-qa ✓ connected and 5 tools.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "cowork-qa": {
      "command": "npx",
      "args": ["-y", "cowork-qa-mcp"]
    }
  }
}

Cursor / Windsurf / other MCP clients

Any client that speaks the MCP stdio transport works. Point its server config at npx -y cowork-qa-mcp.

From source (for development)

git clone https://github.com/inSideos-designs/cowork-qa-mcp.git
cd cowork-qa-mcp
npm install
npm run build
node dist/server.js   # stdio server, expects an MCP client

MCP Registry

This server is also published on the official MCP Server Registry as io.github.inSideos-designs/cowork-qa — clients that auto-discover from the registry will find it without any manual config.

Environment variables

Variable	Default	Purpose
`COWORK_QA_HEADED`	unset (headless)	Set to `1` to launch Chromium with a visible window
`COWORK_QA_DATA`	`<cwd>/.cowork-qa`	Directory where `<session-id>.json` traces are written

Usage example

A typical end-to-end loop the orchestrating LLM runs:

session_start({ goal: "find the cheapest 14\" MacBook Pro on apple.com",
                url: "https://www.apple.com/shop/buy-mac/macbook-pro" })
  → { session_id: "abc-123" }

session_observe({ session_id: "abc-123" })
  → URL + aria-snapshot

session_act({ session_id: "abc-123", action: "click",
              target: "button:has-text('Continue')" })

# ... more acts / observes ...

session_end({ session_id: "abc-123" })
  → { steps: 7, trace_path: "~/.cowork-qa/abc-123.json" }

qa_get_trace({ session_id: "abc-123" })
  → Goal: ...
    Steps (7 total): ...
    Final URL: ...
    Final aria-snapshot: ...

Trace format

Each trace is a JSON file:

{
  "session_id": "abc-123",
  "goal": "...",
  "steps": [
    {
      "t": 142,
      "action": "click",
      "args": { "target": "...", "value": null },
      "url_after": "...",
      "aria_after": "..."
    }
  ],
  "final": { "url": "...", "aria": "..." },
  "path": "/.../abc-123.json"
}

Limitations / known quirks

session_observe calls don't show up in the trace's step count — only session_act calls do. The final aria-snapshot is captured at session_end.
eval runs the JS expression but doesn't return the value to the caller — only side effects on the page are observable.
One Chromium process is shared across all sessions in a server instance; each session gets its own context (cookies, etc. are isolated).
Selectors are passed straight to Playwright. CSS, text-selectors (button:has-text("Send")), and role= selectors all work.

License

MIT — see LICENSE.

Contributing

PRs welcome. Keep it small: this is meant to stay a thin, auditable server.

Available Tools

5 tools

qa_get_traceA

Return the full recorded trace (goal, every step, final URL, final aria-snapshot) so the calling LLM can judge whether the goal was achieved. Call session_end first.

ParametersJSON Schema

Name	Required	Description	Default
`session_id`	Yes

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden for behavioral transparency. It discloses what the trace includes and the prerequisite ordering, but does not explicitly state whether the operation is read-only, what happens if session_end has not been called, or any side effects. The name 'get' implies read-only, but explicit disclosure is absent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, each earning its place. The first sentence states the core action and output contents, while the second provides a necessary ordering instruction. No unnecessary words or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple retrieval tool with one obvious parameter and no output schema, the description is fairly complete: it covers what is returned (goal, steps, URL, snapshot) and the required prerequisite. It does not cover error cases or what to do if the trace is unavailable, but these are likely edge cases that can be inferred or discovered at runtime.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and the description does not mention the session_id parameter at all. While the parameter name is self-explanatory, the description could have clarified that it expects the session ID from session_start or session_end, or provided format details. The lack of any parameter guidance fails to compensate for the sparse schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Return the full recorded trace') and specifies the exact contents (goal, every step, final URL, final aria-snapshot). It distinguishes itself from sibling tools by focusing on post-session retrieval for evaluation, not session management or actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The instruction 'Call session_end first' provides a clear prerequisite for when to use the tool, implying it should be used after session completion. However, it does not explicitly contrast with sibling tools or state when not to use it, though the context of sibling names makes the role obvious.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

session_actB

Perform a browser action in a session: goto | click | fill | press | eval.

ParametersJSON Schema

Name	Required	Description
`value`	No	Value for fill.
`action`	Yes
`target`	No	Selector for click/fill, URL for goto, key for press, JS expression for eval.
`session_id`	Yes

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of disclosing behavioral traits. It only lists the actions and does not describe side effects (e.g., navigation, page mutations), failure modes, waiting behavior, or how 'eval' interacts with the page context. This is minimal transparency for a tool that performs potentially impactful browser actions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that states the purpose and the supported actions in a compact, readable list. There is no redundant information, making it highly concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (4 parameters, no output schema, no annotations), the description is too sparse. It does not explain what each action does, expected formats for target beyond schema snippets, or any return values or error behavior. Sibling tools hint at session context, but the description alone is insufficient for an agent to fully understand the tool's behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 50%, with value and target described in the schema. The description adds no meaning beyond what the schema already provides; it merely repeats the action enum. It does not clarify relationships like which parameters apply to which actions or how session_id is used, so it falls short of compensating for the undocumented parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('Perform') and resource ('browser action'), and enumerates the specific actions (goto, click, fill, press, eval). This clearly differentiates it from sibling tools like session_start, session_observe, session_end, and qa_get_trace, which handle other aspects of the session lifecycle.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool's usage (when you need to perform a listed browser action) but does not explicitly state when to use it versus alternatives such as session_observe for inspecting state or session_start for creating a session. No exclusions or comparative guidance is provided, so usage is implied rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

session_endA

Close the session, persist the trace to disk, and return the path.

ParametersJSON Schema

Name	Required	Description	Default
`session_id`	Yes

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Since no annotations are provided, the description carries the full burden of disclosing behavior. It transparently mentions the closing of the session, persistence to disk, and returning the path. It does not state that the session becomes invalid after closing, but 'close' implies this, and the key side effects are covered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured sentence that sequentially lists the actions: close, persist, and return. Every word adds value, and it is instantly readable. There is no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool with no output schema, the description sufficiently covers the purpose, side effects, and return value. It could be more explicit about the session_id parameter and the irreversible nature of closing, but it provides enough information for an agent to invoke the tool correctly in most contexts.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has a single required parameter, session_id, with no description, and schema coverage is 0%. The description indirectly maps the parameter by referring to 'the session', suggesting that session_id identifies which session to close. This provides some context but does not explicitly describe the parameter's format or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action ('Close the session') and its side effects ('persist the trace to disk', 'return the path'). It distinguishes this from sibling tools like session_start, session_act, session_observe, and qa_get_trace by focusing on the terminal action of a session.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is to be used when ending a session and saving its trace. While it does not explicitly mention alternatives or exclusions, the context is clear: 'Close the session' is a definitive action that an agent would choose when finishing a session. The sibling tools cover other phases, making the usage context evident.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

session_observeA

Return the current URL and aria-snapshot of the session's page.

ParametersJSON Schema

Name	Required	Description	Default
`session_id`	Yes

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It does not explicitly state that the operation is read-only, nor does it describe error behavior for invalid session IDs or inactive sessions. The word 'return' suggests non-mutation, but other behavioral aspects are undisclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no unnecessary words. It is front-loaded with the verb and clearly states the output components, making it extremely concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with one parameter and no output schema, the description adequately specifies the return value (URL and aria-snapshot). It does not detail the output format or error handling, but given the tool's simplicity, the description is nearly complete, with only minor missing context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate. It references 'session's page' which implies session_id identifies a session, but it does not explain what a session_id is, its format, or how to obtain it. This is minimal semantic addition beyond the raw parameter name.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb 'return' with a clear resource: 'current URL and aria-snapshot of the session's page.' This clearly differentiates it from sibling tools like session_start and session_act, which focus on lifecycle actions, and qa_get_trace, which retrieves traces.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool (to observe the page state) but does not explicitly state when not to use it or mention alternatives. It lacks guidance on prerequisites such as needing an active session, which is left to the user to infer.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

session_startA

Open a fresh browser tab and start recording a goal-driven session.

ParametersJSON Schema

Name	Required	Description	Default
`url`	No	Optional starting URL.
`goal`	Yes	Plain-English goal the agent will try to accomplish.

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry behavioral disclosure. It discloses that a fresh tab is opened and that recording starts, which is useful. However, it does not explain state resets (e.g., if a session already exists), navigation behavior for the optional URL, or any return values or session identifiers.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is front-loaded with the primary action ('Open a fresh browser tab') and has no filler or redundant phrases. It earns its place entirely.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The core action is covered, but the tool has no output schema and no annotations, so the description should explain what happens after starting (e.g., whether a session ID is returned, how the session continues). The relationship to sibling tools is also omitted, which is important for an orchestration flow.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% because both parameters have descriptions, so the baseline is 3. The description adds only a minor hint that the goal is central by calling the session 'goal-driven', but it does not provide additional semantic detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'Open a fresh browser tab and start recording a goal-driven session.' This clearly identifies the tool as the session initializer, distinguishing it from siblings like session_act and session_observe.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when starting a new session, but it does not explicitly state when to use this tool versus alternatives, nor does it mention any preconditions or that subsequent tools (session_act, session_observe) should follow. Guidance is only implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

5 tool updatesv0.1.1Aug 4, 2026
- First observedqa_get_trace
- First observedsession_act
- First observedsession_end
- First observedsession_observe
- First observedsession_start

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.9/5.0

Disambiguation5/5

Each tool maps to a distinct phase of the session lifecycle (start, act, observe, end, retrieve trace), leaving no ambiguity about which tool to use. The purposes are clearly separated and non-overlapping.

Naming Consistency4/5

Four of five tools follow a consistent session_<verb> pattern (start, act, observe, end), but qa_get_trace breaks this with a qa_ prefix and a different verb style. The deviation is minor and the intent remains clear.

Tool Count5/5

The tool count of 5 is well-suited for a QA automation server, covering the essential workflow without superfluous or redundant tools. Each tool earns its place in the session lifecycle.

Completeness5/5

The tool set provides full lifecycle coverage from session start through actions, observation, ending, and trace retrieval. There are no obvious gaps for the intended goal-driven QA workflow.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

WebRun Browser Automation A
ai.webrun
Run multi-step tasks in a real Chrome browser: persistent environments, live view, human takeover.
Browser Automation Web Scraping
211
playwright-mcp-server A
com.thenextgennexus
Headless browser primitives for AI agents when sites need real JS rendering.
Browser Automation Web Scraping
175
browserbasehq-mcp-browserbaseOAuth
ai.smithery
Provides cloud browser automation capabilities using Stagehand and Browserbase, enabling LLMs to i…
Browser Automation Web Scraping Agent Orchestration
23,406
agent-web-actions
com.trycloudflare.plates-spread-materials-optimum
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
Browser Automation Agent Orchestration
2

Related MCP Servers

MCP-Server-Playwright
Browser Automation Web Scraping
VikashLoomba
A
license
B
quality
B
maintenance
Enables LLMs to interact with web pages, take screenshots, and execute JavaScript in a real browser environment
Updated a year ago (2025-06-05 21:48 UTC)
10
277
299
MIT
Playwright MCP
Browser Automation Web Scraping
ProvarTesting
A
license
Not graded
quality
D
maintenance
Provides browser automation capabilities using Playwright, allowing LLMs to interact with web pages through structured accessibility snapshots without needing vision models.
Updated 10 months ago (2025-10-27 07:28 UTC)
6,364,011
1
Apache 2.0
Playwright Browser MCP App
Browser Automation Web Scraping
archestra-ai
F
license
Not graded
quality
C
maintenance
Drives a real Chromium browser with Playwright, providing a live, clickable view of the page for the model to browse and the user to interact with.
Updated 2 months ago (2026-06-26 11:22 UTC)
2
-
playwright-mcp
Browser Automation Web Scraping
dinesh-nalla-se
A
license
Not graded
quality
D
maintenance
Provides browser automation through Playwright, enabling LLMs to interact with web pages using structured accessibility snapshots instead of screenshots.
Updated 10 months ago (2025-11-14 20:24 UTC)
6,364,011
Apache 2.0

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/inSideos-designs/cowork-qa-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server