Skip to main content
Glama
HITL.sh MCP Server

HITL.sh MCP Server

Official
by hitl-sh

HITL.sh MCP Server

HITL.sh is a mobile-powered Human-in-the-Loop platform designed to give AI systems instant access to real human judgment. The entire system is built around our dedicated mobile app, which is required for the product to function and enables human reviewers to receive and complete tasks in real time.

๐Ÿš€ Quick Start for Users

Choose the endpoint that matches your platform:

For ChatGPT Users (OAuth):

URL: https://mcp.hitl.sh/mcp

  1. Add MCP Connector in ChatGPT with URL above

  2. Sign up through the OAuth flow

  3. (Optional) Add your personal HITL API key at: https://mcp.hitl.sh/setup-api-key

  4. Start using HITL tools!

๐Ÿ“š Full ChatGPT Guide

For OpenAI Agent Builder / Zapier / Make.com (Direct API Key):

URL: https://mcp.hitl.sh/mcp-simple

  1. Add MCP Server with URL above

  2. Authentication: Bearer Token

  3. Token: Your HITL API key (e.g., hitl_live_abc123...)

  4. Start using HITL tools!

๐Ÿ“š Full OpenAI Agent Builder Guide


Related MCP server: Pingfusi

๐Ÿ› ๏ธ For Developers

Features

  • OAuth 2.1 Authentication - Secure OAuth flow with Auth0 integration

  • Per-User API Keys - Users can configure their own HITL.sh API keys

  • Workflow tools - Find, run, build and manage HITL workflows, and choose who reviews them

  • ChatGPT Compatible - Works as a connector in ChatGPT

  • Claude Desktop Support - Standalone stdio server for local use

  • Production Ready - Deployed on Vercel with proper error handling

๐Ÿ› ๏ธ Available Tools

HITL is workflows: an agent runs a workflow, the workflow asks your humans, and the run finishes with their answer.

Tool

Description

list_workflows

List your workflows, newest first

get_workflow

Get a workflow: steps, connections, input fields

get_workflow_input

List the input fields a workflow reads, with an example body

run_workflow

Start a run of an active workflow with its input

get_execution

Get one run; with wait, answer as soon as it has finished

list_workflow_executions

List a workflow's runs

watch_execution

Get a live-updates URL and token for a run

retry_execution

Run a failed run again with the same input

create_workflow, update_workflow, delete_workflow

Build and change workflows

activate_workflow, pause_workflow, test_workflow

Make a workflow runnable, stop it, or test-run it

list_workflow_revisions, publish_workflow_revision

Published versions

list_workflow_humans, invite_to_workflow

Who reviews a workflow; invite people by email

get_workflow_join_code, create_workflow_join_code, delete_workflow_join_code, rotate_workflow_join_code

A workflow's join code

validate_join_code, join_with_code

See where a join code leads; join with it

check_api_key, signup_status, confirm_signup, resend_signup_email

The key and agent signup

Loops, requests, images, sessions, people, organizations, teams, webhooks and uploads are no longer tools (the API still serves them). The workflow routes are live on dev.api.hitl.sh and answer 404 on api.hitl.sh until they ship there; set HITL_API_BASE=https://dev.api.hitl.sh/v1 to use them now.

Both endpoints (/mcp and /mcp-simple) register these tools from @hitl-sh/core, the same package behind the stdio server @hitl-sh/mcp, so the remote and local servers expose identical tools.

๐Ÿ“‹ Prerequisites

๐Ÿ”ง Environment Variables

Required for Production

# HITL.sh Configuration
HITL_API_KEY=hitl_live_your_default_api_key

# Auth0 OAuth Configuration
AUTH0_ISSUER_URL=https://your-tenant.us.auth0.com
AUTH0_AUDIENCE=https://mcp.hitl.sh

# Auth0 M2M Application (for testing OAuth)
AUTH0_CLIENT_ID=your_client_id
AUTH0_CLIENT_SECRET=your_client_secret

# Auth0 Management API (for per-user API keys)
AUTH0_MANAGEMENT_CLIENT_ID=your_management_client_id
AUTH0_MANAGEMENT_CLIENT_SECRET=your_management_client_secret

Optional

# HITL API Base URL override
HITL_API_BASE=https://api.hitl.sh/v1

# Extra hosts allowed to receive the API key (comma-separated). The client only sends
# keys to hitl.sh and its subdomains, so set this to use a local API, e.g.
# HITL_API_BASE=http://localhost:8080/v1 with HITL_ALLOW_HOSTS=localhost
HITL_ALLOW_HOSTS=

๐Ÿš€ Quick Start

1. Clone and Install

git clone <your-repo-url>
cd mcp.hitl.sh
npm install

2. Set Up Auth0

Follow the setup guide in PER_USER_API_KEY_SETUP.md to:

  1. Create an Auth0 account and tenant

  2. Create an API with audience https://mcp.hitl.sh

  3. Create M2M applications for testing and management

  4. Configure Auth0 Action for per-user API keys

3. Configure Environment Variables

Create .env.local:

cp .env.example .env.local
# Edit .env.local with your credentials

4. Run Locally

npm run dev

Server runs on http://localhost:3000

5. Test OAuth Flow

node scripts/test-oauth.mjs http://localhost:3000/mcp

