MCP

Add Runhuman to your AI coding agent. Ask it to run human QA tests in natural language.

Installation

One command adds Runhuman to your agent:

Available Tools

Runhuman exposes 5 MCP tools for orchestrating human QA testing:

create_job

Creates a custom QA test and returns immediately with a job ID.

Parameter	Required	Description
url	No*	URL to test
description	Yes*	Instructions for the tester
template	No	Template name to use as base configuration
outputSchema	No	JSON Schema for result extraction. If omitted, only success/explanation returned
targetDurationMinutes	No	Time limit (default: 5)
allowDurationExtension	No	Allow tester to request more time (default: true)
maxExtensionMinutes	No	Max extension allowed (default: unlimited)
additionalValidationInstructions	No	Custom instructions for AI validation
screenSize	No	”desktop”, “laptop”, “tablet”, “mobile”, or custom dimensions
repoName	No	GitHub repo (“owner/repo”) for AI context
canCreateGithubIssues	No	Auto-create GitHub issues from bugs (requires repoName)

*Either url+description OR template is required.

run_template

⭐ Templates are important! Create a job from a pre-configured template. Templates let you reuse test configurations without writing full descriptions every time.

Parameter	Required	Description
template	Yes	Template name (get from list_templates)
url	No	Override template’s default URL
description	No	Additional instructions (appended to template)
any create_job param	No	Override any template default

Use list_templates to see available templates, then reference them by name. Much faster than writing full test descriptions!

wait

Idiomatic polling - Waits for a job to complete and returns results automatically. Polls every 10 seconds until completion, timeout, or failure.

Parameter	Required	Description
jobId	Yes	Job ID from create_job or run_template
timeoutSeconds	No	Maximum wait time (default: 600, max: 3600)

No manual polling needed! Just call wait once and it automatically polls until the job finishes.

Returns: When complete, includes:

result: Structured test results matching your schema
testerResponse: Raw feedback from the human tester
testerName/testerAlias: Tester identification
testerAvatarUrl: Avatar image URL for UI display
testerColor: Hex color for tester identity (e.g., “#FF6B35”)
testerData: Testing artifacts (screenshots, video, console logs, network requests, clicks)
costUsd: Exact cost in USD
testDurationSeconds: Time spent by tester

get_job

Quick status check without waiting. Get current job status instantly without polling.

Parameter	Required	Description
jobId	Yes	Job ID to check

Use this for manual polling control or checking multiple jobs in parallel.

list_templates

List available templates for your project.

Parameter	Required	Description
limit	No	Max templates to return (default: 50)

Returns array of templates with names, URLs, and descriptions.

Example Prompts

These prompts work well with any AI agent that has Runhuman installed:

Simple page check:

Use Runhuman to verify that example.com loads correctly and shows the main heading.

Login testing:

Use Runhuman to test the login flow on staging.myapp.com. Try email test@example.com with password demo123, then try a wrong password and verify the error message.

Checkout flow:

Use Runhuman to test the checkout on myapp.com. Add a product to cart, fill shipping info, and verify the order total is correct. Give the tester 10 minutes.

Visual issues:

Use Runhuman to check the product page at myapp.com/products/123 for visual issues. Look for broken images, layout problems, or unreadable text.

Mobile testing:

Use Runhuman to test the navigation menu on myapp.com on mobile. Check if it opens and closes correctly and all links work.

What Happens Behind the Scenes

When you ask your agent to use Runhuman:

Agent checks available templates with list_templates (if applicable)
Agent calls create_job or run_template with your URL/instructions and an output schema it generates
Agent receives a job ID and status message
Agent calls wait with that job ID - this automatically polls until complete!
When complete, agent receives structured results and the tester’s raw response
Agent summarizes the findings for you

The wait tool handles all the polling logic automatically. You just describe what you want tested.

Duration Control

Tell the agent how much time to give the tester:

Use Runhuman to test the signup flow. Allow 10 minutes since this involves email verification.

Use Runhuman to check the homepage. This should be quick, give the tester 3 minutes.

The default is 5 minutes. For complex flows, explicitly request more time.

Writing Good Prompts

Good prompts are specific about what to test:

Instead of	Write
”Test the app"	"Test the login flow on myapp.com. Try valid credentials, then invalid password. Verify error messages."
"Check the UI"	"Check the product page for visual issues. Look for broken images, layout problems, text overflow."
"Test checkout"	"Test checkout on staging.myapp.com. Add product to cart, fill shipping, verify total before submitting.”

Include:

The URL to test
Specific actions to perform
What success looks like
Time needed for complex flows

Complete Example

Here’s what an agent does when you ask it to test a login page:

You say:

Use Runhuman to test login on myapp.com with email test@example.com and password demo123. Then try wrong password and check the error.

Agent calls create_job:

{
  "url": "https://myapp.com/login",
  "description": "Test login with test@example.com / demo123, then try wrong password",
  "outputSchema": {
    "loginWorks": { "type": "boolean", "description": "Login works with valid credentials" },
    "errorShown": { "type": "boolean", "description": "Error shown for wrong password" },
    "errorMessage": { "type": "string", "description": "Error message text" }
  }
}

Agent calls wait:

{
  "jobId": "job-abc123"
}

The wait tool automatically polls every 10 seconds until complete. No manual polling needed!

After 2-3 minutes, wait returns:

{
  "status": "completed",
  "result": {
    "loginWorks": true,
    "errorShown": true,
    "errorMessage": "Invalid username or password"
  },
  "testerResponse": "I tested login with the provided credentials. Login works correctly with test@example.com. When I tried a wrong password, the error message 'Invalid username or password' appeared.",
  "testerName": "Alex",
  "testerAvatarUrl": "https://images.subscribe.dev/uploads/.../phoenix.png",
  "testerColor": "#FF6B35",
  "costUsd": 0.216,
  "testDurationSeconds": 120
}

Agent tells you:

✅ Login test complete! Login works with valid credentials. Error message “Invalid username or password” shown for wrong password. Test took 2 minutes, cost $0.22.

Next Steps

Topic	Link
Full technical specification	Reference
Practical recipes	Cookbook
Direct API integration	REST API