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 15 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 `githubRepos`
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-120). Total with extensions must not exceed 120
maxExtensionMinutes	No	Total extension time in minutes (default: 15). Combined with `targetDurationMinutes` must not exceed 120
maxExtensionCount	No	Number of extensions (default: 3). Set to 0 to disable extensions
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)
githubRepos	No	GitHub repos (`["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 githubRepos)
issueNumbers	No	Issue numbers to test — triggers AI test plan generation from issues (requires githubRepos)
checkTestability	No	Reject job early if AI determines it’s not testable (default: true when prNumbers/issueNumbers provided)
autoCreateGithubIssues	No	Automatically create GitHub issues from AI-extracted test findings after job completion. Requires `githubRepos` to be set.

*projectId is required unless organizationId + githubRepos 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
githubRepos	No	Override template’s GitHub repos (array of `"owner/repo"`)
githubRepo	No	Single GitHub repo (`"owner/repo"`). Use `githubRepos` for multiple
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.

create_template

Create a reusable test template with default configuration.

Parameter	Required	Description
projectId	Yes	Project ID
name	Yes	Template name (must be unique within project)
testDescription	No	Default test instructions for testers
url	No	Default URL to test
outputSchema	No	JSON schema for structured result extraction
resultsTemplate	No	MDForm template for free-form text reports
targetDurationMinutes	No	Expected duration in minutes (1–60)
deviceClass	No	`"desktop"` or `"mobile"` (default: desktop)
githubRepos	No	GitHub repos for context (array of `"owner/repo"`)
githubRepo	No	Single GitHub repo (`"owner/repo"`). Use `githubRepos` for multiple
autoCreateGithubIssues	No	Auto-create GitHub issues from findings

After creating, use the template with run_template or create_schedule.

update_template

Update an existing template’s configuration. Any field can be changed independently.

Parameter	Required	Description
projectId	Yes	Project ID
templateId	Yes	Template ID (get from list_templates)
name	No	New name
testDescription	No	New test instructions
url	No	New default URL
outputSchema	No	New output schema
resultsTemplate	No	New MDForm template
targetDurationMinutes	No	New duration (1–60)
deviceClass	No	New device class
githubRepos	No	New GitHub repos (array of `"owner/repo"`)
githubRepo	No	Single GitHub repo (`"owner/repo"`). Use `githubRepos` for multiple
autoCreateGithubIssues	No	Auto-create GitHub issues

delete_template

Permanently delete a template. Existing schedules using the template will fail on their next execution.

Parameter	Required	Description
projectId	Yes	Project ID
templateId	Yes	Template ID to delete

list_schedules

List recurring test schedules for a project.

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

Returns schedule name, frequency, time, timezone, status, and next execution time.

create_schedule

Create a recurring test schedule that automatically runs a template.

Parameter	Required	Description
projectId	Yes	Project ID
name	Yes	Schedule name
templateId	Yes	Template ID to run (get from list_templates)
scheduledHour	Yes	Hour of day (0–23)
scheduledMinute	Yes	Minute (0, 15, 30, or 45)
timezone	Yes	IANA timezone (e.g., “America/New_York”)
frequency	No	`daily`, `weekly`, `biweekly`, `monthly`, or `once` (default: weekly)
weekdays	No	Days of week for weekly/biweekly (0=Sun..6=Sat)
dayOfMonth	No	Day of month for monthly (1–28, 0=last)
scheduledDate	No	Date for one-time (YYYY-MM-DD)
urlOverride	No	Override the template’s default URL
autoCreateGithubIssuesOverride	No	Auto-create GitHub issues from results

update_schedule

Update a schedule’s settings. Use this to pause/resume, change timing, or swap templates.

Parameter	Required	Description
projectId	Yes	Project ID
scheduleId	Yes	Schedule ID (get from list_schedules)
status	No	`"active"` or `"paused"`
name	No	New name
templateId	No	New template ID
frequency	No	New frequency
scheduledHour	No	New hour (0–23)
scheduledMinute	No	New minute (0, 15, 30, 45)
timezone	No	New timezone
weekdays	No	New weekdays
dayOfMonth	No	New day of month

delete_schedule

Permanently delete a schedule. To temporarily stop without deleting, use update_schedule with status: "paused".

Parameter	Required	Description
projectId	Yes	Project ID
scheduleId	Yes	Schedule ID to delete

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.

Recurring schedule:

Set up a daily smoke test at 9 AM Eastern using the “Smoke Test” template. Run it every weekday.

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.

For recurring tests, the agent can use create_schedule to set up automated runs — no manual polling needed at all.

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