TestNeo MCP — Overview

Turn the AI chat you already use — Cursor, VS Code, Claude Desktop, or any MCP-compatible client — into a full QA agent that generates, executes, watches, and triages tests.

What it is

The TestNeo MCP server exposes TestNeo capabilities as tools that AI assistants can call directly. Plug it into your IDE's MCP configuration and your chat becomes an IDE-native QA workflow:

Query quality data (projects, executions, trends, failures)
Generate tests from context — including design-image contexts
Execute tests with safeguards
Watch live runs to completion
Triage failures with structured root-cause & rerun plans

Why it matters

Zero context switching. Stop juggling generators, runners, and dashboards — answer in chat.
Chat prompts → real test actions. One sentence in plain English maps to a real, audited tool call.
Both NLP and Playwright SDK paths. Same source context, two outputs: NLP test cases and Playwright SDK .spec.ts drafts.

Core capabilities

Project and execution discovery
Pass/fail trend analysis
Failure bundles with likely root cause and next actions
Rerun planning and guarded execution
Context-based test generation (incl. design images)
Playwright SDK spec export and preview execution

How it fits together

MCP tools are the action layer your AI client calls.
TestNeo backend is the source of truth for projects, executions, and intelligence.
Agent workflows orchestrate multi-step operations on top of tools (e.g. qa_intelligence_workflow).

Key workflows

qa_intelligence_workflow — trend + failed runs + triage + rerun preview
figma_to_tests_workflow — context ingestion → test generation → preview
Human-in-the-loop review before any write action (confirm=true)

Safety model

!

Write actions are disabled by default.

To enable tools that mutate data (execute tests, rerun, trigger Playwright), you must:

Set TESTNEO_MCP_ALLOW_WRITE=true in the MCP server environment.
Pass confirm=true on the specific tool input.

This prevents accidental execution from casual prompts. Read & analysis tools work without these flags.

Works with

Any MCP-compatible client. Tested today with:

Cursor
VS Code (with an MCP extension)
Claude Desktop
Windsurf
Zed

Ready to install? Continue to the Quickstart.

Quickstart

Connect the TestNeo MCP server to your IDE and run your first workflow in under five minutes.

Prerequisites

Node.js 20+
TestNeo account with an API key (sign up free)
An MCP-compatible client — Cursor recommended; VS Code, Claude Desktop, Windsurf, Zed all supported

1) Configure MCP in your client

Add the TestNeo server to your MCP client configuration. npx downloads and runs the latest server on demand — no manual install required.

Cursor / Windsurf

Open Settings → MCP (or edit ~/.cursor/mcp.json) and add:

{
  "mcpServers": {
    "testneo": {
      "command": "npx",
      "args": ["-y", "@testneo/mcp-server"],
      "env": {
        "TESTNEO_BASE_URL": "https://app.testneo.ai",
        "TESTNEO_API_KEY": "YOUR_API_KEY",
        "TESTNEO_MCP_ALLOW_WRITE": "false"
      }
    }
  }
}

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your OS:

{
  "mcpServers": {
    "testneo": {
      "command": "npx",
      "args": ["-y", "@testneo/mcp-server"],
      "env": {
        "TESTNEO_BASE_URL": "https://app.testneo.ai",
        "TESTNEO_API_KEY": "YOUR_API_KEY",
        "TESTNEO_MCP_ALLOW_WRITE": "false"
      }
    }
  }
}

VS Code

Use any MCP-aware extension (e.g. Continue, Cline) and point it at the same command / args / env shown above.

i

Tip: Keep TESTNEO_MCP_ALLOW_WRITE set to "false" while you evaluate. Read & analysis tools still work; nothing in your project can be mutated without you flipping the flag.

2) Restart your MCP client

Restart the IDE (or "Reload MCP servers" if your client supports it) so the new tools are loaded.

3) Verify the connection

Try these prompts in chat:

Validate my TestNeo connection

List my TestNeo projects

You should get a structured response with your account info or project list. If you don't, see Troubleshooting.

4) Run your first workflow

Try a one-liner agent workflow:

Run qa_intelligence_workflow for project 47

