Developers

Integrate agents via MCP tools or REST APIs. Keep a Human‑in‑the‑Loop for safe decisions, with optional end‑to‑end encryption.

Architecture

Agents connect via MCP (Streamable HTTP) or REST; the Relay brokers requests and responses, and the mobile app handles secure notifications and approvals.

MCP Tools

HITL Relay MCP Server exposes three core MCP tools for agents to interact with the user. All human in hte loop interactions have a maximum wait time of 15 minutes for responses of the user

• request_human_input – Request input from the human user with optional choices (for easy human reply)
• notify_human – Send one-way notifications to the user's device
• notify_human_completion – Notify user when a task is complete and wait for acknowledgment. This allows user to review provide feedback or kick off a new task

Note: E2EE versions (request_human_input_e2ee, notify_human_e2ee) available for sensitive data. Agent registration is automatic.

MCP Prompts

HITL Relay MCP server provides a useful starter prompt hitl_coms_only for commnicating to the agent/llm on how to use human loop tool for all further communications with the user

API Keys

Create agent-scoped API keys for programmatic access to HITL from your applications.

# Create a new API key
curl -X POST https://hitlrelay.app/api/v1/api-keys \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"description":"CLI key","agent_id":"<uuid>"}'

# Response
{"api_key":"mcp_pk_...","prefix":"mcp_pk_x"}

Pass API keys via Authorization: Bearer <api_key> header or HITL_API_KEY environment variable.

Key Endpoints

• POST /api/v1/auth/google – exchange Google token for JWT
• GET /api/v1/agents, GET /api/v1/requests, POST /api/v1/requests/:id/respond
• GET /api/v1/usage/* – usage and history
• POST /api/v1/keys/register, GET /api/v1/keys/user

Production Relay: https://hitl-relay.app

Python API Integration

Integrate HITL capabilities directly into your applications using API keys:

import os
import requests

# Set API key via environment variable or directly
API_KEY = os.getenv("HITL_API_KEY", "mcp_pk_...")
BASE_URL = "https://hitlrelay.app/api/v1"
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Request human input
def request_approval(prompt, choices=None):
    payload = {
        "prompt": prompt,
        "choices": choices or ["Approve", "Deny"],
    }
    resp = requests.post(
        f"{BASE_URL}/hitl/request",
        headers=headers,
        json=payload
    )
    resp.raise_for_status()
    return resp.json()

# Send notification
def notify_completion(message):
    payload = {"message": message}
    resp = requests.post(
        f"{BASE_URL}/hitl/notify",
        headers=headers,
        json=payload
    )
    resp.raise_for_status()
    return resp.json()

# Usage
result = request_approval(
    "Deploy to production?",
    ["Deploy Now", "Run Tests First", "Cancel"]
)
print(f"User responded: {result['response']}")

Command Line Interface

Use the HITL CLI for quick integrations from shell scripts and terminal workflows:

# Install (coming soon to PyPI)
# pip install hitl-cli

# Set API key
export HITL_API_KEY="mcp_pk_..."

# Request human input
hitl request "Should I proceed with deployment?" \
  --choices "Yes,No,Ask me later"

# Send notification
hitl notify "Backup completed successfully"

# Notify task completion
hitl complete "Data processing finished" \
  --summary "Processed 10,000 records in 5 minutes"

#There is also a convenient hook for Claude Code to capture the Stop Hook to allow  long running sessions with Claude Code. you will need to add to your settings.json in claude code
hitl-hook-review-and-continue
 

Note: CLI is currently available via GitHub. PyPI package coming soon.