๐ŸŒ Deploy to Vercel

1. Push to GitHub

git add .
git commit -m "Initial commit"
git push origin main

2. Deploy to Vercel

  1. Go to vercel.com/new

  2. Import your GitHub repository

  3. Add all environment variables from .env.local

  4. Click Deploy

3. Configure Auth0 with Vercel URL

Update your Auth0 applications with your Vercel URL:

For ChatGPT OAuth Client (SPA):

  • Allowed Callback URLs: https://chatgpt.com/connector_platform_oauth_redirect

  • Allowed Web Origins: https://chatgpt.com, https://chat.openai.com

  • Allowed Logout URLs: https://chatgpt.com, https://chat.openai.com

๐Ÿค– Using with ChatGPT

1. Create Auth0 SPA Client

  1. Auth0 Dashboard โ†’ Applications โ†’ Create Application

  2. Name: ChatGPT MCP Connector

  3. Type: Single Page Application

  4. Configure callback URLs (see above)

  5. Enable Connections โ†’ Username-Password-Authentication

2. Connect in ChatGPT

  1. ChatGPT โ†’ Settings โ†’ MCP Connectors

  2. Add connector with your Vercel URL:

    https://your-app.vercel.app

    (Note: Use base URL, not /mcp endpoint)

  3. Authentication: OAuth

  4. Complete login flow

3. Set Your HITL API Key

Visit https://your-app.vercel.app/setup-api-key to configure your personal HITL.sh API key.

๐Ÿ’ป Using with Claude Desktop

For local Claude Desktop integration, use the published stdio server @hitl-sh/mcp:

1. Configure Claude Desktop

Add to ~/Library/Application Support/Claude/config.json:

{
  "mcpServers": {
    "hitl": {
      "command": "npx",
      "args": ["-y", "@hitl-sh/mcp"],
      "env": {
        "HITL_API_KEY": "your_hitl_api_key_here"
      }
    }
  }
}

From a clone of this repo, node scripts/claude-desktop-server.mjs runs the same server.

2. Restart Claude Desktop

The HITL tools will appear in Claude Desktop!

See CLAUDE_DESKTOP_SETUP.md for detailed instructions.

๐Ÿงช Testing

Test OAuth Flow

node scripts/test-oauth.mjs http://localhost:3000/mcp

Test All Tools

node scripts/test-all-tools.mjs http://localhost:3000/mcp your_api_key

๐Ÿ“ Project Structure

mcp.hitl.sh/
โ”œโ”€โ”€ app/
โ”‚   โ”œโ”€โ”€ mcp/route.ts                    # Main MCP endpoint (OAuth)
โ”‚   โ”œโ”€โ”€ mcp-simple/route.ts             # MCP endpoint with a raw API key
โ”‚   โ”œโ”€โ”€ setup-api-key/page.tsx          # User API key setup page
โ”‚   โ”œโ”€โ”€ api/update-hitl-key/route.ts    # API key update endpoint
โ”‚   โ””โ”€โ”€ .well-known/
โ”‚       โ”œโ”€โ”€ oauth-protected-resource/   # OAuth discovery
โ”‚       โ””โ”€โ”€ oauth-authorization-server/ # Auth server metadata
โ”œโ”€โ”€ lib/
โ”‚   โ””โ”€โ”€ auth0-verify.ts                 # Auth0 token verification
โ”œโ”€โ”€ scripts/
โ”‚   โ”œโ”€โ”€ claude-desktop-server.mjs       # Stdio server (wraps @hitl-sh/core)
โ”‚   โ”œโ”€โ”€ test-oauth.mjs                  # OAuth flow test
โ”‚   โ””โ”€โ”€ test-all-tools.mjs              # All tools test
โ””โ”€โ”€ docs/ (via .md files)

๐Ÿ” Security

  • OAuth 2.1 with PKCE for secure authentication

  • JWT verification using Auth0 JWKS

  • Per-user API keys stored securely in Auth0 user metadata

  • Environment variable fallback for shared API key

  • CORS properly configured for ChatGPT

๐Ÿ“š Documentation

๐Ÿ› Troubleshooting

"Invalid token" errors

  • Check that AUTH0_ISSUER_URL matches your Auth0 tenant

  • Verify token hasn't expired

  • Ensure AUTH0_AUDIENCE is https://mcp.hitl.sh

ChatGPT connection fails

  • Verify Auth0 SPA client has connections enabled

  • Check callback URLs are configured correctly

  • Ensure dynamic client registration is disabled

Per-user API keys not working

  • Verify Auth0 Action is deployed and in Login flow

  • Check user has hitl_api_key in user_metadata

  • User must log out/in to get new token with API key

๐Ÿค Contributing

Contributions welcome! Please:

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Submit a pull request

๐Ÿ“„ License

MIT License - see LICENSE file for details

โœจ Credits

Built with:

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Connects AI assistants to a self-hosted workflow layer so they can create jobs, browse available work, claim tasks, update status, retrieve job details, share structured context, and record review or approval events through exposed tools and prompts.
      9
      6
      Apache 2.0
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to file review jobs that real human reviewers open, return pinned comments and verdicts on, and approve, so agents can iterate on built sites, videos, and other artifacts based on genuine human feedback.
      38 npm
      MIT