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 with deterministic canonical_status
• Failure bundles with likely root cause, next actions, and an optional suggested_nlp_patch (diff-style fix you can apply with testneo_update_test_case_nlp)
• Rerun planning and guarded execution
• Context-based generation with names, not mystery IDs — list unified contexts and resolve context_id from a plain-language label (especially handy for Figma-ingested contexts)
• Playwright SDK spec export and preview execution
• Project-scoped route-map governance (testneo_get_project_route_map / testneo_set_project_route_map) — keep Navigate phrase maps in project settings instead of per-machine env drift

Observability

Every JSON tool response includes a top-level _telemetry object with a stable request_id, duration_ms, and backend_paths (the ordered METHOD path calls the MCP server made). Use it to correlate chat sessions with backend logs.

For centralised monitoring, set TESTNEO_MCP_TELEMETRY_JSONL=true — the server emits one JSON line per tool invocation to stderr, ready for Vector / Fluent Bit / Loki pipelines.

Deterministic execution contract

Execution-oriented tool responses include a stable envelope:

• contract_version: "execution_intelligence.v1"
• canonical_status — queued | running | passed | failed | cancelled | unknown
• raw_status — the original backend status preserved for debugging

Always make agent decisions from canonical_status; it's normalised across backend variants (completed, success, error, …).

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 are selected via testneo_run_agent_workflow and the workflow_type field — qa_intelligence_workflow, triage_failure_workflow, and rerun_decision_workflow are not separate MCP tool names.

Key workflows

• testneo_run_agent_workflow with workflow_type: qa_intelligence_workflow (trend + failed runs + triage + rerun preview), triage_failure_workflow (triage bundles), or rerun_decision_workflow (pass rate + rerun plan preview only).
• testneo_figma_to_tests_workflow — unified context → test generation → preview (or testneo_ingest_figma_context when starting from Figma ETL).
• testneo_run_generated_test_pipeline — single-shot execute → full report (preferred over chaining execute + watch + summary).
• Human-in-the-loop review before guarded writes (confirm=true) where the tool supports it.

Safety model

Works with

Any MCP-compatible client. Tested today with:

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

Next steps

• Quickstart — connect MCP in under 5 minutes.
• Unified Contexts — resolve context_id from a Figma name fragment, no UI digging.
• Prompt Packs — copy-paste prompts for QA, SDET, PM + a one-shot demo.
• Prompt Packs (standalone) — one scrollable page without the sidebar/navigation app.
• Tool Reference — every tool, telemetry shape, contract, and example inputs.

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",
        "TESTNEO_MCP_TELEMETRY_JSONL": "true"
      }
    }
  }
}

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",
        "TESTNEO_MCP_TELEMETRY_JSONL": "true"
      }
    }
  }
}

VS Code

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

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) Find a unified context by name (Figma-friendly)

Contexts you create from Figma appear under the human-readable name you set at ingest. You rarely need to remember numeric ids like 123 or 203 — resolve by label instead:

List unified contexts for project 47

Resolve unified context by name for project 47 — name_query "figma checkout"

The resolver matches names like "Figma — Checkout flow" from a fragment such as "figma checkout". Use the returned resolved_context_id in any generation prompt.

Full walkthrough with sample payloads: Unified Contexts.

5) Run your first workflow

Call the QA intelligence workflow through the real MCP tool (replace 47 with your project_id):

Call testneo_run_agent_workflow with workflow_type "qa_intelligence_workflow", project_id 47, range "30d"

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

Want copy-paste prompts for QA Lead / SDET / PM personas — plus a single one-shot demo prompt? See Prompt Packs.

6) Optional: enable write actions

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

1. Update your MCP config: "TESTNEO_MCP_ALLOW_WRITE": "true".
2. Recommended: keep "TESTNEO_MCP_RELAX_PROJECT_PRECONDITIONS": "false" (the default) so the server fails fast when a project lacks an executable base URL.
3. Restart the MCP client.
4. Always include confirm=true in the prompt:

Execute generated test case 7708 with confirm=true

7) Optional: team route map source-of-truth

Instead of every developer setting TESTNEO_ROUTE_PROFILE / TESTNEO_ROUTE_MAP_JSON locally, store the team's Navigate phrase map in project settings:

Show project route map for 47

