MCP Integration (Claude Desktop)

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

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

Review Not Appearing in Dashboard

Check API is running:

curl https://api.humancheck.dev/health \
  -H "Authorization: Bearer your-api-key-here"

Verify database connection:
humancheck status

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:

Use non-blocking requests and check back later
Increase timeout in Claude Desktop settings
Use the dashboard for faster review

Best Practices

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

Next Steps

Learn about REST API Integration for programmatic access
Explore LangChain Integration for LangChain agents
Check out Use Cases for real-world examples

Getting started

Products

Integrations

Use cases

Configuration

Platform Features

Connectors

Dashboard

MCP Integration (Claude Desktop)

What is MCP?

Setup

1. Install Humancheck

2. Configure Claude Desktop

3. Restart Claude Desktop

4. Start Humancheck Services

Available Tools

1. `request_review`

2. `check_review_status`

3. `get_review_decision`

4. `submit_feedback`

Usage Examples

Example 1: Payment Approval

Example 2: Data Deletion

Example 3: Checking Review Status

Workflow Patterns

Blocking Pattern

Non-blocking Pattern

Configuration

Troubleshooting

Claude Can’t Find Humancheck

Review Not Appearing in Dashboard

Timeout Issues

Best Practices

Next Steps

​What is MCP?

​Setup

​1. Install Humancheck

​2. Configure Claude Desktop

​3. Restart Claude Desktop

​4. Start Humancheck Services

​Available Tools

​1. request_review

​2. check_review_status

​3. get_review_decision

​4. submit_feedback

​Usage Examples

​Example 1: Payment Approval

​Example 2: Data Deletion

​Example 3: Checking Review Status

​Workflow Patterns

​Blocking Pattern

​Non-blocking Pattern

​Configuration

​Troubleshooting

​Claude Can’t Find Humancheck

​Review Not Appearing in Dashboard

​Timeout Issues

​Best Practices

​Next Steps

What is MCP?

Setup

1. Install Humancheck

2. Configure Claude Desktop

3. Restart Claude Desktop

4. Start Humancheck Services

Available Tools

1. `request_review`

2. `check_review_status`

3. `get_review_decision`

4. `submit_feedback`

Usage Examples

Example 1: Payment Approval

Example 2: Data Deletion

Example 3: Checking Review Status

Workflow Patterns

Blocking Pattern

Non-blocking Pattern

Configuration

Troubleshooting

Claude Can’t Find Humancheck

Review Not Appearing in Dashboard

Timeout Issues

Best Practices

Next Steps