You'll get an execution summary, failed-run IDs, triage bundles, and a rerun plan — all in chat.

5) Optional: enable write actions

Once you're comfortable, enable mutating tools (execute, rerun, trigger).

Update your MCP config: "TESTNEO_MCP_ALLOW_WRITE": "true"
Restart the MCP client.
Always include confirm=true in the prompt:

Execute generated test case 7708 with confirm=true

✓

You're done. Continue to Workflows for end-to-end recipes, or browse the Tool Reference.

Tool Reference

All MCP tools exposed by the TestNeo server, grouped by capability. Read & analysis tools are always available; write tools are guarded.

Read & analysis tools

Always available. Safe to call freely — these only read data.

testneo_validate_connection
testneo_list_projects
testneo_list_recent_executions
testneo_get_execution_status
testneo_get_execution_summary
testneo_get_execution_logs
testneo_search_failures
testneo_get_pass_fail_trend
testneo_watch_execution
testneo_get_failure_bundle
testneo_run_agent_workflow

Context & test-generation tools

Ingest context (Figma designs, requirements) and produce NLP / Playwright drafts. Drafts are previewable before any commit.

testneo_ingest_figma_context
testneo_generate_tests_from_context
testneo_preview_generated_tests
testneo_figma_to_tests_workflow

Script & editing tools

Update generated NLP, export to Playwright, or run a Playwright spec preview.

testneo_update_test_case_nlp
testneo_export_playwright_spec
testneo_run_playwright_spec_preview

Write & execution tools Guarded

These mutate state in your TestNeo project. They require both:

TESTNEO_MCP_ALLOW_WRITE=true in the MCP server environment
confirm=true on the tool input

testneo_execute_generated_test_case
testneo_rerun_failed
testneo_trigger_playwright_execution

Example inputs

`testneo_get_pass_fail_trend`

{
  "project_id": 47,
  "range": "30d",
  "limit": 200
}

`testneo_run_agent_workflow`

{
  "workflow_type": "qa_intelligence_workflow",
  "project_id": 47,
  "range": "30d",
  "top_failures": 2,
  "rerun_limit": 3
}

`testneo_generate_tests_from_context`

{
  "project_id": 47,
  "context_id": 103,
  "auth_preamble": {
    "enabled": true,
    "preset": "saucedemo"
  },
  "persist_auth_preamble": true
}

`testneo_execute_generated_test_case` Guarded

{
  "test_case_id": 7708,
  "confirm": true
}

Workflows

Five end-to-end recipes you can run from chat. Each is one or two prompts that orchestrate multiple MCP tools under the hood.

1. QA Intelligence

Goal: trend + failure triage + rerun planning from one prompt.

Prompt:

Run qa_intelligence_workflow for project 47

Output includes:

Execution summary
Latest failed execution IDs
Triage bundles
Recurring themes
Rerun plan preview

2. Context to test generation

Goal: use existing unified context (Figma, requirements, APIs) to create runnable tests.

Prompts:

Generate tests from context 103 for project 47 with auth_preamble preset saucedemo

Preview generated tests as NLP and Playwright spec drafts

Execute generated test case 7708 with confirm=true

Watch execution <execution_id> until completion

3. Failure investigation

Goal: explain a failure and suggest next actions quickly.

Prompts:

Watch execution <execution_id> until completion

Get failure bundle for execution <execution_id>

Search failures in project 47 for checkout

4. Script-path validation

Goal: verify the Playwright SDK script flow in addition to the NLP flow.

Prompts:

Export test case 7708 as Playwright SDK spec

Run Playwright spec preview for project 47 with test name "SDK preview 7708" and confirm=true

Watch execution <execution_id> until completion

5. Human-in-the-loop hardening

Goal: quickly fix generated steps and rerun.

Prompts:

Update NLP commands for test case 7708 with corrected checkout route

Execute generated test case 7708 with confirm=true

Watch execution <execution_id> until completion

Security & Governance

How TestNeo MCP keeps QA actions safe by default, and how to run it responsibly across teams and environments.

Security principles

Least privilege by default. Read tools always work; write tools require explicit enablement.
Explicit user intent for write actions. Two flags must align before anything mutates.
Traceable outputs. Every tool call returns identifiers (project, test case, execution) you can audit.

Write guardrails

Write actions require both:

TESTNEO_MCP_ALLOW_WRITE=true in the MCP server environment
confirm=true in the tool input

This prevents accidental execution from casual prompts. Without both, the server returns Write tools are disabled and stops.

Recommended environment practices

Use dedicated API keys per environment / team. Don't share keys across staging and production.
Rotate keys regularly. Treat them like secrets.
Avoid hardcoding secrets in docs or source. Use environment variables or a secret manager.
Scope backend access appropriately for production — read-only by default, write enablement granted to specific teams.

Governance recommendations

Define an explicit role policy:

Who can trigger execution?
Who can rerun failed tests?
Who can update generated test cases?

Keep a clear approval workflow for generated tests:

generate → preview → approve → execute

Operational audit

For each tool invocation, capture and retain:

Prompt / request context
Tool called
Execution ID / test case ID
Timestamps and result status

Safe rollout pattern

Start read-only in production. Let teams query and triage.
Enable write mode for a limited team once they trust the workflow.
Expand once workflows stabilise and the audit process is in place.

i

Need an enterprise-grade rollout plan, SSO, or per-team key isolation? Contact us — we'll help you design it.

Troubleshooting

Quick fixes for the most common issues setting up or using the TestNeo MCP server.

Tool not found

Symptom: Tool ... was not found in chat.

Fix:

Restart / reload the MCP server in your IDE.
Update to the latest server: in your MCP config, npx -y @testneo/mcp-server@latest ensures the newest tools load.
Confirm the server appears in your client's MCP status panel.

Write action blocked

Symptom: Write tools are disabled.

Fix:

Set TESTNEO_MCP_ALLOW_WRITE=true in the MCP env block.
Restart the MCP server.
Include confirm=true in the write-tool input.

See Security & Governance for why these guardrails exist.

Execution fails with `{{base_url}}`

Symptom: invalid URL or unresolved placeholder during a test run.

Fix:

Make sure the project environment exists and has a base_url set.
Set a default environment for the project.
Add an auth preamble + concrete route steps when needed.

Symptom: a step like Navigate to the checkout overview screen fails to resolve.

Fix: replace with an explicit route:

Navigate to {{base_url}}/checkout-step-two.html

Update the test via:

testneo_update_test_case_nlp

Auth or trial errors

Symptom: trial expired / unauthorised / forbidden.

Fix:

Validate your token in chat: Validate my TestNeo connection
Confirm your account subscription / trial status in the dashboard.
If your guest quota is exhausted, sign up free.

Still stuck?

Open a support ticket from our contact page with:

Your MCP client name & version
The exact prompt you used
The full error or last few lines from your MCP server log

TestNeo MCP — Overview

What it is

Why it matters

Core capabilities

How it fits together

Key workflows

Safety model

Works with

Quickstart

Prerequisites

1) Configure MCP in your client

Cursor / Windsurf

Claude Desktop

VS Code

2) Restart your MCP client

3) Verify the connection

4) Run your first workflow

5) Optional: enable write actions

Tool Reference

Read & analysis tools

Context & test-generation tools

Script & editing tools

Write & execution tools Guarded

Example inputs

testneo_get_pass_fail_trend

testneo_run_agent_workflow

testneo_generate_tests_from_context

testneo_execute_generated_test_case Guarded

Workflows

1. QA Intelligence

2. Context to test generation

3. Failure investigation

4. Script-path validation

5. Human-in-the-loop hardening

Security & Governance

Security principles

Write guardrails

Recommended environment practices

Governance recommendations

Operational audit

Safe rollout pattern

Troubleshooting

Tool not found

Write action blocked

Execution fails with {{base_url}}

Generated step uses vague navigation

Auth or trial errors

Still stuck?

`testneo_get_pass_fail_trend`

`testneo_run_agent_workflow`

`testneo_generate_tests_from_context`

`testneo_execute_generated_test_case` Guarded

Execution fails with `{{base_url}}`