AgentMP/hitl-mcp-server

HITL MCP Server

A Model Context Protocol (MCP) server that bridges Claude Desktop with your HITL (Human In The Loop) escalation service. This allows Claude to create, approve, modify, reject, and manage HITL escalations directly from Claude Desktop.

https://hub.docker.com/r/agentmp/hitl-mcp-server

Features

• Create HITL Escalations: Create new escalation requests with proposed actions
• Approve Escalations: Approve pending escalations with optional comments
• Modify Escalations: Modify existing escalations with new actions
• Reject Escalations: Reject escalations with optional comments
• Get Escalation Details: Retrieve details of specific escalations
• List Escalations: List all escalations for the authenticated user

Prerequisites

• Node.js 18+
• Docker (optional, for containerized deployment)
• AGENTMP API Key from your platform
• Claude Desktop application

Steps to Configure Cogito HITL on Claude Desktop

(Please refer to SetupClaudeDesktop.md for steps)

Setup

Option 1: Docker Deployment (Recommended)

1. Clone or create the project files:

   mkdir hitl-mcp-server
   cd hitl-mcp-server
   

2. Create all the required files (app.js, package.json, package-lock.json, Dockerfile, docker-compose.yml)

3. Set your API key:

   export AGENTMP_API_KEY="your_api_key_here"
   

4. Build and run the container:

   chmod +x run.sh
   ./run.sh
   

   Or manually:

   docker-compose up --build -d
   

Option 2: Local Node.js Deployment (Recommended for troubleshooting)

1. Install dependencies:

   npm install
   

2. Set your API key:

   export AGENTMP_API_KEY="your_api_key_here"
   

3. Use the setup script:

   chmod +x setup-local.sh
   ./setup-local.sh
   

4. Or run manually:

   node app.js
   

Testing Your Setup

Before configuring Claude Desktop, test your setup:

# Test the server directly
export AGENTMP_API_KEY="your_api_key"
node app.js

If working correctly, you should see:

🚀 Starting HITL MCP Server...
✅ API Key loaded successfully  
🔧 Setting up request handlers...
✅ HITL MCP Server initialized successfully
🌟 HITL MCP Server running and connected via stdio
📡 Ready to handle HITL requests from Claude Desktop

Claude Desktop Configuration

To use this MCP server with Claude Desktop, you need to configure it in your Claude Desktop settings.

Configuration Steps

1. Open Claude Desktop
2. Go to Settings → Developer
3. Edit Config (this opens your MCP configuration file)
4. Add the following configuration:

For Docker Deployment:

{
  "mcpServers": {
    "hitl": {
      "command": "docker",
      "args": ["exec", "-i", "hitl-mcp-server", "node", "app.js"],
      "env": {
        "AGENTMP_API_KEY": "your_api_key_here"
      }
    }
  }
}

For Local Node.js Deployment:

{
  "mcpServers": {
    "hitl": {
      "command": "node",
      "args": ["/path/to/your/hitl-mcp-server/app.js"],
      "env": {
        "AGENTMP_API_KEY": "your_api_key_here"
      }
    }
  }
}

5. Save the configuration file
6. Restart Claude Desktop

Usage Examples

Once configured, you can use the following commands in Claude Desktop:

Create a HITL Escalation

Create a HITL escalation for session "sess-123" with agent "my-agent" for a purchase of "Premium License" costing $99.99. Escalate to user "user@example.com" with normal priority.

Approve an Escalation

Approve HITL escalation "esc-123456789" with comment "Approved for purchase"

Modify an Escalation

Modify HITL escalation "esc-123456789" to change the item to "Enterprise License" and amount to $199.99 with comment "Upgraded to enterprise"

Reject an Escalation

Reject HITL escalation "esc-123456789" with comment "Budget exceeded"

Get Escalation Details

Get details for HITL escalation "esc-123456789"

List All Escalations

List all my HITL escalations

Available Tools

The MCP server provides the following tools:

1. create_hitl: Create a new HITL escalation request
2. approve_hitl: Approve a HITL escalation
3. modify_hitl: Modify a HITL escalation with new action
4. reject_hitl: Reject a HITL escalation
5. get_hitl: Get details of a specific HITL escalation
6. list_hitls: List all HITL escalations for the authenticated user

Environment Variables

• AGENTMP_API_KEY (required): Your API key for the AGENTMP platform

API Endpoints Used

The server communicates with your HITL service using these endpoints:

• POST /api/hitl/mcp - MCP JSON-RPC endpoint for create, approve, modify
• POST /api/hitl/{id}/reject - REST endpoint for rejecting escalations
• GET /api/hitl/{id} - REST endpoint for getting escalation details
• GET /api/hitl - REST endpoint for listing escalations

Troubleshooting

Common Issues

1. "No such container: hitl-mcp-server"

   • The Docker container isn't running
   • Run: docker-compose up -d to start it
   • Check: docker ps | grep hitl-mcp-server to verify it's running
   • Recommendation: Use local Node.js setup instead

2. "Cannot find module '@modelcontextprotocol/sdk/server/index.js'"

   • Dependencies not installed locally
   • Run: npm install in the project directory
   • Make sure you're in the correct directory with package.json

3. API Key Not Set

   • Ensure AGENTMP_API_KEY environment variable is properly set
   • Check that the API key is valid and has proper permissions

4. Container Not Starting

   • Check Docker logs: docker logs hitl-mcp-server
   • Ensure the API key is provided in the environment

5. Claude Desktop Not Recognizing Server

   • Verify the MCP configuration syntax in Claude Desktop
   • Check that the path to the script is correct (use absolute path)
   • Restart Claude Desktop after configuration changes
   • For local setup, use the config format provided by setup-local.sh

6. Connection Issues

   • Ensure your network allows connections to backend.agentmp.io
   • Check if any firewall rules are blocking the connection

Logs

For Docker deployment, view logs with:

docker logs hitl-mcp-server

For local deployment, logs will appear in the terminal where you ran npm start.

Security Considerations

• Store your API key securely and never commit it to version control
• The container runs as a non-root user for security
• Consider using Docker secrets for production deployments
• Regularly rotate your API keys

Contributing

Feel free to submit issues and enhancement requests!

License

MIT License

Set your API key

export AGENTMP_API_KEY="99aeae0e6b4f4107a59d1b59010834cb3eb96ae0f667078f7cc2a296dad27785"

Build the image

docker build -t hitl-mcp-server .

Run the container

docker run -d
--name hitl-mcp-server
--env AGENTMP_API_KEY="99aeae0e6b4f4107a59d1b59010834cb3eb96ae0f667078f7cc2a296dad27785"
--restart unless-stopped
-i
hitl-mcp-server

Perfect! Your Docker container is running successfully (ID: 3c10bcf71a6d...).

🎯 Claude Desktop Configuration

Open Claude Desktop → Settings → Developer → Edit Config and add this:## 📝 Setup Steps

1. Save the config above in Claude Desktop
2. Restart Claude Desktop
3. Test with the examples below

🧪 Simple Test Cases

Here are test cases from basic to advanced:

Test 1: List Existing HITLs (Basic)

List all my HITL escalations

Expected: Should show your existing HITL escalations or empty list

Test 2: Create a HITL Escalation (Core Function)

Create a HITL escalation with these details:
- Session ID: "test-session-123"  
- Agent ID: "claude-test-agent"
- User prompt: "User wants to purchase premium subscription"
- Proposed action: Purchase of "Premium Plan" for $29.99
- Escalate to: "karthik6461@gmail.com"
- Priority: "normal"

Expected: Should return escalation ID like "esc-xxxxx-xxxxx-xxxxx"

Test 3: Get HITL Details (Verification)

Get details for HITL escalation "esc-[ID-FROM-TEST-2]"

Replace [ID-FROM-TEST-2] with the actual ID from Test 2

Test 4: Approve HITL (Action)

Approve HITL escalation "esc-[ID-FROM-TEST-2]" with comment "Approved for testing purposes"

Test 5: Create and Modify (Advanced)

Create a HITL escalation for a $50 software license purchase, then modify it to $75 enterprise license

🔍 Quick Verification Commands

Before testing in Claude, verify your container:

# Check container is running
docker ps | grep hitl-mcp-server

# Check container logs
docker logs hitl-mcp-server

# Test the container directly
docker exec -i hitl-mcp-server node -e 'console.log("✅ Container is working!")'

📊 Expected Claude Responses

If working correctly, Claude should:

• ✅ Recognize the HITL tools automatically
• ✅ Create escalations and return IDs like esc-xxxxx-xxxxx-xxxxx
• ✅ Show JSON responses with escalation details
• ✅ Handle approve/modify/reject operations

🚨 If Something Goes Wrong

1. Check Docker logs: docker logs hitl-mcp-server
2. Restart Claude Desktop after any config changes
3. Verify container is running: docker ps | grep hitl-mcp-server

Start with Test 1 (list HITLs) - it's the safest and will confirm the connection is working!