What is Mcp Human

MCP-Human is a Model Context Protocol (MCP) server designed to facilitate human assistance for AI assistants. It allows AI systems to request human input when needed by creating tasks on Amazon Mechanical Turk.

Use cases

Use cases for MCP-Human include enhancing AI decision-making with human feedback, conducting surveys or research that require human interaction, and improving the accuracy of AI responses in complex scenarios.

How to use

To use MCP-Human, set up your AWS credentials with MTurk permissions, configure the MCP server with your MCP client, and run the server in sandbox mode for testing or in live mode for real requests.

Key features

Key features of MCP-Human include integration with Amazon Mechanical Turk for human input, support for sandbox and live modes, and the ability to configure the server with environment variables.

Where to use

MCP-Human can be used in various fields where AI systems require human input, such as customer support, data labeling, and interactive AI applications.

MCP-Human: Human Assistance for AI Assistants

A Model Context Protocol (MCP) server that enables AI assistants to get human input when needed. This tool creates tasks on Amazon Mechanical Turk that let real humans answer questions from AI systems. While primarily a proof-of-concept, it demonstrates how to build human-in-the-loop AI systems using the MCP standard. See limitations for current constraints.

Setup

Prerequisites

• Node.js 16+
• AWS credentials with MTurk permissions. See instructions below.
• AWS CLI (recommended for setting aws credentials)

Configuring AWS credentials

# Configure AWS credentials for profile mcp-human
export AWS_ACCESS_KEY_ID="your_access_key"
export AWS_SECRET_ACCESS_KEY="your_secret_key"
aws configure set aws_access_key_id ${AWS_ACCESS_KEY_ID} --profile mcp-human
aws configure set aws_secret_access_key ${AWS_SECRET_ACCESS_KEY} --profile mcp-human

Configuring MCP server with your MCP client

Claude code

Sandbox mode:

claude mcp add human -- npx -y mcp-human@latest

The server defaults to sandbox mode (for testing). If you want to submit real requests, use MTURK_SANDBOX=false.

claude mcp add human -e MTURK_SANDBOX=false -- npx -y mcp-human@latest

Generic

Update the configuration of your MCP client to the following:

{
  "mcpServers": {
    "human": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-human@latest"
      ]
    }
  }
}

e.g.: Claude Desktop (MacOS): ~/Library/Application\ Support/Claude/claude_desktop_config.json

Configuration

The server can be configured with the following environment variables:

Variable	Description	Default
MTURK_SANDBOX	Use MTurk sandbox (true) or production (false)	true
AWS_REGION	AWS region for MTurk	us-east-1
AWS_PROFILE	AWS profile to use for credentials	mcp-human
DEFAULT_REWARD	The reward amount in USD.	0.05
FORM_URL	URL where the form is hosted. Needs to be https.	https://syskall.com/mcp-human/

Setting Up AWS User with Mechanical Turk Access

To create an AWS user with appropriate permissions for Mechanical Turk:

1. Log in to the AWS Management Console:

   • Go to https://aws.amazon.com/console/
   • Sign in as a root user or an administrator

2. Create a new IAM User:

   • Navigate to IAM (Identity and Access Management)
   • Click “Users” > “Create user”
   • Enter a username (e.g., mturk-api-user)
   • Click “Next” to proceed to permissions

3. Set Permissions:

   • Choose “Attach existing policies directly”
   • Search for and select AmazonMechanicalTurkFullAccess
   • If you need more granular control, you can create a custom policy with specific MTurk permissions
   • Click “Next” and then “Create user”

4. Create Access Keys:

   • After user creation, click on the username to go to their detail page
   • Go to the “Security credentials” tab
   • In the “Access keys” section, click “Create access key”
   • Choose “Application running outside AWS” or appropriate option
   • Click through the wizard and finally “Create access key”

5. Save Credentials:

   • Download the CSV file or copy the Access key ID and Secret access key
   • These will be used as AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables
   • Important: This is the only time you’ll see the secret access key, so save it securely

6. Configure MTurk Requester Settings:

   • Visit the MTurk Requester website: https://requester.mturk.com/
   • Set up payment method and other account details
   • For testing, use the MTurk Sandbox: https://requestersandbox.mturk.com/

Note: Always start with the MTurk Sandbox (MTURK_SANDBOX=true) to test your integration without spending real money. Only switch to production when you’re confident in your implementation.

Architecture

This system consists of two main components:

1. MCP Server: A server implementing the Model Context Protocol that integrates with MTurk
2. Form: A static HTML form.

The AI assistant connects to the MCP server, which creates tasks on MTurk. Human workers complete these tasks through a form, and their responses are made available to the AI assistant.

The Mechanical Turk form used is hosted on GitHub pages: https://syskall.com/mcp-human/. It gets populated with data through query parameters.

MCP Tools

askHuman

Allows an AI to ask a question to a human worker on Mechanical Turk.

Parameters:

• question: The question to ask a human worker
• reward: The reward amount in USD (default: $0.05)
• title: Title for the HIT (optional)
• description: Description for the HIT (optional)
• hitValiditySeconds: Time until the HIT expires in seconds (default: 1 hour)

Example usage:

// From the AI assistant's perspective
const response = await call("askHuman", {
  question:
    "What's a creative name for a smart home device that adjusts lighting based on mood?",
  reward: "0.25",
  title: "Help with creative product naming",
  hitValiditySeconds: 3600, // HIT valid for 1 hour
});

If a worker responds within the HIT’s validity period, the response will contain their answer. If not, it will return a HIT ID that can be checked later.

checkHITStatus

Check the status of a previously created HIT and retrieve any submitted assignments.

Parameters:

• hitId: The HIT ID to check status for

Example usage:

// From the AI assistant's perspective
const status = await call("checkHITStatus", {
  hitId: "3XMVN1BINNIXMTM9TTDO1GKMW7SGGZ",
});

Resources

mturk-account

Provides access to MTurk account information.

URIs:

• mturk-account://balance - Get account balance
• mturk-account://hits - List HITs
• mturk-account://config - Get configuration info

Limitations

• Need to implement progress notifications to avoid getting timing out.
• Currently only supports simple text-based questions and answers
• Limited to one assignment per HIT
• No support for custom HTML/JS in the form
• Simple polling for results rather than a webhook approach
• Uses MTurk’s ExternalQuestion format, which requires hosting a form