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 21 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.

list_organization_members

List members of an organization with their role, status (active / suspended), owner flag, and join date. Useful before inviting or removing members.

Parameter	Required	Description
organizationId	Yes	Organization ID to list members for

invite_organization_member

Invite someone to an organization by email. Sends a Clerk-backed invitation; the recipient must accept to become a member. Requires the caller to have admin permission in the organization.

Parameter	Required	Description
organizationId	Yes	Organization to invite the user to
email	Yes	Email address of the person to invite
role	No	One of "admin", "contributor", or "viewer" (default: "contributor")

Roles:

• admin — full access including billing, member management, and project creation
• contributor — can edit projects and run jobs, but cannot manage billing or members
• viewer — read-only access to all organization resources

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–60)
maxExtensionMinutes	No	Total extension time in minutes (default: 15). Set to 0 to disable extensions
maxExtensionCount	No	Number of extensions (default: 3). Set to 0 to disable extensions
additionalValidationInstructions	No	Custom instructions for AI validation
deviceClass	No	"desktop", "mobile", or "both" (default: "both")
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.
emailOnCompletion	No	Per-job email-on-completion override: "inherit" (default — defers to project, then account-level Job updates pref), "always", or "never"

*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
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, expired, rejected, error): Failure reason and details

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

get_test_artifacts

Fetch rich session artifacts for a completed job — voice transcript, console logs, network requests, user-interaction events, AI ↔ tester conversation, and AI-identified key moments. Use after get_job or wait when you need to investigate why a test passed or failed.

Parameter	Required	Description
jobId	Yes	Job ID to fetch artifacts for
artifacts	No	Array of artifact types to retrieve. Defaults to all available types.

Artifact types: structured-output, transcript, console-logs, network-requests, conversation, events, key-moments.

All artifact types except structured-output are paid-tier gated server-side; ungated callers receive a clean “subscription required” error.

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", "mobile", or "both" (default: "both")
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

list_tester_notes

List tester knowledge-base notes (credentials, environment details, procedures) visible to the caller. Use this to discover note IDs before editing or deleting.

Parameter	Required	Description
organizationId	No	Restrict to one organization
projectId	No	Restrict to one project (org-wide notes are also returned)
search	No	Full-text search across title and body
tags	No	Filter by tag (credentials, environment, setup, procedures, known-issues, contacts, general)
limit	No	Max notes to return
offset	No	Skip this many notes (pagination)

create_tester_note

Create a tester knowledge-base note scoped to an organization, optionally narrowed to a single project.

Parameter	Required	Description
title	Yes	Note title
body	Yes	Note body (plain text or Markdown)
organizationId	Yes	Organization the note belongs to
projectId	No	Project to scope the note to. Omit for org-wide
tags	No	Tags (see list_tester_notes for allowed values)
isInternal	No	Mark internal-only (Volter staff only)

Returns the new note’s ID for chaining into update_tester_note or delete_tester_note.

update_tester_note

Edit an existing note by ID. Pass any combination of editable fields — at least one is required.

Parameter	Required	Description
noteId	Yes	Note ID to update
title	No	New title
body	No	New body
organizationId	No	Move the note to a different organization
projectId	No	Re-scope to a project, or pass null to clear (move to org-wide)
tags	No	Replace tags
isInternal	No	Toggle internal-only visibility (Volter staff only)

delete_tester_note

Soft-delete (archive) a tester note by ID. Hidden from list_tester_notes but the row is retained for audit.

Parameter	Required	Description
noteId	Yes	Note 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:

1. Agent discovers your workspace with list_organizations and list_projects
2. Agent checks available templates with list_templates (if applicable)
3. Agent calls create_job or run_template with your URL/instructions and an output schema it generates
4. Agent receives a job ID and status message
5. Agent calls wait with that job ID — this automatically polls until complete!
6. When complete, agent receives structured results and the tester’s raw response
7. 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:

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:

{
  "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