MCP

Add Runhuman to your AI coding agent via MCP.

Recommended: For most users, Agent Skills is the simplest way to get started. Use MCP if your agent doesn’t support skills or you prefer MCP configuration.

Installation

One command adds Runhuman to your agent:

Available Tools

Runhuman exposes 7 MCP tools for orchestrating human QA testing:

list_organizations

List all organizations the authenticated user belongs to. Use this to discover your workspace before creating jobs.

No parameters required. Returns organization name, ID, project count, and member count.

list_projects

List projects accessible to the authenticated user, optionally filtered by organization.

Parameter	Required	Description
organizationId	No	Filter projects by organization ID. If omitted, returns all accessible projects

Returns project name, ID, GitHub repo, and default URL.

create_job

Creates a custom QA test and returns immediately with a job ID. You must follow up with wait to get results.

Parameter	Required	Description
projectId	Yes*	Project ID for the test job
organizationId	No	Organization ID for billing context, or to auto-create a project with `githubRepo`
url	No	URL to test (publicly accessible)
description	No	Instructions for the human tester
template	No	Template name to use as base configuration
templateContent	No	Raw template content (markdown with YAML frontmatter) as alternative to saved template
outputSchema	No	JSON Schema for structured result extraction. If omitted, only success/explanation returned
resultsTemplate	No	MDForm template for free-form text reports (alternative to outputSchema)
targetDurationMinutes	No	Time limit in minutes (default: 30, range: 1-60)
allowDurationExtension	No	Allow tester to request more time (default: true)
maxExtensionMinutes	No	Max additional minutes, or `false` for unlimited (default: false)
additionalValidationInstructions	No	Custom instructions for AI validation
deviceClass	No	`"desktop"` or `"mobile"` (default: “desktop”)
attachments	No	Array of file attachments for the tester (max 10)
githubRepo	No	GitHub repo (`"owner/repo"`) for AI context
githubToken	No	GitHub token for operations without GitHub App installation
prNumbers	No	PR numbers to test — triggers AI test plan generation from PR changes (requires githubRepo)
issueNumbers	No	Issue numbers to test — triggers AI test plan generation from issues (requires githubRepo)
checkTestability	No	Reject job early if AI determines it’s not testable (default: true when prNumbers/issueNumbers provided)

*projectId is required unless organizationId + githubRepo are provided for auto-creation.

Either url+description, template, or prNumbers/issueNumbers is needed to define what to test.

run_template

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

Parameter	Required	Description
projectId	Yes	Project ID for the test job
template	Yes	Template name (get from list_templates)
url	No	Override template’s default URL
description	No	Additional instructions (appended to template)
outputSchema	No	Override template’s output schema
targetDurationMinutes	No	Override template’s duration (range: 1-60)
deviceClass	No	Override template’s device class
githubRepo	No	Override template’s GitHub repo
attachments	No	Override template’s attachments
additionalValidationInstructions	No	Extra validation rules (appended to template)

Use list_templates to see available templates, then reference them by name.

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, min: 10, 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
testerAlias: Tester identification
testerResponse: Raw feedback from the human tester
costUsd: Exact cost in USD
testDurationSeconds: Time spent by tester
jobUrl: Link to view results in the dashboard

get_job

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

Parameter	Required	Description
jobId	Yes	Job ID to check

Returns different detail levels based on status:

Active (pending, preparing, waiting, working): Current state description and next steps
Completed: Full results, tester info, cost, and duration
Failed (incomplete, abandoned, rejected, error): Failure reason and details

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

list_templates

List available templates for a project.

Parameter	Required	Description
projectId	Yes	Project ID to list templates for
limit	No	Max templates to return (default: 50)

Returns template names, default 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 discovers your workspace with list_organizations and list_projects
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 30 minutes. For simple checks, you can request less time (e.g., 5 minutes).

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:

{
  "projectId": "proj-abc123",
  "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:

Test Completed

Job ID: job-abc123
Status: completed
Duration: 120s
Cost: $0.216
Tester: Alex

Results:
  loginWorks: true
  errorShown: true
  errorMessage: Invalid username or password

Raw Response:
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.

View in dashboard: https://runhuman.com/dashboard/...

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