MCP Setup Guide

Connect your MCP‑capable clients to the HITL Relay as a remote MCP server. Choose direct OAuth/SSE (if your client supports it) or use a local proxy for clients that only support stdio.

Quick Start: Link you phone and client/agent (OAuth)

1. Sign in on the HITL mobile app (User Google Sign in, Apple Sign in, or Email address and password) to register your device.
2. Configure your MCP client to connect to the HITL relay:
   • Direct OAuth clients that support streamable HTTP set the remote endpoint .
   • Stdio‑only clients: use stdio proxy e.g. mcp remote or HITL CLI proxy to inject auth and (optionally) E2EE.
3. OAuth flow should be be automatic and login with the same user id to link the phone to the agent

1) Concepts

• Transport: MCP supports stdio and StreamableHTTP/SSE (server‑sent events) over HTTP.
• Auth: HITL Relay issues JWTs for authenticated users for agent/tool access. Provide this token to the MCP server.
• E2EE (optional): Payloads can be end‑to‑end encrypted using registered public keys (PKI).

2) Direct OAuth/SSE (if supported)

Some MCP clients can connect to a remote HTTP endpoint and send an Authorization header. Use your JWT from Google Sign‑In or MCP agent onboarding.

# Example: Configure your client to connect to the remote MCP endpoint
MCP_REMOTE_URL=https://hitlrelay.app/mcp-server/mcp/
MCP_AUTH_HEADER="Authorization: Bearer $MCP_JWT"

# Your client should pass MCP_AUTH_HEADER on every request to MCP_REMOTE_URL.

Note: If your client doesn’t support remote HTTP/SSE or OAuth headers, use the proxy approach below.

3) Proxy for stdio‑only clients

Use a local proxy to bridge stdio ⇄ HTTP/SSE and inject OAuth headers. Two options:

1. mcp‑remote (community proxy): configure it with your remote URL and Authorization header, then point your client to run the proxy as a stdio server.

   # Pseudo‑example (adjust flags per the proxy you use):
   mcp-remote   --remote-url https://hitlrelay.app/mcp-server/mcp/   --header "Authorization: Bearer $MCP_JWT"   --stdio
   
   # Then configure your client (e.g., Claude Desktop) to run:
   # command: mcp-remote
   # args: ["--remote-url", "https://hitlrelay.app/mcp-server/mcp/", "--header", "Authorization: Bearer $MCP_JWT", "--stdio"]

2. HITL CLI proxy (recommended for E2EE): use the CLI to authenticate, register keys, and run a local stdio proxy that handles OAuth and optional E2EE to the remote server.

   # Authenticate and obtain JWT
   hitl-cli login
   
   # (Optional) Generate and register E2EE keys
   hitl-cli keys generate
   hitl-cli keys register
   
   # Start local stdio proxy with E2EE enabled
   hitl-cli proxy   --remote https://hitlrelay.app/mcp-server/mcp/   --use-e2ee   --stdio
   
   # In your client, configure MCP server command:
   # command: hitl-cli
   # args: ["proxy", "--remote", "https://hitlrelay.app/mcp-server/mcp/", "--use-e2ee", "--stdio"]

4) Tooling verification

Once connected, your MCP client should list HITL tools (request_human_input, request_human_input_e2ee, notify_human, notify_human_e2ee, onboard_agent). Try a dry run:

# Example prompt to exercise the toolchain
"request_human_input: Approve deploy to production? Choices: Yes/No"

5) End‑to‑End Encryption (E2EE)

1. Generate a keypair on each device/agent.
2. Register public keys with the HITL Relay (PKI endpoints).
3. Enable E2EE in the proxy so payloads are encrypted client‑side.
4. Only recipients with the corresponding private keys can decrypt.

# With HITL CLI proxy (example)
hitl-cli keys generate && hitl-cli keys register
hitl-cli proxy --remote https://hitlrelay.app/mcp-server/mcp/ --use-e2ee --stdio