Proven flow ~10 minutes

Run TestNeo from Claude Desktop

Connect Claude Desktop to TestNeo MCP, then drive QA from chat: list projects, run a login flow, check release readiness, and get a PR Release Brief — without hopping through the product UI for every step.

What you'll do

When it works, Claude calls TestNeo tools locally. Your tn_… key stays in the config file — never paste it into the chat.

Prerequisites

• Node.js 20+ on the machine where Claude Desktop runs (node -v).
• Claude Desktop (Pro / Max / Team / Enterprise where MCP connectors are available).
• TestNeo account — app.testneo.ai/signup.
• A web project with at least one test (e.g. SauceDemo-style login) and an environment with base_url. Secrets belong in env vars like {{password}}, not hardcoded in NLP.

1 · Get your TestNeo API key

2 · Configure Claude Desktop

Config file paths

If the file does not exist, create it. If it already has other MCP servers, merge the "testneo" block under mcpServers — do not wipe existing entries.

JSON to paste

Replace YOUR_API_KEY with your real tn_… key. Start with writes off.

{
  "mcpServers": {
    "testneo": {
      "command": "npx",
      "args": ["-y", "@testneo/mcp-server@0.2.1"],
      "env": {
        "TESTNEO_BASE_URL": "https://app.testneo.ai",
        "TESTNEO_WEB_APP_URL": "https://app.testneo.ai",
        "TESTNEO_API_KEY": "YOUR_API_KEY",
        "TESTNEO_MCP_ALLOW_WRITE": "false",
        "TESTNEO_MCP_TELEMETRY_JSONL": "true",
        "TESTNEO_MCP_DEFAULT_EXECUTION_MODE": "cloud",
        "TESTNEO_MCP_PREFER_LOCAL_AGENT": "false",
        "TESTNEO_MCP_DEFAULT_EXECUTION_PLATFORM": "local",
        "TESTNEO_MCP_REQUIRE_LOCAL_AGENT_FOR_BATCH": "false",
        "TESTNEO_MCP_WAIT_FOR_AGENT_MS": "0"
      }
    }
  }
}

Example config also lives at docs/mcp.json.example.

3 · Restart Claude & confirm tools

4 · Read-only smoke test

With TESTNEO_MCP_ALLOW_WRITE=false, discovery still works. Paste these one at a time:

Validate my TestNeo connection. Summarize success and any account hint.

List my TestNeo projects. Show project_id and name for each.

On project_id <PROJECT_ID>, find test cases matching "login". List id and name.

If Claude lists your projects, the bridge works. Save a project_id and a login test_case_id for the next steps.

5 · Enable writes (only when ready to run)

1. Edit the config: set "TESTNEO_MCP_ALLOW_WRITE": "true".
2. Quit and reopen Claude Desktop again.
3. Runs still need confirm: true on the tool call — Claude should ask or you should say “confirm true”.

Local agent vs cloud (before you run)

Claude Desktop only triggers the run. Something still has to drive the browser.

Call testneo_get_local_agent_status. Report agent_registered, agent_connected, seconds_since_heartbeat, and setup_url. If not connected, give setup steps only — do not run tests yet.

Local-agent env snippet (replace the five execution lines in your Claude config, then quit/reopen Claude):

"TESTNEO_MCP_DEFAULT_EXECUTION_MODE": "local",
"TESTNEO_MCP_PREFER_LOCAL_AGENT": "true",
"TESTNEO_MCP_DEFAULT_EXECUTION_PLATFORM": "local",
"TESTNEO_MCP_REQUIRE_LOCAL_AGENT_FOR_BATCH": "true",
"TESTNEO_MCP_WAIT_FOR_AGENT_MS": "60000"

More detail: MCP Quickstart — cloud vs local agent · Troubleshooting — local agent.

6 · Run a login test (proven path)

Use your real project_id, test case, and environment name (often dev or staging). With the default cloud config you can run immediately. If you switched to local mode, confirm the agent is connected first (prompt above).

Preview first (no execute)

Call testneo_run_generated_test_pipeline with test_case_id <TEST_CASE_ID>, confirm false, environment_name "<ENV_NAME>". Summarize what would run.

Execute + wait + report

Call testneo_run_generated_test_pipeline with test_case_id <TEST_CASE_ID>, confirm true, environment_name "<ENV_NAME>", idempotency_key "claude-login-001". Summarize pipeline.analytics_summary, canonical_status, execution_id, and if failed the first error_message.

Friendly one-liner (also works)

