HITL.sh MCP Server
Officialby hitl-sh
README.md
# 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](USER_GUIDE.md)
### 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](OPENAI_AGENT_BUILDER_GUIDE.md)
---
## ๐ ๏ธ 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`](https://www.npmjs.com/package/@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](https://nodejs.org/))
- HITL.sh API key ([get one here](https://hitl.sh))
- Auth0 account ([sign up](https://auth0.com))
- Vercel account for deployment ([sign up](https://vercel.com))
## ๐ง Environment Variables
### Required for Production
```bash
# 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
```bash
# 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
```bash
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](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`:
```bash
cp .env.example .env.local
# Edit .env.local with your credentials
```
### 4. Run Locally
```bash
npm run dev
```
Server runs on `http://localhost:3000`
### 5. Test OAuth Flow
```bash
node scripts/test-oauth.mjs http://localhost:3000/mcp
```
## ๐ Deploy to Vercel
### 1. Push to GitHub
```bash
git add .
git commit -m "Initial commit"
git push origin main
```
### 2. Deploy to Vercel
1. Go to [vercel.com/new](https://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`:
```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](CLAUDE_DESKTOP_SETUP.md) for detailed instructions.
## ๐งช Testing
### Test OAuth Flow
```bash
node scripts/test-oauth.mjs http://localhost:3000/mcp
```
### Test All Tools
```bash
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](CLAUDE.md) - For future Claude Code sessions
- [PER_USER_API_KEY_SETUP.md](PER_USER_API_KEY_SETUP.md) - Complete Auth0 setup guide
- [CLAUDE_DESKTOP_SETUP.md](CLAUDE_DESKTOP_SETUP.md) - Local Claude Desktop integration
## ๐ 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
## ๐ Links
- [HITL.sh](https://hitl.sh) - Human-in-the-Loop platform
- [MCP Specification](https://modelcontextprotocol.io/) - Model Context Protocol
- [Auth0 Documentation](https://auth0.com/docs) - OAuth provider
- [Vercel Documentation](https://vercel.com/docs) - Deployment platform
## โจ Credits
Built with:
- [Next.js 15](https://nextjs.org/)
- [mcp-handler](https://www.npmjs.com/package/mcp-handler)
- [Auth0](https://auth0.com/)
- [HITL.sh](https://hitl.sh/)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues