Skip to main content
Humancheck provides native integration with Claude Desktop through the Model Context Protocol (MCP). This allows Claude to automatically request human review when it encounters uncertain or high-stakes decisions.

​
What is MCP?

The Model Context Protocol (MCP) is a standardized protocol that enables AI assistants like Claude Desktop to interact with external tools and services. Humancheck’s MCP server provides tools that Claude can use to request reviews and get decisions.

​
Setup

​
1. Install Humancheck

pip install humancheck

​
2. Configure Claude Desktop

Add Humancheck to your Claude Desktop MCP configuration: macOS: 
~/Library/Application Support/Claude/claude_desktop_config.json
Windows: 
%APPDATA%\Claude\claude_desktop_config.json
Linux: 
~/.config/Claude/claude_desktop_config.json
Add the following configuration: 
{
  "mcpServers": {
    "humancheck": {
      "command": "humancheck",
      "args": ["mcp"]
    }
  }
}

​
3. Restart Claude Desktop

After updating the configuration, restart Claude Desktop for the changes to take effect.

​
4. Start Humancheck Services

Make sure Humancheck is running: 
humancheck start
Or if you only need the API (MCP doesn’t require the dashboard): 
humancheck start --api-only

​
Available Tools

Once configured, Claude has access to the following Humancheck tools:

​
1. request_review

Request human review for an AI agent decision. Parameters:
  • task_type (string): Type of task (e.g., “payment”, “data_deletion”)
  • proposed_action (string): The action you want to take
  • reasoning (string, optional): Why you’re requesting review
  • confidence_score (float, optional): Confidence score (0.0-1.0)
  • urgency (string, optional): “low”, “medium”, “high”, or “critical”
  • metadata (object, optional): Custom metadata
Returns:
  • review_id (integer): ID of the created review
  • status (string): Review status
  • dashboard_url (string): Link to view in dashboard

​
2. check_review_status

Check the status of a review. Parameters:
  • review_id (integer): ID of the review
Returns:
  • status (string): Current status
  • task_type (string): Type of task
  • proposed_action (string): The proposed action

​
3. get_review_decision

Get the decision for a review (if available). Parameters:
  • review_id (integer): ID of the review
Returns:
  • decision_type (string): “approve”, “reject”, or “modify”
  • modified_action (string, if modified): The modified action
  • notes (string, optional): Notes from the reviewer

​
4. submit_feedback

Submit feedback on a review or decision. Parameters:
  • review_id (integer): ID of the review
  • rating (integer): Rating from 1-5
  • comment (string, optional): Feedback comment

​
Usage Examples

​
Example 1: Payment Approval

Claude will automatically use the tool when it encounters high-stakes operations: 
User: I need to process a payment of $10,000 to ACME Corp.

Claude: I'll help you process that payment. Since this is a high-value 
payment, let me request human review first.

<uses request_review tool>
  task_type: "payment"
  proposed_action: "Process payment of $10,000 to ACME Corp"
  reasoning: "High-value payment requires human approval"
  confidence_score: 0.85
  urgency: "high"

I've requested human review for this payment. The review ID is 123. 
You can view it in the dashboard at http://localhost:8501.

Would you like me to check the status of the review?

​
Example 2: Data Deletion

User: Delete all data for user@example.com per GDPR request.

Claude: I'll help with that GDPR deletion request. This is a sensitive 
operation, so let me request human review first.

<uses request_review tool>
  task_type: "data_deletion"
  proposed_action: "Delete all data for user@example.com"
  reasoning: "GDPR deletion request"
  urgency: "medium"

Review requested (ID: 124). You can approve it in the dashboard.

​
Example 3: Checking Review Status

User: What's the status of review 123?

Claude: Let me check that for you.

<uses check_review_status tool>
  review_id: 123

The review status is "approved". The payment has been approved and 
can be processed.

​
Workflow Patterns

​
Blocking Pattern

When Claude needs an immediate decision: 
User: Process this payment and wait for approval.

Claude: <uses request_review>
       <waits for decision>
       <uses get_review_decision>
       
The payment has been approved. Processing...

​
Non-blocking Pattern

When Claude can continue with other work: 
User: Request review for this payment, I'll check back later.

Claude: <uses request_review>
       
Review requested (ID: 125). You can check the status later or 
I can check it for you when you're ready.

​
Configuration

You can customize the MCP server behavior in humancheck.yaml: 
# MCP Configuration
mcp_server_name: humancheck
mcp_version: 0.1.0

# API Configuration (MCP uses this)
api_host: 0.0.0.0
api_port: 8000

​
Troubleshooting

​
Claude Can’t Find Humancheck

  1. Check configuration file path: Make sure you’re editing the correct config file for your OS.
  2. Verify command is available: 
    which humancheck
    If not found, add the installation location to your PATH.
  3. Check logs: 
    humancheck logs
  4. Test MCP server manually: 
    humancheck mcp

​
Review Not Appearing in Dashboard

  1. Check API is running: 
    curl https://api.humancheck.dev/health \
  -H "Authorization: Bearer your-api-key-here"
  2. Verify database connection: 
    humancheck status
  3. Check review was created: 
    curl https://api.humancheck.dev/reviews \
  -H "Authorization: Bearer your-api-key-here"

​
Timeout Issues

If Claude times out waiting for decisions, you can:
  1. Use non-blocking requests and check back later
  2. Increase timeout in Claude Desktop settings
  3. Use the dashboard for faster review

​
Best Practices

  1. Be specific with task_type: Use consistent task types like “payment”, “data_deletion”, “content_moderation”
  2. Provide clear reasoning: Help reviewers understand why the review is needed
  3. Set appropriate urgency: Use “critical” sparingly, only for truly urgent matters
  4. Include metadata: Add relevant context in the metadata field
  5. Check back periodically: For non-blocking requests, periodically check status

​
Next Steps