hitl

HITL MCP Server (HitL) provides a bridge between Claude Desktop and your Human-In-The-Loop escalation service. It allows you to create, modify, approve, reject, and fetch details of HITL escalations directly from Claude Desktop, enabling semi-autonomous agent workflows with human-in-the-loop approvals. The server exposes tools to manage escalations and stores interaction context for auditing and future enhancements. With Cogito HITL support, you can escalate actions such as licensing purchases, feature requests, or any task requiring human oversight, and route notifications through your chosen channels (Slack, Teams, WhatsApp, Telegram, etc.). To use it, configure Claude Desktop to reach the HITL MCP server (in this setup via Docker) and leverage the available commands to manage HITL escalations.

Prerequisites:

• Docker Desktop installed and running
• Node.js 18+ (for local troubleshooting) [optional if using Docker]
• AGENTMP API Key from your platform
• Claude Desktop application

Option A: Docker Deployment (Recommended)

1. Pull and run the HITL MCP server container:

docker pull agentmp/hitl-mcp-server:latest

# Run the container in detached mode with your API key
docker run -d \
  --name hitl-mcp-server \
  --env AGENTMP_API_KEY="<YOUR AGENTMP API KEY>" \
  --restart unless-stopped \
  agentmp/hitl-mcp-server

2. Note the container name (hitl-mcp-server) for Claude Desktop configuration.

Option B: Local Node.js Deployment (Troubleshooting/Development)

1. Install dependencies:

npm install

2. Set your API key:

export AGENTMP_API_KEY="your_api_key_here"

3. Run the server locally (if you have a local Node.js setup and want to test without Docker):

node app.js

Claude Desktop Configuration (both options)

1. Open Claude Desktop → Settings → Developer → Edit Config
2. 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"
      }
    }
  }
}

3. Or, 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"
      }
    }
  }
}

4. Save and restart Claude Desktop.

Testing the setup

• If using Docker, ensure the container is running and reachable by Claude Desktop.
• Example sanity check: run the server locally and verify you see the startup messages as shown in the README.

Tips and common considerations:

• Ensure AGENTMP_API_KEY is valid and kept secure. Do not expose in public repos.
• If you encounter issues with the container not starting, verify Docker is running and the container name matches hitl-mcp-server.
• The MCP configuration expects Docker-based execution; adjust the path to app.js only if you’re using a non-typical image layout.
• The server exposes endpoints for MCP communication; your HITL service endpoints (provided by AGENTMP) must be reachable from the container or local environment.
• If you need additional channels for push notifications, configure Cogito HITL channels at agentmp.ai/linkchannels and ensure channel identifiers are set up in your AGENTMP account.
• For troubleshooting, consult the HITL.mcp-server logs and verify API key initialization messages during startup.