Set project route map for 47 with the proposed payload, confirm=true

The setter is write-gated. See Project-scoped route map in the Tool Reference for the precedence rules.

Execution contract note

Execution-intelligence tools return a normalised envelope:

• contract_version: "execution_intelligence.v1"
• canonical_status and raw_status for deterministic agent parsing.

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_get_project_route_map
• 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

Discover unified contexts by name (no UI digging), ingest new context (Figma designs, requirements), and produce NLP / Playwright drafts. Drafts are previewable before any commit.

• testneo_list_unified_contexts
• testneo_get_unified_context_by_name
• testneo_ingest_figma_context
• testneo_generate_tests_from_context
• testneo_preview_generated_tests
• testneo_apply_route_hardening
• testneo_figma_to_tests_workflow
• testneo_set_project_route_map Guarded

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 Guarded

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_run_generated_test_pipeline
• testneo_rerun_failed
• testneo_trigger_playwright_execution

Note: the server exposes 33 testneo_* tools. Groups below include Swagger/OpenAPI and pipeline execution; use this page’s sidebar Prompt Packs for copy-paste prompts.

Swagger / OpenAPI intelligence (web + API projects)

• testneo_swagger_preview
• testneo_swagger_upload_and_generate Guarded
• testneo_swagger_impact_analysis Guarded
• testneo_swagger_impact_actions Guarded
• testneo_api_project_upload_openapi Guarded
• testneo_api_project_openapi_impact Guarded

Response telemetry (_telemetry)

Every MCP tool invocation is wrapped with timing and backend-call tracing. On JSON-shaped responses the payload includes a merged top-level _telemetry object (any prior _telemetry from upstream is replaced):

If the handler returns plain text that is not parseable JSON, telemetry is appended as a trailing JSON block labeled _mcp.telemetry (JSON).

For centralised monitoring, set TESTNEO_MCP_TELEMETRY_JSONL=true to emit one JSON line per tool invocation to stderr (same correlation fields plus outcome and an optional error_message) — suitable for Vector / Fluent Bit / Loki / SigNoz pipelines.

Execution-intelligence contract normalisation

Execution-oriented MCP outputs include a stable envelope for deterministic agent parsing:

• contract_version: "execution_intelligence.v1" on normalised execution / status tools.
• canonical_status per execution / summary — one of queued | running | passed | failed | cancelled | unknown.
• raw_status preserved for backend debugging.

Tools aligned to this envelope:

• testneo_list_recent_executions
• testneo_get_execution_status
• testneo_get_execution_summary
• testneo_search_failures
• testneo_get_pass_fail_trend (preview rows include canonical_status)
• testneo_watch_execution (final_canonical_status + timeline canonical statuses)

This reduces downstream prompt / parser drift when backend status strings vary (completed, success, error, …).

Failure bundle: NLP patch suggestion (suggested_nlp_patch)

testneo_get_failure_bundle accepts include_nlp_patch_suggestion (default true). When enabled, the server may fetch baseline NLP for the failing test case and attach suggested_nlp_patch with:

• unified_diff — line-oriented before / after for quick review.
• proposed_nlp_commands — full suggested NLP list.
• testneo_update_test_case_nlp — ready-to-call arguments when test_case_id is known; otherwise null (use proposed_nlp_commands as a template).

testneo_run_agent_workflow — for triage_failure_workflow and qa_intelligence_workflow, enriches each built failure bundle the same way. rerun_decision_workflow does not build triage_bundles.

Heuristics are conservative (route hardening, optional short wait for timeout themes); always review before applying testneo_update_test_case_nlp.

Project execution preconditions

Before testneo_generate_tests_from_context, testneo_figma_to_tests_workflow, and any confirmed execution on testneo_execute_generated_test_case, testneo_run_playwright_spec_preview, testneo_rerun_failed, or testneo_trigger_playwright_execution, the server loads the project (and, if needed, web environments) and requires a resolvable http(s) base URL.

Failures return JSON with:

• error: "project_precondition_failed"
• precondition_code
• remediation (agent-actionable)

Escape hatch (not for production): TESTNEO_MCP_RELAX_PROJECT_PRECONDITIONS=true.

Precondition policies v2

Write / execute surfaces also run a policy layer and may return:

• error: "policy_failed"
• policy_mode — strict (default) or warn
• findings[] with code, severity, message, and remediation