On project <PROJECT_ID>, find the login test and run it on environment "<ENV_NAME>" with confirm true. Tell me pass or fail and the execution link if available.

If it failed

Call testneo_get_failure_bundle with execution_id "<EXECUTION_ID>", include_nlp_patch_suggestion true. Summarize root cause and whether suggested_nlp_patch is safe to apply.

Demo flows (recommended order)

Use these as a live walkthrough. Replace <PROJECT_ID> with your project (e.g. 40). Keep confirm: false unless you intend to run tests.

Flow A — Login execute (~2 min)

1. Validate connection + list projects.
2. Find login test on <PROJECT_ID>.
3. Pipeline preview → execute with confirm true (writes on).

Using TestNeo MCP: validate connection, list projects, confirm project_id <PROJECT_ID> exists. Then find test cases matching "login" and list id + name.

On project <PROJECT_ID>, find the login test and run it on environment "<ENV_NAME>" with confirm true. Tell me pass or fail and execution_id.

Flow B — Release readiness / ship decision (~3 min, no git needed)

Best opener when you already have data in the project (history, executions, memory). No branch required.

For TestNeo project_id <PROJECT_ID>, give me a release readiness check.

1) Call testneo_get_release_readiness with project_id <PROJECT_ID> if available.
2) Call testneo_get_pr_validation_history with project_id <PROJECT_ID>, limit 15.
3) Call testneo_run_agent_workflow with workflow_type "qa_intelligence_workflow", project_id <PROJECT_ID>, range "30d", top_failures 5, rerun_limit 5.

Then answer in plain language:
- PASS / WARN / BLOCK trend from recent PR validations
- Top failure themes from executions
- Go / Hold / Go-with-conditions (with the specific condition)
- Top 3 actions before we ship

Do not run any tests. confirm stays false.

Call testneo_get_pr_validation_history with project_id <PROJECT_ID>, limit 20.
Present a table: workflow_id | risk level | score | date | short summary.
Then say: is this project trending safer or riskier for release? One paragraph.

Flow C — PR validation → Release Brief (~5 min)

Needs git context (repo open / Claude can detect SHAs) or you paste base_sha, head_sha, owner, name, PR number, and changed files. Never invent SHAs.

Validate this PR for TestNeo project_id <PROJECT_ID>.

1) Detect git context from the workspace:
   - head_sha = git rev-parse HEAD
   - base_sha = git merge-base HEAD origin/main (or origin/master)
   - changed_files from git diff --name-status <base_sha> HEAD
   - repository owner/name from git remote get-url origin
2) If no git repo is available, ask me for base_sha, head_sha, owner, name, PR number, and changed_files — do not invent SHAs.

3) Call testneo_pr_validation_workflow with:
   - project_id: <PROJECT_ID>
   - repository: { owner, name }
   - pull_request: { number: <PR_NUMBER> }
   - git: { base_sha, head_sha, changed_files }
   - sync_jira_before_validate: true
   - execution: { run_impacted_tests: true }
   - confirm: false

4) Display the FULL Release Brief (do not truncate): risk level, score, findings, merge recommendation, workflow_id.
5) If risk is BLOCK or WARN, immediately offer explain + fix plan.

Call testneo_explain_failure with workflow_id "<WORKFLOW_ID>", include_rerun_plan true.
Explain each blocking finding in plain English and list exact tests to rerun.

Call testneo_suggest_fix with workflow_id "<WORKFLOW_ID>", priority_filter "all".
Show NOW vs NEXT fixes and a re-validate plan.

Prompt cookbook

Copy-paste prompts that work well in Claude Desktop. Replace placeholders. For role packs (C17–C20, EM1–EM9), see Prompt packs and standalone prompt packs.

Discover

Call testneo_validate_connection. Summarize success.

Call testneo_list_projects with limit 50. Table of project_id and name.

Call testneo_find_test_cases with project_id <ID>, search "login". List id, name, tags.

Call testneo_list_tests_by_tags with project_id <ID>, tags ["smoke","login"], match_mode "intersection". List matches.

Call testneo_list_unified_contexts with project_id <ID>, compact true. Table of id and name.

Call testneo_get_unified_context_by_name with project_id <ID>, name_query "figma checkout", match_mode "auto". Return resolved_context_id.

Execute & triage

Call testneo_get_local_agent_status. Report agent_connected and setup_url. If false, stop — do not execute until the agent is up.

Call testneo_run_generated_test_pipeline with test_case_id <ID>, confirm false, environment_name "staging".

