HITL.sh MCP Server
OfficialIntegrates Auth0 for OAuth 2.1 authentication, JWT verification, and per-user API key storage and management, enabling secure user authentication for the MCP server.
This server has a remotely hosted endpoint. Open its connector listing for connection details, authentication requirements, and setup instructions:
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
Add MCP Connector in ChatGPT with URL above
Sign up through the OAuth flow
(Optional) Add your personal HITL API key at:
https://mcp.hitl.sh/setup-api-keyStart using HITL tools!
๐ Full ChatGPT Guide
For OpenAI Agent Builder / Zapier / Make.com (Direct API Key):
URL: https://mcp.hitl.sh/mcp-simple
Add MCP Server with URL above
Authentication: Bearer Token
Token: Your HITL API key (e.g.,
hitl_live_abc123...)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 your workflows, newest first |
| Get a workflow: steps, connections, input fields |
| List the input fields a workflow reads, with an example body |
| Start a run of an active workflow with its input |
| Get one run; with |
| List a workflow's runs |
| Get a live-updates URL and token for a run |
| Run a failed run again with the same input |
| Build and change workflows |
| Make a workflow runnable, stop it, or test-run it |
| Published versions |
| Who reviews a workflow; invite people by email |
| A workflow's join code |
| See where a join code leads; join with it |
| 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
Node.js 18+ (download)
HITL.sh API key (get one here)
Auth0 account (sign up)
Vercel account for deployment (sign up)
๐ง 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_secretOptional
# 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 install2. Set Up Auth0
Follow the setup guide in PER_USER_API_KEY_SETUP.md to:
Create an Auth0 account and tenant
Create an API with audience
https://mcp.hitl.shCreate M2M applications for testing and management
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 credentials4. Run Locally
npm run devServer 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 main2. Deploy to Vercel
Go to vercel.com/new
Import your GitHub repository
Add all environment variables from
.env.localClick 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_redirectAllowed Web Origins:
https://chatgpt.com, https://chat.openai.comAllowed Logout URLs:
https://chatgpt.com, https://chat.openai.com
๐ค Using with ChatGPT
1. Create Auth0 SPA Client
Auth0 Dashboard โ Applications โ Create Application
Name:
ChatGPT MCP ConnectorType: Single Page Application
Configure callback URLs (see above)
Enable Connections โ Username-Password-Authentication
2. Connect in ChatGPT
ChatGPT โ Settings โ MCP Connectors
Add connector with your Vercel URL:
https://your-app.vercel.app(Note: Use base URL, not
/mcpendpoint)Authentication: OAuth
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/mcpTest 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
CLAUDE.md - For future Claude Code sessions
PER_USER_API_KEY_SETUP.md - Complete Auth0 setup guide
CLAUDE_DESKTOP_SETUP.md - Local Claude Desktop integration
๐ Troubleshooting
"Invalid token" errors
Check that
AUTH0_ISSUER_URLmatches your Auth0 tenantVerify token hasn't expired
Ensure
AUTH0_AUDIENCEishttps://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_keyin user_metadataUser must log out/in to get new token with API key
๐ค Contributing
Contributions welcome! Please:
Fork the repository
Create a feature branch
Make your changes
Submit a pull request
๐ License
MIT License - see LICENSE file for details
๐ Links
HITL.sh - Human-in-the-Loop platform
MCP Specification - Model Context Protocol
Auth0 Documentation - OAuth provider
Vercel Documentation - Deployment platform
โจ Credits
Built with:
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
This server cannot be deployed
Maintenance
Related MCP Connectors
Human-in-the-loop control panel for AI agents: start runs, review them, answer their requests.
Build, test and publish agentic workflows from your AI client: approve steps, read tables, see runs.
Build and run AI agent workflows: start runs, answer what they ask, search knowledge, edit agents.
Design, build and run teams of AI agents with checked handoffs between them.
Related MCP Servers
- AlicenseAqualityCmaintenanceConnects 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.96Apache 2.0
- AlicenseNot gradedqualityAmaintenanceEnables 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 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to submit work to real human reviewers, receive pinned feedback and verdicts, and iterate until approved.38 npmMIT
- AlicenseNot gradedqualityAmaintenanceLets AI agents submit work to real human reviewers, receive pinned feedback and a verdict, and iterate until the result is approved.38 npmMIT