hitl-mcp

Human in the Loop MCP Server - allows AI assistants to ask questions and send notifications to humans.

Installation

npm install -g hitl-mcp

Or use directly with npx:

npx hitl-mcp

Setup

1. Get your Convex URL

Your dashboard URL will look like: https://your-app.convex.site

The CONVEX_URL you need is the .convex.cloud version:

https://your-deployment-id.convex.cloud

2. Configure your MCP Client

For Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "hitl": {
      "command": "npx",
      "args": ["-y", "hitl-mcp"],
      "env": {
        "CONVEX_URL": "https://your-deployment.convex.cloud"
      }
    }
  }
}

For Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on Mac):

{
  "mcpServers": {
    "hitl": {
      "command": "npx",
      "args": ["-y", "hitl-mcp"],
      "env": {
        "CONVEX_URL": "https://your-deployment.convex.cloud"
      }
    }
  }
}

3. Keep the Dashboard Open

Open your HITL dashboard in a browser to receive and answer questions.

Tools

notify

Send a notification to the human (fire-and-forget).

notify(title: string, message: string)

ask

Ask a question and wait for the human's response.

ask(question: string, context?: string, timeout_seconds?: number)

Default timeout is 5 minutes.

How It Works

AI Assistant  ──►  hitl-mcp  ──►  Convex  ◄──  Dashboard (You)
     │                │              │              │
     │ ask("Color?")  │              │              │
     │ ─────────────► │ ───────────► │ ──────────► │
     │                │   polling    │              │ type "Blue"
     │ ◄── "Blue" ─── │ ◄─────────── │ ◄────────── │

License

MIT