Client Onboarding

This guide provides instructions on how to connect various MCP clients to the HITL (Human in the Loop) relay.

Important Notes

The base URL for the HITL relay is: https://hitlrelay.app/mcp-server/mcp/
To support HITL\'s 15-minute timeout for human input, you may need to adjust your client\'s default timeout settings (e.g., from 60 seconds to 900 seconds).
You can customize the agent name displayed in the HITL app in three ways:
- By suffixing the MCP URL: .../mcp/your_agent_name
- By sending an X-MCP-Agent-Name header.
- By default, the name from the Dynamic Client Registration is used. This is especially useful for differentiating multiple instances of the same agent type (e.g., multiple Claude instances).

Instructions for Claude code

Basic syntax

claude mcp add --transport http Human-in-the-Loop https://hitlrelay.app/mcp-server/mcp/

Example with custom agent name via URL suffixing

claude mcp add --transport http Human-in-the-Loop https://hitlrelay.app/mcp-server/mcp/your_agent_name

Example with custom agent name via header

claude mcp add --transport http Human-in-the-Loop https://hitlrelay.app/mcp-server/mcp/ \
  --header "X-MCP-Agent-Name: Your Agent Name"

You also need to modify MCP_TOOL_TIMEOUT in your settings.json to be 900000 (15 minutes). See the Claude Code Settings.json documentation for more details.

Instructions for Codex CLI

Server transport configuration

STDIO

# The top-level table name must be 'mcp_servers'
# The sub-table name (`server-name` in this example) can be anything you would like.
[mcp_servers.human-in-the-loop]
command = "npx"
# Optional
args = ["-y", "mcp-remote", "https://hitlrelay.app/mcp-server/mcp/codex_cli"]

Streamable HTTP (recent support in Codex CLI)

# Streamable HTTP requires the experimental rmcp client
experimental_use_rmcp_client = true
[mcp_servers.human-in-the-Loop]
url = "https://hitlrelay.app/mcp-server/mcp/codex_cli"

Other configuration options

# Optional: override the default 60s per-tool timeout
tool_timeout_sec = 900

Instructions for Gemini CLI

Configure MCP servers in ~/.gemini/settings.json to extend Gemini CLI with custom tools:

Add an mcpServers object to your settings.json file:

{
  "mcpServers": {
    "human-in-the-loop": {
      "url": "https://hitlrelay.app/mcp-server/mcp/gemini_cli",
     "timeout": 900000
    }
  }
}

Claude Desktop

Configuration for Claude Desktop follows the same pattern as other MCP clients. Add the server configuration to your Claude Desktop settings.

Chat GPT

You can now use the HITL in ChatGPT as it supports remote MCP. Please see the official documentation and this video for more details.

Unfortunately there is an MCP timeout of 60 seconds so you will need to respond within that time or the request will fail. You can still send one-way notifications to your phone which could be useful for longer running tasks.

Cursor

Install in Cursor manually:

Press Cmd/Ctrl + Shift + J to open Cursor Settings
Select Tools and Integrations
Select New MCP Server
Add the following configuration:

{
  "mcpServers": {
    "human-in-the-loop": {
      "url": "https://hitlrelay.app/mcp-server/mcp/cursor"
    }
  }
}

Optional: To use the service with cursor-agent:

cursor-agent mcp login human-in-the-loop

Windsurf

Press Ctrl/Cmd + , to open Windsurf settings
Scroll to Cascade → MCP servers
Select Add Server → Add custom server
Add the following configuration:

{
  "mcpServers": {
    "human-in-the-loop": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://hitlrelay.app/mcp-server/mcp/windsurf"]
    }
  }
}

Zed

Press Cmd + , to open Zed settings
Add the following configuration:

{
  "context_servers": {
    "human-in-the-loop": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://hitlrelay.app/mcp-server/mcp/zed"],
      "env": {}
    }
  }
}

ROOCODE

Use mcp-remote or equivalent proxy for ROOCODE:

{
  "mcpServers": {
    "human-in-the-loop": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://hitlrelay.app/mcp-server/mcp/roocode"],
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

For Streamable HTTP support:

{
  "mcp.servers": {
    "human-in-the-loop": {
      "type": "streamable-http",
      "url": "https://hitlrelay.app/mcp-server/mcp/roocode"
    }
  }
}