Call testneo_run_generated_test_pipeline with test_case_id <ID>, confirm true, environment_name "staging", idempotency_key "run-001". Summarize status and execution_id.

Call testneo_run_batch_by_tags with project_id <ID>, tags ["smoke"], match_mode "union", confirm true, environment_name "staging", idempotency_key "batch-smoke-001".

Call testneo_get_execution_summary for execution_id "<EXEC>". Then logs with limit 80. Summarize pass/fail and first fix.

Call testneo_get_failure_bundle with execution_id "<EXEC>", include_nlp_patch_suggestion true. Summarize cause + patch safety.

Call testneo_run_agent_workflow with workflow_type "qa_intelligence_workflow", project_id <ID>, range "30d", top_failures 5. Summarize themes; do not rerun.

Generate from context / docs / Swagger

Call testneo_generate_tests_from_context with project_id <ID>, context_id <CTX>, test_types ["positive","negative","edge"], include_ui_tests true, max_tests 12, auto_align_saucedemo_route_map false. List generated ids and names.

Call testneo_generate_tests_from_context with project_id <ID>, context_id <CTX>, test_types ["positive","negative","edge"], include_ui_tests true, max_tests 12, auth_preamble {"enabled": true, "preset": "saucedemo"}, persist_auth_preamble true, auto_align_saucedemo_route_map true.

Call testneo_ai_assistant_query with project_id <ID>, query "Summarize highest-risk user flows for automation", response_style "concise". Return assistant_reply.

Call testneo_ai_assistant_query with project_id <ID>, context_name_query "figma checkout", query "What edge cases should UI tests cover?", response_style "detailed".

Swagger / OpenAPI upload + generate uses write tools — see Customer E2E playbook · Part F.

Release readiness (no git required)

For TestNeo project_id <ID>, give me a release readiness check: get_release_readiness (if available), pr_validation_history limit 15, qa_intelligence_workflow range 30d. Answer Go/Hold/Go-with-conditions with evidence. Do not run tests.

Call testneo_get_pr_validation_history with project_id <ID>, limit 20. Table: workflow_id | risk | score | date | summary. Is the project trending safer or riskier?

Call testneo_get_pr_validation_history with project_id <ID>, limit 15. Call testneo_run_agent_workflow with workflow_type "qa_intelligence_workflow", project_id <ID>, range "7d", top_failures 3. Cross-reference PR blockers with execution themes. Go/hold recommendation.

Using TestNeo MCP on project <ID>: check release readiness and PR validation history. Should we ship? Give Go/Hold/Go-with-conditions with evidence. Do not run tests.

PR validation → Release Brief

Validate my PR for project_id <ID>. Detect git base/head SHAs and changed_files (do not invent). Call testneo_pr_validation_workflow with sync_jira_before_validate true, execution.run_impacted_tests true, confirm false. Show the FULL Release Brief and workflow_id.

Same as validate my PR, but confirm true so impacted tests can run. If blocking_count > 0, call testneo_suggest_fix with priority_filter "now".

Call testneo_explain_failure with workflow_id "<WORKFLOW_ID>", include_rerun_plan true. Plain English root cause + tests to rerun.

Call testneo_suggest_fix with workflow_id "<WORKFLOW_ID>", priority_filter "all". Show NOW vs NEXT and re-validate plan.

Call testneo_get_pr_validation_detail with workflow_id "<WORKFLOW_ID>". Summarize the full board for QA.

I will change login/auth on project <ID>. Find login tests, get_pr_validation_history limit 10, get_risk_signals for those test ids, optional pre_validate_hint. Report risky tests and what to validate before merge. No execution.

Engineering Memory

Call testneo_list_engineering_memory_patterns with project_id <ID>. Summarize top patterns, trend (worsening/stable), and what to watch on the next PR.

Call testneo_list_engineering_memory with project_id <ID>. Summarize recent bugs/incidents by area.

Call testneo_get_incident_matches with project_id <ID> and changed_files from my branch (or sample paths like src/auth/login.ts). Summarize prior incidents and known fixes.

Call testneo_get_incident_matches with project_id <ID> and changed_files: [{"path":"src/auth/login.ts","status":"modified"},{"path":"src/checkout/CheckoutService.ts","status":"modified"}]. Summarize matches for an EM.

Deep dive: Release Intelligence guide · PR Validation in MCP docs · Workflow 7.

Security FAQ (what customers ask)

More governance detail: Security & Governance.

Troubleshooting

Full list: MCP troubleshooting.

Next steps