> ## Documentation Index
> Fetch the complete documentation index at: https://docs.humancheck.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Integration (Claude Desktop)

> Native integration with Claude Desktop via MCP protocol

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

```bash theme={null}
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:

```json theme={null}
{
  "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:

```bash theme={null}
humancheck start
```

Or if you only need the API (MCP doesn't require the dashboard):

```bash theme={null}
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`:

```yaml theme={null}
# 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**:
   ```bash theme={null}
   which humancheck
   ```
   If not found, add the installation location to your PATH.

3. **Check logs**:
   ```bash theme={null}
   humancheck logs
   ```

4. **Test MCP server manually**:
   ```bash theme={null}
   humancheck mcp
   ```

### Review Not Appearing in Dashboard

1. **Check API is running**:
   ```bash theme={null}
   curl https://api.humancheck.dev/health \
     -H "Authorization: Bearer your-api-key-here"
   ```

2. **Verify database connection**:
   ```bash theme={null}
   humancheck status
   ```

3. **Check review was created**:
   ```bash theme={null}
   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

* Learn about [REST API Integration](/integrations/rest-api) for programmatic access
* Explore [LangChain Integration](/integrations/langchain) for LangChain agents
* Check out [Use Cases](/use-cases/payment-approval) for real-world examples