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:

---

The Two Tools

Runhuman exposes two MCP tools:

create_job

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

Parameter	Required	Description
url	Yes	URL to test
description	Yes	Instructions for the tester
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)

The job is queued, not complete. You must call wait_for_result to get results.

wait_for_result

Polls job status and returns results when complete.

Parameter	Required	Description
jobId	Yes	Job ID from create_job
waitSeconds	No	How long to wait (default: 30, max: 300)

Call this repeatedly with increasing wait times until the test completes:

1. First call: waitSeconds: 30
2. If not complete: waitSeconds: 45
3. If still not complete: waitSeconds: 60

The tool checks status before waiting and returns immediately if already complete.

Returns: When complete, includes:

• result: Structured test results matching your schema
• testerResponse: Raw feedback from the human tester
• testerAlias: Anonymized tester name (e.g., “Alex”, “Jordan”)
• 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)

---

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:

1. Agent calls create_job with your URL, instructions, and an output schema it generates
2. Agent receives a job ID and status message
3. Agent calls wait_for_result with that job ID
4. If the test is still running, agent calls wait_for_result again with a longer wait
5. When complete, agent receives structured results and the tester’s raw response
6. Agent summarizes the findings for you

The agent 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:

1. The URL to test
2. Specific actions to perform
3. What success looks like
4. 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_for_result (30s): Response: Still pending, tester not claimed yet

Agent calls wait_for_result (45s): Response: Still in progress, tester is working

Agent calls wait_for_result (60s):

{
  "status": "completed",
  "result": {
    "success": true,
    "data": {
      "loginWorks": true,
      "errorShown": true,
      "errorMessage": "Invalid username or password"
    }
  },
  "testerResponse": "I tested login with the provided credentials...",
  "testerAlias": "Alex",
  "testerAvatarUrl": "https://images.subscribe.dev/uploads/.../phoenix.png",
  "testerColor": "#FF6B35"
}

Agent tells you:

Login test complete. Login works with valid credentials. Error message “Invalid username or password” shown for wrong password.

---

Next Steps

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