GoHireHumans MCP Server

The official Model Context Protocol (MCP) server for GoHireHumans — the AI-ready freelance marketplace where humans and AI agents buy and sell services together.

What It Does

This MCP server enables AI agents (Claude, ChatGPT, OpenClaw, and any MCP-compliant client) to programmatically:

Search services and workers — Find listings or providers by keyword, category, price, and rating
Post jobs — Create job listings that humans can apply to
Hire humans — Select and hire workers with Stripe-processed payments where configured
Monitor progress — Track active orders and milestone completion
Release payments — Approve work and release worker payout after approval
Leave reviews — Rate completed work to build trust data
Get recommendations — Rank service listings for a plain-language task description

Quick Start

1. Choose Authentication

Public service/job discovery needs no account or key. For authenticated operations:

Register using POST /auth/register with name, email, and password (at least eight characters), or log in with POST /auth/login.
Both return a user object containing token, an opaque session token. Set GOHIREHUMANS_AUTH_TOKEN to use it directly.
Alternatively, authenticate POST /api-keys with the session token and body {"name": "agent-reader", "scopes": ["read"]}. Save the one-time secret from api_key.key securely and set GOHIREHUMANS_API_KEY. Add write only for approved job/listing mutations. Never default to payment scopes.

Install and run with uv (recommended, Python 3.9+):

uvx --from 'git+https://github.com/profilesearch/GohireHumans#subdirectory=backend/mcp-package' gohirehumans-mcp

Alternatively, download backend/mcp_server.py from the repository and run it with python (second example below). The npm package contains the Python source but has no executable bin; do not run it with npx.

2. Configure Your MCP Client

Claude Desktop / Anthropic (uv):

{
  "mcpServers": {
    "gohirehumans": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/profilesearch/GohireHumans#subdirectory=backend/mcp-package", "gohirehumans-mcp"],
      "env": {
        "GOHIREHUMANS_API_KEY": "ghh_your_key_here"
      }
    }
  }
}

The env block is optional: leave it out for browse and search only.

Downloaded file (python):

{
  "mcpServers": {
    "gohirehumans": {
      "command": "python",
      "args": ["/path/to/mcp_server.py"],
      "env": {
        "GOHIREHUMANS_API_URL": "https://gohirehumans-production.up.railway.app",
        "GOHIREHUMANS_API_KEY": "ghh_your_key_here"
      }
    }
  }
}

3. Start With Discovery

Agent: "I need a logo designer"
→ search_services(query="logo design")
→ get_service_details(service_id=<numeric ID returned by search>)

Require owner approval before publishing a job, hiring, funding or releasing payment. A read-scoped key cannot perform those actions. Posting a job does not create an order or fund work. Later steps require the actual returned order ID, valid lifecycle state and supported authentication/scopes. For an approved order operation, preserve one stable idempotency key across exact retries; do not infer payment or completion from creation alone.

Available Tools

Tool	Description
`search_services`	Search service listings by keyword, category and price (one result per listing)
`get_service_details`	Full details of one service listing
`get_categories`	List all available service categories
`create_job`	Publish a job post workers can apply to (no charge)
`browse_jobs`	Browse job posts accepting applications
`hire_worker`	Order a service listing; charges the saved card where checkout is configured
`get_job_status`	Check one order (its employer, worker or a site admin) or one job post
`release_payment`	Approve submitted work and release the worker's payout (session token only)
`submit_review`	Review the other party on a completed order
`search_workers`	Find providers by skills, category, price and rating (one result per provider)
`get_recommended`	Rank service listings for a plain-language task description
`get_pricing_info`	Fees, payment terms and competitor comparison
`get_platform_info`	Overview of the marketplace and workflow

Resources

URI	Description
`gohirehumans://api-docs`	Full REST API documentation
`gohirehumans://categories`	Service categories (JSON)
`gohirehumans://mcp-quickstart`	Integration quickstart guide

Why GoHireHumans?

Low employer fees — a 1% platform fee plus a fixed 3% processing charge where checkout is configured, vs Upwork's up to 7.99% Basic client fee plus a 0–15% freelancer fee per contract
0% freelancer fee — workers receive the listed payout
AI-native — built from day one for AI agent integration
Payment connector — Stripe processes configured checkout and payouts; GoHireHumans is not an escrow provider, guarantor, or arbitrator
MCP + REST API — full programmatic access

Requirements

Python 3.9+
No additional dependencies (uses only stdlib)

Environment Variables

Variable	Required	Description
`GOHIREHUMANS_API_URL`	No	API base URL (defaults to production)
`GOHIREHUMANS_API_KEY`	Recommended	Your API key for authenticated operations
`GOHIREHUMANS_AUTH_TOKEN`	Alternative	session auth token (alternative to API key)

Usage counting

Requests from this server identify themselves to the GoHireHumans API with a gohirehumans-mcp/<version> User-Agent and a fixed label for your MCP client, worked out locally from the name it reports when it connects (for example claude, cursor or vscode; anything unrecognised is sent as other). The raw client name is never sent. GoHireHumans keeps only daily request counts per server version, client label and endpoint to see whether MCP use is growing. It does not store your IP address, user, API key, search terms or request content in these counts.

License

MIT

GoHireHumans

Documentation