Skip to main content
Glama

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-mcp

MCP 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 price

  • search_workers, get_recommended: compare providers by skill, rating and price, or rank listings for a task description

  • browse_jobs, get_categories: see open jobs and service categories

  • get_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 job

  • hire_worker: hire a worker for a task

  • get_job_status: track an order

  • release_payment: approve completed work so the worker's listed payout is released

  • submit_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.py

The 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 3000

Open http://localhost:3000 in your browser.


Deploy to Railway (Backend)

Step 1: Create a Railway Project

  1. Go to railway.app and sign in

  2. Click "New Project" → "Deploy from GitHub Repo"

  3. Connect your GitHub account and select your repo (or use "Deploy from Local" with the Railway CLI)

Step 2: Configure the Service

  1. In your Railway project, click on the service

  2. Go to Settings → Build & Deploy

  3. Set Root Directory to backend

  4. Railway will auto-detect the Dockerfile

Step 3: Add Environment Variables

In the Railway dashboard, go to Variables and add:

Variable

Value

PORT

8080 (Railway usually sets this automatically)

FLASK_DEBUG

false

DATABASE_PATH

Optional local override. Production prefers /data/gohirehumans.db.

Step 4: Add a Persistent Volume (Important!)

SQLite needs persistent storage:

  1. In Railway, click "+ New" → "Volume"

  2. Mount path: /data

  3. Do not point production SQLite under /app; /app is ephemeral.

Step 5: Deploy

Railway deploys automatically on push. Your backend URL will look like:

https://gohirehumans-api-production-xxxx.up.railway.app

Step 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 --prod

Option B: GitHub Integration

  1. Go to vercel.com and sign in

  2. Click "Add New Project" → import your repo

  3. Set Root Directory to frontend

  4. Framework Preset: Other

  5. Click Deploy

Step 3: Custom Domain

  1. In Vercel dashboard → Settings → Domains

  2. Add gohirehumans.com

  3. Follow 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 domain

Project 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 file

API Endpoints

Method

Path

Description

GET

/health

Health check

POST

/auth/register

Register new user

POST

/auth/login

Login

GET

/profile

Get current user profile

GET

/services

List service listings

POST

/services

Create a service listing

GET

/jobs

List jobs

GET

/me/services

The caller's own services in every status (auth required; page, per_page, status, include_removed)

GET

/me/jobs

The caller's own jobs in every status, with application_count (auth required)

POST

/jobs

Create a job

POST

/jobs/{id}/apply

Apply to a job; payout-ready account and non-empty cover_message required, optional http(s) portfolio_url; incomplete payout setup returns 403 payout_setup_required

GET

/jobs/{id}/applications

Job-owner/admin-only JSON list; session or read-scoped API key. Each application includes worker_payout_ready (boolean synced hint), suggested_rank (1–3 or null), and suggestion_reasons (up to three fixed-copy strings, empty when not suggested). Only eligible, payout-ready pending/shortlisted applicants on open/reviewing fixed-price jobs with hiring enabled are suggested; no padding, no numeric score. Hiring still re-checks Stripe live; the buyer chooses.

DELETE

/jobs/{id}/apply

Withdraw your own pending application before a hire; one reapply allowed per job

POST

/jobs/{id}/hire

Hire an applicant

GET

/services/{id}/quote

Preview an authenticated, itemized service charge without creating an order

POST

/services/{id}/order

Order a listed service; optionally bind the request to a quote

POST

/orders/{id}/approve

Approve submitted work and release payment

POST

/orders/{id}/review

Leave a review

POST

/seed

Secret-gated local/demo seeding

GET

/admin/dashboard

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:

  1. Make sure the backend is running and accessible

  2. Check that config.js has the correct backend URL

  3. Ensure 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:browser

Set 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 tools
browse_jobsA
Read-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_categoriesA
Read-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_statusA
Read-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_infoA
Read-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_infoA
Read-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_service_detailsA
Read-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_workerA
DestructiveIdempotent

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_paymentA
Destructive

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_servicesA
Read-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_workersA
Read-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

    A4.4/5.0

    Scored across 13 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers