MCP-Human: Human Assistance for AI Assistants

1# MCP-Human: Human Assistance for AI Assistants
2 
3A 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](#limitations) for current constraints.
4 
5![we need to go deeper](./deeper.gif)
6 
7## Setup
8 
9### Prerequisites
10 
11- Node.js 16+
12- AWS credentials with MTurk permissions. See [instructions below](#setting-up-aws-user-with-mechanical-turk-access).
13- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) (recommended for setting aws credentials)
14 
15### Configuring AWS credentials
16 
17```sh
18# Configure AWS credentials for profile mcp-human
19export AWS_ACCESS_KEY_ID="your_access_key"
20export AWS_SECRET_ACCESS_KEY="your_secret_key"
21aws configure set aws_access_key_id ${AWS_ACCESS_KEY_ID} --profile mcp-human
22aws configure set aws_secret_access_key ${AWS_SECRET_ACCESS_KEY} --profile mcp-human
23```
24 
25### Configuring MCP server with your MCP client
26 
27### Claude code
28 
29Sandbox mode:
30 
31```sh
32claude mcp add human -- npx -y mcp-human@latest
33```
34 
35The server defaults to [sandbox mode](https://workersandbox.mturk.com/) (for testing). If you want to submit real requests, use `MTURK_SANDBOX=false`.
36 
37```sh
38claude mcp add human -e MTURK_SANDBOX=false -- npx -y mcp-human@latest
39```
40 
41### Generic
42 
43Update the configuration of your MCP client to the following:
44 
45```json
46{
47  "mcpServers": {
48    "human": {
49      "command": "npx",
50      "args": ["-y", "mcp-human@latest"]
51    }
52  }
53}
54```
55 
56e.g.: Claude Desktop (MacOS): `~/Library/Application\ Support/Claude/claude_desktop_config.json`
57 
58## Configuration
59 
60The server can be configured with the following environment variables:
61 
62| Variable         | Description                                        | Default                          |
63| ---------------- | -------------------------------------------------- | -------------------------------- |
64| `MTURK_SANDBOX`  | Use MTurk sandbox (`true`) or production (`false`) | `true`                           |
65| `AWS_REGION`     | AWS region for MTurk                               | `us-east-1`                      |
66| `AWS_PROFILE`    | AWS profile to use for credentials                 | `mcp-human`                      |
67| `DEFAULT_REWARD` | The reward amount in USD.                          | `0.05`                           |
68| `FORM_URL`       | URL where the form is hosted. Needs to be https.   | `https://syskall.com/mcp-human/` |
69 
70## Setting Up AWS User with Mechanical Turk Access
71 
72To create an AWS user with appropriate permissions for Mechanical Turk:
73 
741. **Log in to the AWS Management Console**:
75 
76   - Go to https://aws.amazon.com/console/
77   - Sign in as a root user or an administrator
78 
792. **Create a new IAM User**:
80 
81   - Navigate to IAM (Identity and Access Management)
82   - Click "Users" > "Create user"
83   - Enter a username (e.g., `mturk-api-user`)
84   - Click "Next" to proceed to permissions
85 
863. **Set Permissions**:
87 
88   - Choose "Attach existing policies directly"
89   - Search for and select `AmazonMechanicalTurkFullAccess`
90   - If you need more granular control, you can create a custom policy with specific MTurk permissions
91   - Click "Next" and then "Create user"
92 
934. **Create Access Keys**:
94 
95   - After user creation, click on the username to go to their detail page
96   - Go to the "Security credentials" tab
97   - In the "Access keys" section, click "Create access key"
98   - Choose "Application running outside AWS" or appropriate option
99   - Click through the wizard and finally "Create access key"
100 
1015. **Save Credentials**:
102 
103   - Download the CSV file or copy the Access key ID and Secret access key
104   - These will be used as `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables
105   - **Important**: This is the only time you'll see the secret access key, so save it securely
106 
1076. **Configure MTurk Requester Settings**:
108   - Visit the MTurk Requester website: https://requester.mturk.com/
109   - Set up payment method and other account details
110   - For testing, use the MTurk Sandbox: https://requestersandbox.mturk.com/
111 
112> **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.
113 
114## Architecture
115 
116This system consists of two main components:
117 
1181. **MCP Server**: A server implementing the Model Context Protocol that integrates with MTurk
1192. **Form**: A static HTML form.
120 
121The 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.
122 
123The Mechanical Turk form used is hosted on GitHub pages: [https://syskall.com/mcp-human/](https://syskall.com/mcp-human/). It gets populated with data through query parameters.
124 
125## MCP Tools
126 
127### askHuman
128 
129Allows an AI to ask a question to a human worker on Mechanical Turk.
130 
131Parameters:
132 
133- `question`: The question to ask a human worker
134- `reward`: The reward amount in USD (default: $0.05)
135- `title`: Title for the HIT (optional)
136- `description`: Description for the HIT (optional)
137- `hitValiditySeconds`: Time until the HIT expires in seconds (default: 1 hour)
138 
139Example usage:
140 
141```javascript
142// From the AI assistant's perspective
143const response = await call("askHuman", {
144  question:
145    "What's a creative name for a smart home device that adjusts lighting based on mood?",
146  reward: "0.25",
147  title: "Help with creative product naming",
148  hitValiditySeconds: 3600, // HIT valid for 1 hour
149});
150```
151 
152If 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.
153 
154### checkHITStatus
155 
156Check the status of a previously created HIT and retrieve any submitted assignments.
157 
158Parameters:
159 
160- `hitId`: The HIT ID to check status for
161 
162Example usage:
163 
164```javascript
165// From the AI assistant's perspective
166const status = await call("checkHITStatus", {
167  hitId: "3XMVN1BINNIXMTM9TTDO1GKMW7SGGZ",
168});
169```
170 
171## Resources
172 
173### mturk-account
174 
175Provides access to MTurk account information.
176 
177URIs:
178 
179- `mturk-account://balance` - Get account balance
180- `mturk-account://hits` - List HITs
181- `mturk-account://config` - Get configuration info
182 
183## Limitations
184 
185- Need to implement [progress notifications](https://github.com/modelcontextprotocol/typescript-sdk/issues/461) to avoid getting timing out.
186- Currently only supports simple text-based questions and answers
187- Limited to one assignment per HIT
188- No support for custom HTML/JS in the form
189- Simple polling for results rather than a webhook approach
190- Uses MTurk's ExternalQuestion format, which requires hosting a form
191