Current policy checks include: executable base URL readiness, auth credentials presence when login-like commands are detected, route-map coverage warnings / blockers for unresolved Navigate phrases, checkout data prerequisite warnings, and weak assertion coverage warnings (no verify / assert / expect).

Configure with TESTNEO_MCP_POLICY_MODE=strict (default) or warn.

Project-scoped route map (project_settings.mcp_route_hardening)

• testneo_get_project_route_map — reads project settings and reports both stored and effective route-hardening config.
• testneo_set_project_route_map Guarded — updates project_settings.mcp_route_hardening (use confirm=true to apply).

Effective precedence during generation / update flows:

1. MCP env defaults (TESTNEO_ROUTE_PROFILE, TESTNEO_ROUTE_MAP_JSON)
2. Project-scoped route map (project_settings.mcp_route_hardening)
3. Per-call route_hardening override

This keeps a team-level source of truth without depending on each developer's machine env.

Idempotency for write tools

Write tools accept an optional idempotency_key (string). Behaviour:

• Same key + same effective input → replay cached response (replayed: true)
• Same key + different effective input → error: "idempotency_conflict"
• No key → normal behaviour (no replay protection)

Recommended for retries from CI agents and orchestrated prompts.

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_get_failure_bundle

{
  "execution_id": "abc123def456",
  "logs_limit": 150,
  "event_limit": 20,
  "include_nlp_patch_suggestion": true
}

testneo_list_unified_contexts

{
  "project_id": 47,
  "compact": true,
  "max_compact_lines": 60
}

testneo_get_unified_context_by_name

Matches names like Figma — Checkout flow when you query "figma checkout". Use prefer_context_id only if several rows tie.

{
  "project_id": 47,
  "name_query": "figma checkout",
  "match_mode": "auto",
  "prefer_context_id": 203,
  "include_detail": false
}

testneo_generate_tests_from_context

Prefer obtaining context_id from testneo_get_unified_context_by_name (e.g. after Figma ingest, name fragment "figma checkout"). Below, 203 is an illustrative resolved id, not fixed.

{
  "project_id": 47,
  "context_id": 203,
  "auth_preamble": {
    "enabled": true,
    "preset": "saucedemo"
  },
  "persist_auth_preamble": true,
  "persist_route_hardening": true,
  "auto_align_saucedemo_route_map": true
}

With auto_align_saucedemo_route_map left default true and SauceDemo auth, MCP applies the SauceDemo phrase map whenever env has TESTNEO_ROUTE_PROFILE=none and no TESTNEO_ROUTE_MAP_JSON. Set to false to rely only on env + route_hardening overrides.

testneo_execute_generated_test_case Guarded

{
  "test_case_id": 7708,
  "confirm": true,
  "idempotency_key": "ci-rerun-2026-05-09-7708"
}

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:

Call testneo_run_agent_workflow with workflow_type "qa_intelligence_workflow", project_id 47, range "30d"

Output includes:

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

2. Context to test generation

Goal: use an existing unified context (Figma, requirements, APIs) to create runnable tests without digging up a numeric context_id by hand.

Prompts:

List unified contexts for project 47 (compact index)

Resolve unified context by name for project 47 — name_query "figma checkout"

Generate tests from the resolved_context_id returned above for project 47 with auth_preamble preset saucedemo

Optional next steps:

Preview generated tests as NLP and Playwright spec drafts

Execute generated test case 7708 with confirm=true

Watch execution <execution_id> until completion

If two contexts collide on a Figma re-import, narrow name_query or pass prefer_context_id. Full walkthrough in Unified Contexts.

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

The failure-bundle response includes an optional suggested_nlp_patch (unified_diff, proposed_nlp_commands, and a ready-to-call testneo_update_test_case_nlp payload when test_case_id is known) — toggled by include_nlp_patch_suggestion (default true).

Each tool response also carries _telemetry (request_id, duration_ms, backend_paths) for support and iteration.

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

Unified Contexts

Find the right context_id by name — no UI scraping, no guessing. Especially handy for Figma-ingested contexts where the name carries meaning.

Why this exists

Finding context_id in the product UI was friction for demos and first-time MCP use. Two read-only tools handle that end to end.

Contexts you create through Figma ingest (testneo_ingest_figma_context or the UI) show up in this list under the human-readable name you chose (for example Figma — Checkout flow). You talk to MCP using that label (or a short fragment such as "figma checkout"); you do not need to remember the numeric id.

Tools

Worked example: Figma context → resolve by name → generate tests

Assume project 47 and a unified context you already created from Figma whose name looks like Figma — Checkout flow (the exact string is whatever you set at ingest time).

1) List unified contexts

{
  "project_id": 47,
  "compact": true
}

Compact index lines look like id=203 | "Figma — Checkout flow" | unified | entities=… (the 203 here is illustrative — your server returns the real id).

2) Resolve by name

{
  "project_id": 47,
  "name_query": "figma checkout",
  "match_mode": "auto"
}

Natural-language chats often say the same thing: "Resolve the Figma checkout context for project 47." The tool picks the best match among names that contain "figma" and "checkout" (after normalisation).

3) Read resolved_context_id

From the tool output (above we pretended 203).

4) Generate tests using that id

{
  "project_id": 47,
  "context_id": 203,
  "auth_preamble": { "enabled": true, "preset": "saucedemo" },
  "auto_align_saucedemo_route_map": true
}

With SauceDemo auth, auto_align_saucedemo_route_map (default true) applies bundled route phrases unless you disable it or configure TESTNEO_ROUTE_PROFILE / TESTNEO_ROUTE_MAP_JSON.

End-to-end recipe (copy mindset)

1. Project — testneo_list_projects → pick project_id.
2. Contexts — testneo_list_unified_contexts with that project_id (or skip straight to step 3 if you already know part of the label).
3. Resolve — testneo_get_unified_context_by_name with a fragment of the Figma / context name, e.g. name_query: "figma checkout" and match_mode: "auto". If several match, narrow the string or set prefer_context_id from the list.
4. Generate — testneo_generate_tests_from_context using the returned resolved_context_id.

Prompts you can paste

List unified contexts for project <PROJECT_ID> and show the compact index.

Resolve unified context by name for project <PROJECT_ID>: name_query "figma checkout", match_mode auto — if ambiguous, I'll pick prefer_context_id from the list.

Generate tests for project <PROJECT_ID> using the resolved_context_id from the prior step with auth_preamble preset saucedemo (or disable if not SauceDemo).

Related

• Quickstart
• Workflows (Workflow 2)
• Tool Reference
• Prompt Packs

Prompt Packs

Copy-paste prompts for QA Lead, SDET, and PM personas — plus a single one-shot demo prompt that walks the full MCP story.

QA Lead — quality signal, release risk, reruns

1) Connection sanity check

Validate my TestNeo MCP connection and list my projects with test case counts.

2) 30-day pulse

For project <PROJECT_ID>, show pass/fail trend for the last 30 days using a reasonable execution sample size, and summarize whether quality is stable, improving, or degrading in one short paragraph.

3) One-command QA intelligence

Call testneo_run_agent_workflow with workflow_type "qa_intelligence_workflow", project_id <PROJECT_ID>, range "30d", top_failures 2, rerun_limit 3. Summarize recurring_themes and triage_bundles, cite latest_failed_execution_ids, and list the top 3 follow-up actions for my team.

4) Failure triage sprint

Call testneo_run_agent_workflow with workflow_type "triage_failure_workflow", project_id <PROJECT_ID>, range "30d", top_failures 3. For each triage_bundles entry, give me: symptom, inferred theme, and concrete next QA steps.

5) Rerun decision (preview-first)

Call testneo_run_agent_workflow with workflow_type "rerun_decision_workflow", project_id <PROJECT_ID>, range "30d". Do not execute reruns — explain rerun_plan_preview and what would change with TESTNEO_MCP_ALLOW_WRITE and confirm=true on testneo_rerun_failed.

6) Semantic failure search

Search failures in project <PROJECT_ID> for "<KEYWORDS>" (e.g. checkout, login, timeout). Summarize recurring patterns and which areas need regression focus.

7) Deep dive on one run

Fetch execution summary and failure bundle for execution <EXECUTION_ID>. Explain in QA terms what broke, severity, and whether this looks like product bug vs test flake.

8) Human-in-loop after a fix

Pull execution logs for execution <EXECUTION_ID>. Recommend whether we should rerun the same test case, update NLP steps, or file a defect — and say what evidence supports that.

9) Find the right unified context fast

List unified contexts for project <PROJECT_ID>, then resolve by name_query "figma <feature>" so I get a definitive context_id for generation (matches Figma-ingested names like "Figma — Checkout flow"; use prefer_context_id if two rows collide).

10) Project route map governance

Show project route map for <PROJECT_ID> (testneo_get_project_route_map). If missing/partial, propose a merge payload for testneo_set_project_route_map with phrases we repeatedly use in failures. Do not apply unless I confirm=true.

SDET — automation, specs, flaky runs, MCP mechanics

1) Project + execution discovery

Validate TestNeo connection, list projects, then list recent failed executions for project <PROJECT_ID> with a short note on status normalization if anything looks ambiguous.

2) Structured watch

Watch execution <EXECUTION_ID> until completion (use polling). When done, summarize final status and any failure signals worth capturing in a CI ticket.

3) Failure bundle for automation

Get failure bundle for execution <EXECUTION_ID> and extract: failed steps, log snippets theme, inferred root cause bucket, suggested automation fixes (selectors, waits, data).

4) NLP hardening — routes

Using testneo_apply_route_hardening, show how these NLP Navigate lines rewrite with our server's route profile and map (or suggest TESTNEO_ROUTE_MAP_JSON entries if phrases are unknown): [paste commands].

5) Persist improved NLP

Update test case <TEST_CASE_ID> NLP commands to: [paste list]. Apply route hardening with apply_route_hardening=true before saving unless I already used explicit {{base_url}} paths everywhere. Confirm the payload you will send matches my intent.

6) Playwright SDK path

Export test case <TEST_CASE_ID> as Playwright SDK TypeScript spec, then review it for brittle steps. If MCP write is enabled and I approve, run Playwright spec preview for project <PROJECT_ID> with a clear test name and confirm=true — and watch the resulting execution.

7) Context-driven generation + preview

For project <PROJECT_ID>: resolve unified context by name_query "<LABEL_FRAGMENT>" (or list contexts first), then generate tests from the resolved context_id with auth_preamble preset saucedemo when relevant. Preview the first few cases as NLP + spec drafts; flag risk_flags like missing assertions. Note any route hardening changes.

8) Trend + flaky classification

For project <PROJECT_ID>, get pass_fail_trend plus recent failures list. Identify tests or flows that failed more than once in the window and label each as suspected flake vs probable defect based on MCP evidence only.

PM / engineering manager — plain language, outcomes, timelines

These prompts assume read-only MCP by default — usually enough for status and narratives.

1) Single project heartbeat

In plain language for a PM audience: summarize current quality status for project <PROJECT_ID> using recent executions and any trend MCP exposes. No tool jargon in the summary — explain what "good" vs "risky" means for release.

2) Weekly quality narrative

Give me a 5-bullet executive update for project <PROJECT_ID> covering pass rate trajectory, notable failures, customer-facing risk areas, and what we validated recently. Pull data via MCP tools, then simplify terminology.

3) "What broke recently?"

What failed in project <PROJECT_ID> in roughly the last two weeks at a glance? Describe impact in feature terms (e.g. checkout) not MCP tool names; include links or IDs execs rarely need — but keep execution IDs footnoted for engineering.

4) Trend direction

Is automated quality trending up or down for project <PROJECT_ID> over <RANGE e.g. 30d>? One chart-like sentence + one caveat about sample size based on MCP data.

5) Risk before demo or launch

We have a stakeholder demo soon. Scan project <PROJECT_ID> for recent failures and tell me top 3 product areas I should verbally caveat or avoid demoing — the risk list only, no blame.

6) Regression focus for planning

From MCP failure search/triage on project <PROJECT_ID>, what themes should roadmap planning prioritize next sprint (stability vs new feature risk)? Bullet list with business framing.

7) Human-in-loop design → tests (high level)

Someone ingested design context earlier. Explain at a PM level how project <PROJECT_ID> can go from Figma/unified context to draft tests — and what approvals are still required before auto-execution is safe. Actual IDs optional; keep it procedural.

8) Incident-style postmortem stub

For execution <EXECUTION_ID>, write a lightweight postmortem: what broke, scope, mitigation, prevention — readable by PM and ENG. MCP can provide technical detail; strip acronyms in the narrative.

One-shot "full demo" prompt

Use once to show someone the full MCP story (read-heavy by default). After it runs, you can selectively enable writes and rerun with approvals.

You are demonstrating the TestNeo MCP integration.

1) Validate the TestNeo connection and list projects; pick project <PROJECT_ID> (or ask me if unclear).

2) For that project, call testneo_run_agent_workflow with workflow_type "qa_intelligence_workflow", range "30d", top_failures 2, rerun_limit 3: summarize execution_summary / pass rate, cite example failed execution IDs briefly, summarize recurring_themes from triage_bundles, and present rerun_plan_preview (do not execute reruns unless I explicitly confirm and writes are enabled).

3) Optionally, for test generation from a Figma (or other) unified context: call testneo_list_unified_contexts, then testneo_get_unified_context_by_name with a fragment of the context display name (e.g. name_query "figma checkout" for a context like "Figma — Checkout flow"). Outline generate from resolved_context_id → preview NLP + Playwright drafts, mention route hardening/env maps in one sentence if Navigate steps look vague, and list approvals needed before testneo_execute_generated_test_case with confirm=true.

4) End with three concrete prompts I can reuse next — one for QA lead, one for SDET, one for PM — all customized to real IDs discovered in steps 1–2.

Keep the transcript tight: bullets and short prose, no fluff.

Related

• Quickstart
• Workflows
• Tool Reference
• Unified Contexts

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:

1. TESTNEO_MCP_ALLOW_WRITE=true in the MCP server environment
2. 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

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

Troubleshooting

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

Which context_id should I use?

Symptom: you only know the context label from Figma or docs, not its numeric id.

Fix:

• Call testneo_list_unified_contexts for project_id.
• Or testneo_get_unified_context_by_name with name_query (match_mode: auto, exact, or substring) and prefer_context_id when several match.

Typical demo path: ingest names a context Figma — … → resolve "figma <feature>" → generate.

Full walkthrough: Unified Contexts.

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:

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

See Security & Governance for why these guardrails exist.

MCP project_precondition_failed

Symptom: testneo_generate_tests_from_context, testneo_figma_to_tests_workflow, or execute tools return error: "project_precondition_failed" with a precondition_code.

Cause: the project has no usable http(s) base URL — empty website_url, example.com, an invalid URL — or environments lack a valid base_url.

Fix:

• Set the project website URL (target URL) in TestNeo, or set a default environment base_url variable.
• For non-prod automation only, set MCP env TESTNEO_MCP_RELAX_PROJECT_PRECONDITIONS=true (disables the check — not recommended in production).

See Tool Reference — Project execution preconditions.

Policy failed (error: "policy_failed")

Symptom: a write or execute tool returns error: "policy_failed" with policy_mode and a findings[] list.

Fix: read each finding's code, severity, and remediation. Common causes: missing auth credentials when login-like commands are detected, unresolved Navigate phrases (route-map gap), checkout flows with no add-to-cart signal, or no verify / assert / expect anywhere. Set TESTNEO_MCP_POLICY_MODE=warn only if you accept the trade-off.

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.

Generated step uses vague navigation

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

Fix:

• testneo_generate_tests_from_context defaults to auto_align_saucedemo_route_map=true: when you use SauceDemo auth (auth_preamble.preset: saucedemo) and MCP env has no custom route map (TESTNEO_ROUTE_PROFILE=none / no TESTNEO_ROUTE_MAP_JSON), bundled SauceDemo Navigate phrases rewrite to {{base_url}}/… paths.
• Or set MCP env TESTNEO_ROUTE_PROFILE=saucedemo / TESTNEO_ROUTE_MAP_JSON for explicit control.
• Or update steps via testneo_update_test_case_nlp / testneo_apply_route_hardening.

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.

Correlating a tool run with the API

When reporting an MCP issue or comparing runs:

• Inspect _telemetry.request_id and duration_ms on JSON tool outputs.
• Use backend_paths to see which METHOD path calls the MCP server made (GET /api/web/v1/…, etc.).
• For centralised logs, enable TESTNEO_MCP_TELEMETRY_JSONL=true and filter the stderr JSONL events by request_id.

See Tool Reference — Response telemetry.

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
• The _telemetry.request_id from the JSON response (if available)