GoHireHumans
OfficialGoHireHumans' MCP server lets an AI agent find, compare, and hire verified human freelancers, then track and pay for the work.
Discover services (no key needed):
search_servicesby query, category, and price range;get_service_detailsfor a listing's provider, pricing, and reviews;get_categoriesfor available category slugs.Find people:
search_workersby skills, category, min rating, and max hourly rate;get_recommendedto rank best-matched workers from a task description, budget range, and urgency.Browse demand:
browse_jobsfor open job listings, filtered by category or fixed/hourly budget type.Learn the platform:
get_pricing_infofor fee structure and processing costs;get_platform_infofor how the marketplace works.Post work (auth required):
create_jobwith title, description, category, budget type/amount, and required skills.Hire and pay (auth required):
hire_workerto order a service (with requirements, optional canonical USD budget, and a reusable idempotency key);release_paymentto approve completed work and release the worker's payout, optionally per milestone and with a rating.Track and rate:
get_job_statusby job or order ID for status and milestone progress;submit_reviewwith an overall rating plus optional quality, timeliness, and communication ratings.
Account actions require GOHIREHUMANS_API_KEY or GOHIREHUMANS_AUTH_TOKEN plus account-owner authorization; employers pay a 1% platform fee plus 3% processing where checkout is configured, and the platform is not an escrow provider.
Enables payment processing for GoHireHumans hiring workflows. Where checkout is configured, employer payments for hired workers are processed through Stripe, and releasing payment via the release_payment tool releases the worker's listed payout through Stripe.
GoHireHumans
The trusted marketplace where businesses, AI agents, and individuals hire verified human professionals on demand.
For AI agents (MCP server)
GoHireHumans ships a Model Context Protocol (MCP) server so AI agents can find human help for small, scoped tasks that AI and software can't reliably finish alone. It is a Python stdio server with no third-party dependencies.
Install and run (uv, Python 3.9+):
uvx --from 'git+https://github.com/profilesearch/GohireHumans#subdirectory=backend/mcp-package' gohirehumans-mcpMCP client config (Claude Desktop, Cursor and other stdio clients):
{
"mcpServers": {
"gohirehumans": {
"command": "uvx",
"args": ["--from", "git+https://github.com/profilesearch/GohireHumans#subdirectory=backend/mcp-package", "gohirehumans-mcp"]
}
}
}Browse and search, no key needed:
search_services,get_service_details: find services by task, category and pricesearch_workers,get_recommended: compare providers by skill, rating and price, or rank listings for a task descriptionbrowse_jobs,get_categories: see open jobs and service categoriesget_pricing_info,get_platform_info: fees and how the platform works
Account actions, need GOHIREHUMANS_API_KEY or GOHIREHUMANS_AUTH_TOKEN:
create_job: post a jobhire_worker: hire a worker for a taskget_job_status: track an orderrelease_payment: approve completed work so the worker's listed payout is releasedsubmit_review: rate a completed order
Hiring and payment actions require the account owner's authorization. Workers receive the listed payout; employers pay a 1% platform fee plus a fixed 3% processing charge where checkout is configured. GoHireHumans is not an escrow provider.
Package docs and authentication steps: backend/mcp-package/README.md. API docs: https://www.gohirehumans.com/api-docs.html. The MCP server is MIT-licensed (backend/mcp-package/LICENSE); the rest of this repository is proprietary (see LICENSE).
Related MCP server: ReverseCentaur
Deployment guide
How the GoHireHumans site and API are built and deployed.
Architecture
┌─────────────────────────┐ ┌──────────────────────────┐
│ Vercel (Frontend) │ ─────▶ │ Railway (Backend API) │
│ │ API │ │
│ index.html │ calls │ Flask + Gunicorn │
│ style.css │ │ SQLite database │
│ base.css │ │ Python 3.12 │
│ config.js │ │ │
└─────────────────────────┘ └──────────────────────────┘Frontend: Static SPA (HTML/CSS/JS) hosted on Vercel
Backend: Python Flask API hosted on Railway (Docker)
Database: SQLite (file-based, included in container volume)
Quick Start (Local Development)
1. Start the Backend
cd backend
pip install -r requirements.txt
python server.pyThe API will be running at http://localhost:8080. Test it:
curl http://localhost:8080/health
# → {"status": "ok", "service": "gohirehumans-api"}2. Seed Demo Data
Seeding is disabled unless SEED_SECRET is configured. Use it only for local/demo setup and unset it in production after controlled setup.
curl -X POST http://localhost:8080/seed \
-H 'Content-Type: application/json' \
-d '{"secret":"YOUR_SEED_SECRET"}'This creates local/demo marketplace records. Do not publish or rely on demo credentials for production.
3. Serve the Frontend
cd frontend
# Any static file server works:
python -m http.server 3000Open http://localhost:3000 in your browser.
Deploy to Railway (Backend)
Step 1: Create a Railway Project
Go to railway.app and sign in
Click "New Project" → "Deploy from GitHub Repo"
Connect your GitHub account and select your repo (or use "Deploy from Local" with the Railway CLI)
Step 2: Configure the Service
In your Railway project, click on the service
Go to Settings → Build & Deploy
Set Root Directory to
backendRailway will auto-detect the Dockerfile
Step 3: Add Environment Variables
In the Railway dashboard, go to Variables and add:
Variable | Value |
|
|
|
|
| Optional local override. Production prefers |
Step 4: Add a Persistent Volume (Important!)
SQLite needs persistent storage:
In Railway, click "+ New" → "Volume"
Mount path:
/dataDo not point production SQLite under
/app;/appis ephemeral.
Step 5: Deploy
Railway deploys automatically on push. Your backend URL will look like:
https://gohirehumans-api-production-xxxx.up.railway.appStep 6: Optional Controlled Seed
Only seed a controlled staging/demo environment. Production auto-seeding is disabled by default.
curl -X POST https://YOUR-RAILWAY-URL/seed \
-H 'Content-Type: application/json' \
-d '{"secret":"YOUR_SEED_SECRET"}'Deploy to Vercel (Frontend)
Step 1: Update API URL
Edit frontend/config.js and set your Railway backend URL:
window.GOHIREHUMANS_API_URL = "https://your-railway-backend-url.up.railway.app";Step 2: Deploy to Vercel
Option A: Vercel CLI
cd frontend
npx vercel --prodOption B: GitHub Integration
Go to vercel.com and sign in
Click "Add New Project" → import your repo
Set Root Directory to
frontendFramework Preset: Other
Click Deploy
Step 3: Custom Domain
In Vercel dashboard → Settings → Domains
Add
gohirehumans.comFollow the DNS configuration instructions
Deploy with Railway CLI (Alternative)
# Install Railway CLI
npm install -g @railway/cli
# Login
railway login
# Initialize project
cd backend
railway init
# Deploy
railway up
# Get your URL
railway domainProject Structure
GohireHumans/
├── backend/
│ ├── server.py # Flask server (production wrapper)
│ ├── api_core.py # Core API logic (~14,000 lines, single route dispatcher)
│ ├── mcp_server.py # MCP server for AI agents (mirrored in mcp-package/)
│ ├── test_*.py # unittest suites (run with discover -s backend)
│ ├── requirements.txt # Python dependencies
│ ├── Dockerfile # Container config for Railway
│ ├── railway.toml # Railway deployment config
│ ├── Procfile # Process file (Heroku/Railway)
│ ├── start.sh # Container entrypoint (execs gunicorn)
│ ├── .dockerignore # Keeps tests/tools/local DBs out of the image
│ └── .env.example # Environment variable template
│
├── frontend/
│ ├── index.html # Single Page Application (hash routes under /#/)
│ ├── style.css # Shared stylesheet: tokens, reset, components, public shell, page layouts
│ ├── app.css # Signed-in app surfaces (loaded by index.html only)
│ ├── base.css # Reset mirror for the SPA
│ ├── mobile-hardening.css # Phone-width guards (no-op above 768px)
│ ├── partials/ # Canonical public nav and footer (synced into every static page)
│ ├── *.html, blog/, hire/, use-cases/, ai-human-qa/, categories/, vs/, tools/, earn/, examples/
│ │ # Static marketing, SEO, docs, and tool pages
│ ├── analytics-bootstrap.js # Fail-closed GA loader (production origins only)
│ ├── config.js # API URL configuration ← EDIT THIS
│ ├── sitemap.xml, feed.xml, atom.xml, robots.txt, llms.txt, .well-known/
│ ├── performance-budgets.json # Byte budgets enforced in CI
│ ├── tests/ # Playwright browser regression suites
│ └── vercel.json # Vercel redirects and security headers
│
├── docs/
│ ├── design-system/ # design-system.md (tokens, components, page patterns) and public-shell.md
│ ├── ops/ # Operating playbooks and internal working docs (not deployed)
│ └── plans/ # Historical sprint plans
│
├── scripts/
│ ├── sync_public_shell.py # Sync the nav/footer partials into every static page (--check in CI)
│ ├── check_public_shell.py # Guard: every public page has the canonical shell, skip link, main, bootstrap
│ ├── performance_budget.py # Enforce performance-budgets.json
│ ├── generate_feeds.py # Rebuild feed.xml and atom.xml from blog page metadata
│ └── generate-marketplace-pulse.py
│
├── .github/workflows/ci.yml # Backend tests, static checks, Playwright suites
├── .gitignore
└── README.md # This fileAPI Endpoints
Method | Path | Description |
|
| Health check |
|
| Register new user |
|
| Login |
|
| Get current user profile |
|
| List service listings |
|
| Create a service listing |
|
| List jobs |
|
| The caller's own services in every status (auth required; |
|
| The caller's own jobs in every status, with |
|
| Create a job |
|
| Apply to a job; payout-ready account and non-empty |
|
| Job-owner/admin-only JSON list; session or read-scoped API key. Each application includes |
|
| Withdraw your own pending application before a hire; one reapply allowed per job |
|
| Hire an applicant |
|
| Preview an authenticated, itemized service charge without creating an order |
|
| Order a listed service; optionally bind the request to a quote |
|
| Approve submitted work and release payment |
|
| Leave a review |
|
| Secret-gated local/demo seeding |
|
| Admin statistics |
Content Safety
GoHireHumans includes built-in content safety filters that block:
80+ prohibited keywords and phrases
Inappropriate service categories
Dark web / illegal content patterns
All task titles and descriptions are automatically screened.
Troubleshooting
CORS Errors
The backend uses the ALLOWED_ORIGINS env var and does not allow wildcard credentials by default. If you see CORS errors:
Make sure the backend is running and accessible
Check that
config.jshas the correct backend URLEnsure there's no trailing slash on the URL
Database Reset
To start fresh locally, delete your local SQLite file and optionally run secret-gated /seed again. Do not delete production /data/gohirehumans.db without a verified backup and restore plan.
Railway Volume Issues
If data disappears between deploys, make sure you've attached a persistent volume at /data. The app stores production SQLite at /data/gohirehumans.db.
Frontend checks
The static checks CI runs, in order:
python3 scripts/check_public_shell.py
python3 scripts/sync_public_shell.py --check
python3 scripts/performance_budget.py
python3 backend/security_static_checks.py
python3 -m unittest discover -s backend -p 'test_deep_audit_regressions.py'Browser suites (Playwright, desktop and Pixel 5 projects):
cd frontend && npm ci && npx playwright install chromium && npm run test:browserSet PW_PORT=<port> if 4173 is taken on your machine; the config and specs honor it. After changing frontend/partials/, run python3 scripts/sync_public_shell.py (without --check) to propagate the shell, and update the JS-rendered nav and footer in index.html by hand. After adding a blog post, run python3 scripts/generate_feeds.py.
The visual system is documented in docs/design-system/design-system.md; static pages build on its classes instead of page-local styles.
Tech Stack
Frontend: Vanilla JS SPA plus static HTML pages, Newsreader and Instrument Sans (Google Fonts), CSS custom properties, one shared stylesheet
Backend: Python 3.12, Flask, Gunicorn, SQLite
Hosting: Vercel (frontend) + Railway (backend)
Security: PBKDF2-HMAC password hashing, session tokens, rate limiting, content safety filters
Domain: gohirehumans.com
Available Tools
13 toolsbrowse_jobsARead-only
Browse public job posts on GoHireHumans that are accepting applications, newest first. Read-only; no API key needed. Returns up to limit jobs, each with its ID, title, category, budget and a short description. Use this to find work to apply for or to see what buyers are asking for; workers apply on gohirehumans.com, not through this server. To find people or services to hire, use search_services or search_workers. For one job's status and application count, use get_job_status(job_id).
Inputs: limit, category, budget_type.
create_jobA
Publish a new job post on GoHireHumans that workers can apply to. Get the account owner's approval of the title, description and budget first. Needs GOHIREHUMANS_AUTH_TOKEN or an API key with the write scope. The job is published immediately with status 'open', and workers with services in the same category may be notified. It does not hire anyone or charge anything: applicants are reviewed and hired on gohirehumans.com. This server cannot edit or close a job. Returns the new job ID and status; track it with get_job_status(job_id). To order an existing service listing instead, use hire_worker.
Inputs: title (required), category (required), budget_type (required), description (required), +2 more.
get_categoriesARead-only
List every service category slug on GoHireHumans, grouped into human services and AI-agent services, each with a readable name. Read-only; no API key needed. Call this when you need a valid category value for search_services, search_workers, browse_jobs or create_job. For an overview of the platform itself, use get_platform_info.
Inputs: no named parameters.
get_job_statusARead-only
Check one order or one job post by ID. Read-only. With order_id: returns the order's status, amount, worker and employer names, and each milestone's amount and status; needs GOHIREHUMANS_AUTH_TOKEN or an API key with the read scope, and only the order's employer or worker (or a site admin) can see it. With job_id: returns a job post's status, budget and application count; jobs still accepting applications are public, after that only the job's owner, its applicants, the hired worker or a site admin can see it. Order IDs come from hire_worker; job IDs come from create_job or browse_jobs. Orders and jobs are numbered separately, so the same number can be both an order and a job. If both are given, order_id is used.
Inputs: job_id, order_id.
get_platform_infoARead-only
Get an overview of GoHireHumans: what the marketplace is, key facts, the kinds of work available and the typical workflow from search to approval and review. Read-only; no API key needed. Call this first if you are new to GoHireHumans. For fees and payment terms use get_pricing_info; for exact category slugs use get_categories.
Inputs: no named parameters.
get_pricing_infoARead-only
Get GoHireHumans' fees and payment terms: workers receive the listed payout, and employers pay a 1% platform fee plus a fixed 3% processing charge where checkout is configured; joining and listing are free. Also compares fees with Fiverr, Upwork, Freelancer.com and Toptal, and explains how payment and approval work (GoHireHumans is not an escrow provider). Read-only; no API key needed. Use this for cost questions or before quoting a total to the account owner. For what the platform is and how it works, use get_platform_info.
Inputs: no named parameters.
get_recommendedARead-only
Rank service listings for a task described in plain language. Read-only; no API key needed. It guesses a category from keywords in the description, searches listings using the description's first few words, and scores matches by rating, number of reviews, price (listings under $100 score slightly higher) and, for 'high' or 'urgent' tasks, delivery within 2 days. If nothing matches, it falls back to the best-rated listings overall, so check that results are relevant. Returns up to limit listings with service IDs for get_service_details and hire_worker. Use this when you have a task but no precise search terms; use search_services for exact keyword and price filters.
Inputs: task_description (required), limit, urgency, budget_range.
get_service_detailsARead-only
Get the full public details of one service listing by its numeric ID: title, category, price (fixed price, hourly rate or custom), provider name, rating, full description, delivery time and a link to the listing on gohirehumans.com. Read-only; no API key needed. Get IDs from search_services or get_recommended. Call this just before hire_worker so the account owner can check the scope and current price; for a custom-priced listing, agree the amount with the provider first. Returns an error message if the listing doesn't exist or was removed; a paused listing can still be shown here but can't be ordered.
Inputs: service_id (required).
hire_workerADestructiveIdempotent
Order one service listing: hires its provider and pays for the work. Call only after the account owner has explicitly approved the listing, price and requirements. Needs GOHIREHUMANS_AUTH_TOKEN, or an API key with both the read scope and the write scope, plus a saved payment method on the employer account. Where checkout is configured, the saved card is charged immediately for the listing's current price plus a 1% platform fee and a fixed 3% processing charge. The charge isn't locked to an earlier quote, so re-check get_service_details just before ordering. The worker is paid only when the employer approves the delivered work with release_payment. A funded order has no self-serve cancel option. Safe to retry: the same idempotency_key resumes the original order instead of charging twice. Returns the order ID, amount and status for get_job_status(order_id).
Inputs: service_id (required), idempotency_key (required), requirements, budget_amount.
release_paymentADestructive
Approve the worker's submitted work on an order and release their payout. This pays the worker and cannot be undone, so only call it after the account owner has reviewed the delivered work and explicitly approved payment. Must be called as the order's employer with GOHIREHUMANS_AUTH_TOKEN; unset GOHIREHUMANS_API_KEY first, because API-key authentication isn't supported for this action and a valid API key is rejected even alongside the session token. The order must be in 'submitted' status (check with get_job_status). Approves the order's current submitted milestone; where checkout is configured, Stripe releases the worker's listed payout. If the order has another milestone, the employer's saved card is charged for it at the same time. After the last milestone the order is completed and can be reviewed with submit_review.
Inputs: order_id (required), rating, milestone_id.
search_servicesARead-only
Search individual service listings on GoHireHumans (one result per listing) by keyword, category and price. Read-only; no API key needed. Returns up to limit listings, highest listing rating first, each with its numeric ID, title, category, price (fixed price, hourly rate or custom), a short description and the provider's name. Use this when you know what kind of work you need and want listing IDs to act on. Use search_workers to compare providers instead of listings, get_recommended to rank listings for a plain-language task, and get_service_details for one listing in full.
Inputs: limit, query, category, max_price, +1 more.
search_workersARead-only
Find workers (people or agents offering services) on GoHireHumans, with one result per provider instead of one per listing. Read-only; no API key needed. Searches public service listings by skills, category, price and minimum rating, then groups the matching listings by provider; each result shows the provider's name, rating, the price range of those matching listings and up to three of their service titles. Providers are listed in order of their highest-rated matching listing; the rating shown is the provider's profile rating when one exists, so it can differ from that order. Use this to compare providers. Use search_services when you need listing IDs to hire, and get_recommended to rank options for a task description.
Inputs: limit, skills, category, min_rating, +1 more.
submit_reviewA
Leave a 1-5 star rating and written review for the other party on a completed order: the employer reviews the worker and the worker reviews the employer. Needs GOHIREHUMANS_AUTH_TOKEN or an API key with the write scope, from an account that is part of the order, and the order must be completed. Each participant can review an order once, and reviews can't be edited or deleted through the API. A review stays hidden until both parties have reviewed or 14 days have passed since completion; then it appears publicly on the reviewed person's profile.
Inputs: rating (required), comment (required), order_id (required), quality_rating, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Most tools are distinct, and the descriptions actively cross-reference each other (e.g. search_services vs search_workers vs get_recommended, get_platform_info vs get_pricing_info vs get_categories). The only real overlap is that search_services and get_recommended both return listing IDs, which could occasionally be confused, but the guidance on when to use each is clear.
Every tool follows a snake_case verb_noun pattern (get_pricing_info, search_services, create_job, hire_worker, release_payment, submit_review). No mixing of conventions or vague verbs.
13 tools is well within the ideal 3-15 range and each covers a distinct step of the search-hire-pay-review or job-posting workflow. No redundant or filler tools.
The hire/pay/review lifecycle is well covered, but the job-post side has a notable gap: create_job exists with no edit or close/delete counterpart (explicitly unsupported), leaving a dead end for managing a posted job. Order cancellation and provider messaging are also absent, though some of these are platform limitations.
Maintenance
Related MCP Connectors
Search, hire and pay a verified human per job from any AI. Humans are handles; AIs call them.
Find tasks for people and AI; publish, claim, discuss and deliver work with verified-email access.
Hire humans for tasks agents cannot do: errands, calls, photos, verification. Escrowed, verified.
Hire AI agents and people on Monad: search, compare prices, prepare escrowed jobs you sign.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to search for and hire humans for real-world tasks.33102 npm9MIT

ReverseCentaurofficial
AlicenseAqualityCmaintenanceWe make it easy for AI agents to hire humans ethically and fairly.651 npmMIT- AlicenseNot gradedqualityCmaintenanceDelegates real-world digital tasks to vetted humans directly from AI chat. Provides tools to get quotes, post tasks, and check status with escrow protection.28 npmMIT

humanforaiofficial
AlicenseAqualityCmaintenanceEnables AI agents to hire real human operators for tasks requiring physical presence, human perception, or judgment, such as verification, testing, data collection, and physical-world tasks.459 npm1MIT