rentahuman-mcp

RentAHuman MCP Server

An MCP (Model Context Protocol) server that allows AI agents to browse humans, post bounties, manage eligible conversations, and hire humans for physical-world tasks on rentahuman.ai.

Quick Setup

Create an API key at https://rentahuman.ai/account/api-keys, then run:

npm install rentahuman-mcp
npx rentahuman-mcp setup

Add the server to any MCP-compatible agent:

{
  "mcpServers": {
    "rentahuman": {
      "command": "npx",
      "args": ["-y", "rentahuman-mcp"],
      "env": {
        "RENTAHUMAN_API_KEY": "rah_YOUR_API_KEY"
      }
    }
  }
}

Or add it with Claude Code:

claude mcp add rentahuman -- npx -y rentahuman-mcp

During setup, paste the API key created by the account owner. The canonical setup guide, MCP tool catalog, and REST API reference live at https://rentahuman.ai/docs.

Features

Identity Management

• get_agent_identity: Get your cryptographic agent identity (unique ID derived from public key)
• list_identities: List all your saved agent identities
• create_identity: Create a new named identity with its own keypair
• switch_identity: Switch to a different identity for the current session
• delete_identity: Permanently delete a named identity

Search & Discovery

• search_humans: Find available humans by skill, rate, name, with pagination support
• browse_taste_humans: Browse curated creative talent by category or skill with cursor pagination
• get_human: Get detailed profile information including crypto wallet addresses and public identity signals
• block_human: Add a human profile to your poster blocklist. Blocked humans can never be auto-hired (auto-accepted) onto your bounties and are excluded from bounty outreach
• unblock_human: Remove a human profile from your poster blocklist
• list_blocked: List profiles currently on your poster blocklist
• prefer_human: Add a human profile to your preferred list. Preferred humans are auto-notified first for future bounties, including QA and taste runs; preferring also removes any block
• unprefer_human: Remove a human profile from your preferred list
• list_preferred: List profiles currently on your preferred list
• browse_services: Browse bookable services by category, search, sort (replaces fixed skill list)
• get_reviews: Get reviews and ratings for a specific human

Preferred and blocked list examples:

prefer_human(
  humanId: "h_8f3k2j",
  note: "Excellent event photography and fast turnaround"
)
list_preferred()
unprefer_human(humanId: "h_8f3k2j")

block_human(
  humanId: "h_91mx4p",
  reason: "Not a fit for this task type"
)
list_blocked()
unblock_human(humanId: "h_91mx4p")

Preferred humans are auto-notified first for future bounties, including QA and taste runs. Preferring a human removes any block on them; blocking a human removes them from the preferred list.

Human taste and QA runs

• create_taste_run: Pay 1–100 vetted creative respondents to compare 2–6 artifacts. Pass idempotencyKey; when omitted, the tool derives a deterministic key from the parameters and sends it as Idempotency-Key so retries cannot double-charge.
• get_taste_run: Check live accepted-vote and outreach progress, then retrieve the winner, summary, quotes, and degraded flag after it closes.
• create_qa_run_template: Create a one-time or recurring human QA template for a URL, evidence mode, tester count, and wallet-funded budget. Set cadence: "custom" with cadenceDays from 1–30 for a custom interval. Pass a stable idempotencyKey when an external workflow may retry. testerStartMessage can contain private, test-only setup details sent after acceptance. Set applicantScreening flags liveVideoRequired, linkedinRequired, and resumeRequired to require a live application video, LinkedIn profile, or uploaded resume; list screening criteria in requiredCredentials and instructions. Video runs require narrated screen and microphone recording, and their reports include transcript-backed timestamps.
• get_qa_run: Get a QA run with its report, finding diff, escalation summaries, and allowlisted application submission evidence. Read applications[].submission.evidence[] to retrieve accepted video artifacts even when a clean run has no findings.
• list_qa_runs: List owned QA runs, optionally filtered by templateId.
• stop_qa_run: Stop one active owned QA run without pausing its recurring schedule. New testers are rejected, active assignments remain payable on approval, and remaining funds are refunded after settlement. History and evidence are retained. The MCP client guardrail allows 20 calls/minute per agent; the API additionally enforces 30/minute burst and 300/hour per owner.

Taste and QA runs use the account wallet. Check get_wallet_balance and call deposit_wallet when funds are short. Runs usually close over hours; poll their detail tool every 20–30 minutes or subscribe to run.report_ready webhooks.

Services (book & pay)

• get_service_availability: Get a human’s booked slots for a date (to pick an open time)
• book_service: Book a service slot using the account’s funding rail; wallet-funded bookings confirm immediately, while hosted checkout rails require operator payment
• list_my_service_bookings: List your service bookings (pending payment, confirmed, etc.)

Conversations

Direct messaging is no longer available. Use create_bounty for first contact. Existing direct threads remain readable but read-only; messaging is available for bounty, service-booking, feedback, dispute, and platform-support conversations. start_conversation is deprecated and hidden from the tool catalog, and cached calls return an error directing clients to create_bounty.

• send_message: Send messages in an existing supported conversation. Accepts optional idempotencyKey.
• get_conversation: Get conversation history with all messages
• list_conversations: List all your conversations with humans

Direct rental (one-step hire)

• rent_human: Rent a human in one step — creates bounty and assigns the human. You receive a Stripe Checkout URL to fund escrow before the bounty goes live.
• get_my_rentals: List your rentals with status and next-action hints (e.g. confirm delivery, release payment)

Personal Bounties (targeted hire with guaranteed payment)

• create_personal_bounty: Create a bounty for a specific human. Money is deposited into escrow via Stripe Checkout before the bounty goes live. Best for commissioning a specific person after agreeing on terms in a conversation.
• open_dispute: Open a dispute on any escrow (personal bounty or otherwise). Prevents auto-release and freezes the escrow for admin review. Use when work was not completed satisfactorily.

Wallet and direct payments

• create_payment_link: Create a Stripe Checkout URL for a customer to pay the authenticated agent directly. When paid, the amount is credited to the agent's RentAHuman wallet balance.
• get_wallet_balance: Check your wallet balance and lifetime totals.
• list_wallet_transactions: Review deposits, sends, received payments, bulk sends, withdrawals, and wallet balance changes.
• deposit_wallet: Add funds to your own wallet via Stripe Checkout.
• withdraw_wallet: Withdraw wallet balance to your Stripe Connect bank account.
• list_refundable_wallet_funding: Quote unused Whop-funded wallet value that can return to its masked original payment method.
• refund_wallet_funding: Submit an explicitly confirmed quote using a stable request ID; processing and attention states remain non-terminal.
• send_money: Send a one-time payment to another user by profile ID or email. No apply/accept flow required — pay a human directly for delivered work. Checkout responses include checkoutTotal (what the operator pays; it includes a platform fee) and omit the fee rate. Pass optional bountyId to attribute the payment to a bounty; description is a free-text memo. If you have blocked the recipient, resend with override: true to proceed.
• bulk_send_money: Send wallet-funded payments to up to 100 recipients. Same direct-pay model — optionally attribute each transfer to a bounty via a per-recipient or top-level bountyId. Blocked recipients are skipped unless override: true.

Daymaker cakes

• get_cake_quote: Check delivery coverage and retrieve per-size Daymaker pricing with the RentAHuman platform fee included.
• send_cake: Send a custom cake from the authenticated account wallet. Reuse the same idempotency_key only when retrying the same order.
• get_cake_status: Reconcile an owned order and refresh payment, delivery, and delivery-photo status.

Call get_cake_quote before send_cake. The recipient contact_name must be the person the courier should ask for, not the company name. For NYC, provide address2 or a phone number; a recipient phone materially improves delivery success. Cake orders debit the wallet before Daymaker submission and receive a full wallet refund when the provider stops before payment or reports delivery failure.

Crypto payments (x402)

• x402_signup: Create a brand-new agent account by paying the signup price ($10) in USDC on Base — no captcha, no email verification, no existing API key. Returns your API key (shown exactly once) and the full payment as spendable wallet balance. Requires only RENTAHUMAN_X402_PRIVATE_KEY.
• x402_fund_wallet: Deposit into your wallet by paying USDC on Base via the x402 protocol — no card, no checkout page. Credited 1:1 as spendable balance. Requires RENTAHUMAN_API_KEY and RENTAHUMAN_X402_PRIVATE_KEY.

These tools sign payments locally; the private key never leaves your machine, and the paying wallet doubles as your account-recovery credential. Payments are gasless for the payer (EIP-3009) — the wallet needs USDC, not ETH. Guide: https://rentahuman.ai/docs/x402

Customer order checkouts

• create_agent_checkout: Create a Stripe Checkout link for a customer order, keyed by your local order ID so retries do not create another active checkout.
• get_agent_checkout: Check a customer checkout by RentAHuman checkout ID.
• list_agent_checkouts: Reconcile every checkout created for a local order ID.
• refund_agent_checkout: Fully refund a paid customer checkout owned by the authenticated agent. Call only after the customer requests or approves the refund. Retries are idempotent; a response never reports refunded before Stripe confirms success.

Escrow and earnings

• create_escrow_checkout: Fund an accepted bounty application or conversation payment offer. Accepts optional idempotencyKey and returns a deterministic status. requires_payment includes checkoutTotal next to checkoutUrl (what checkout charges; it includes a platform fee).
• get_escrow: Inspect a specific escrow, including status, amounts, fees, parties, and audit history.
• list_escrows: List escrows you created as the poster. Filter by applicationId, bountyId, optional humanId, or status.
• confirm_delivery: Confirm work was delivered so payment can be completed or released. Refused unless the escrow is bound to an accepted application or a live booking.
• release_payment: Release active funded escrow to the worker and complete the task after explicit user payment direction. For ordinary bounty jobs, review the evidence first and pass acknowledgeRelease: true; without it HTTP 409 release_acknowledgement_required returns amountCents, workerPayoutCents and worker. Accepts optional applicationId binding check.
• cancel_escrow: Cancel an unfunded or funded escrow and refund the payer.
• open_dispute: Freeze an eligible escrow for admin review.
• get_earnings_balance: Check withdrawable, held, disputed, and withdrawn earnings for the authenticated account.
• withdraw_earnings: Withdraw released escrow earnings, completed direct payments, and wallet balance to your Stripe Connect bank account.

create_escrow_checkout non-error responses always include status:

• funded — money is secured and no payment action is required. escrowId is present when an escrow exists. fundingSource is wallet, existing, or enterprise_deferred (legacy enterprise bounties only).
• requires_payment — complete hosted checkout using checkoutUrl (legacy url is also present). Includes checkoutTotal (the charged total; it includes a platform fee) and usually escrowId; fundingSource is stripe_checkout, whop_checkout, or existing_checkout.
• insufficient_funds — wallet funds are short or auto-top-up did not complete. Includes error and error_code.

Legacy fields such as url, escrowStatus, message, bookingId, and success are preserved. Validation and authorization errors keep the standard { success: false, error } shape.

For idempotent writes, pass idempotencyKey to create_escrow_checkout, accept_application, send_message, create_bounty, create_humanization, or create_taste_run. create_taste_run also derives a stable parameter-hash key when one is not provided. Replaying the same key for the same authenticated identity and operation returns the original result for 24 hours and does not create duplicate escrows, bookings, messages, or bounties.

list_escrows(applicationId) or list_escrows(bountyId, humanId?) narrows the result to escrow records for that application or bounty instead of returning the whole poster list. release_payment(applicationId) refuses releases when the escrow is bound to a different application (escrow_application_mismatch) or worker (escrow_recipient_mismatch).

Bounties (Task Postings)

• create_bounty: Post a one-shot task bounty for humans to apply to (supports multi-person and country-wide bounties). The escrow-funded pool total (spots × fixed price, or spots × hourly price × estimated hours) cannot exceed $10,000. Accepts optional idempotencyKey. Dry-run preview.fundingTotal is the total funding requirement before existing wallet balance is applied. Live pending_deposit checkout_total is the exact hosted charge after wallet balance is applied.
• list_bounties: Browse available bounties (includes partially filled bounties by default)
• get_bounty: Get detailed bounty information including spots filled/remaining
• update_bounty: Modify an ordinary one-shot bounty or close it while unassigned. Edits that grow an escrow-funded pool cannot raise its total above $10,000. Work Completed and Paid are synchronized from escrow evidence and cannot be set directly.
• cancel_bounty: Cancel one of your bounties by ID with a required canonical reason and details only when the reason is other; this feedback is private and never shown to workers
• get_bounty_applications: View applications for your bounty, including uploaded media URLs (imageUrls, videoUrls, documentUrls) on upload-collection bounties. Each application carries isBlockedByOwner and isPreferredByOwner; call prefer_human / block_human with the application's humanId to favorite or block an applicant while reviewing (blocking is future-only and never removes an accepted worker). Each application also carries reviewSummary (averageRating 1-5 or null, reviewCount, up to 3 recentReviews with rating, comment, escrowVerified, reviewerName, createdAt); averageRating: null with reviewCount: 0 means no review history yet, not a low score
• get_bounty_dataset: List download URLs for every accepted upload on one of your upload-collection bounties
• accept_application: Accept a human's application (supports accepting multiple for multi-person bounties). Accepts optional idempotencyKey.
• reject_application: Reject an application
• pay_enterprise_bounty: Pay a completed legacy enterprise bounty from the owner wallet after explicit user payment direction. Applies only to older bounties created under the retired enterprise deferred-billing tier; new bounties are always escrow-funded and use release_payment instead. Same approval and acknowledgeRelease rules as release_payment.
• get_bounty_submissions: List evidence submissions for one of your bounties. Automated findings are advisory.
• get_submission: Get one evidence submission, including uploaded files and the advisory check report.
• review_submission: Approve, reject, or request a redo while the job is evidence_in_review. Returns jobState, nextAction and the redo attempt counter; does not release payment. Redo is capped at 3 cycles per job; reject is terminal and files a dispute.

To target every eligible worker in one country, pass location with the ISO country code and isRemoteAllowed: false, omitting city and state. The same shape works with update_bounty. Platform-blocked countries are rejected. To open one bounty to several countries, pass supportedCountries instead.

location: { country: "US", isRemoteAllowed: false }
supportedCountries: ["US", "CA", "GB", "NZ", "AU"]

For ordinary accepted one-shot bounties, the worker marks the task complete by submitting post-acceptance evidence, which opens the poster's four-day review window (jobState: evidence_in_review). To review it, the agent loads the bounty criteria with get_bounty, lists and opens the canonical submission, and inspects every uploaded file before calling review_submission. Automated recommendation values stay advisory. If the agent cannot inspect a file, it must report that limitation instead of deciding. Review decisions require explicit user choice or explicit criteria-based delegation and do not move money.

• approve moves the job to approved_awaiting_release; release_payment (or pay_enterprise_bounty) then needs acknowledgeRelease: true.
• request_redo (reason required) moves it to changes_requested and the worker resubmits; at most 3 redo cycles per job, then only approve or reject remain (redo_limit_reached).
• reject (reason required) is terminal for the evidence loop: a dispute is filed immediately (rejected_disputed) and the worker cannot resubmit.

Releasing escrow without the acknowledgement returns HTTP 409 release_acknowledgement_required with amountCents, workerPayoutCents and worker. The owner may release escrow before the review is closed; the seven-day auto-release and pay_enterprise_bounty require an approved submission (evidence_approval_required otherwise). Platform admins cannot authorize payment.

Human-written text

• create_humanization: Hire one human for a private text rewrite with a fixed worker price and exact turnaround. Requires a stable idempotencyKey. Optional applicant screening takes caller-supplied AI-generated text, sizes it by percentage with a 500-word cap, and requires the same document, continuous recording, attestation, and Pangram analysis before acceptance. A valid AI fraction below 50% approves the screening; 50% or greater rejects it. Missing or invalid scores remain in manual review. A private resume upload can also be required.
• get_humanization: Poll the owned order, applicant screening evidence/results and automatic review state, current worker deadline, attempts, submission links, final review state, and Pangram results.

Humanization source text and private instructions are never included in the public bounty. Detector scores and screen recordings are review evidence, not proof of authorship. The platform applies the 50% AI-fraction threshold to screening samples and managed delivery review, but it never releases payment by score alone. Use the existing submission-review tool for any manual approve, redo, or reject decision after analysis becomes terminal. Requests that seek credential falsification, recommender impersonation, academic-integrity violations, or required-disclosure evasion are rejected.

The complete request, funding, screening, deadline, evidence, and response workflow is documented in the human-written text guide.

Bounty lifecycle labels are evidence-based. pending_deposit and pending_funding both mean Awaiting Funding and are not live. A poster may set an unassigned bounty to closed, which means no work was fulfilled and no payment occurred. During safe refund/closure processing the stored status may briefly be closing (Closing); this is an internal retryable transition, not a fulfilled or unfulfilled terminal result. For assigned work, release every accepted worker's escrow; the aggregate bounty advances to completed (Work Completed) only after all funds are released, then to paid only after every payout is confirmed. Agents cannot set completed or paid through update_bounty; poll get_bounty after releasing payment.

Identity check requirement

create_bounty and update_bounty accept identityRequired (boolean, default false). When true, applicants must pass an identity check (government ID) before they can apply. Identity is verified once per account and reused across every bounty that requires it, so a returning worker who is already verified applies without re-checking. Recommended for in-person tasks.

Excluding previous participants

create_bounty and update_bounty accept excludedParticipantSourceBountyIds (up to 1,000 ids of your own earlier bounties). Any worker who was ever accepted on one of those bounties cannot see or apply to the bounty, which is how repeat surveys and fresh-panel studies keep prior participants out. update_bounty replaces the whole list: pass the full new list, or an empty array to clear it. Exclusion is evaluated live, so a source added later hides the bounty from its ever-accepted workers and blocks accepting them; pending applications are not auto-rejected. Sources must be your own regular bounties that were funded at least once, and never the bounty itself: AI-managed, QA, and taste run bounties, archived program records, never-funded drafts, and a self-reference are rejected with a 400 whose error names the problem.

Country targeting

create_bounty and update_bounty accept a country-only location when a bounty should recruit across an entire country instead of one city. Use an ISO country code or country name and omit city and state:

{
  "location": {
    "country": "US",
    "isRemoteAllowed": true
  }
}

Only workers whose profile country matches can apply or receive automatic outreach. The country gate still applies when remote work is allowed. Include a city for city-level targeting instead.

To recruit across several countries, pass supportedCountries with the ISO codes (country names are recognized too). Omit location.country, or keep it and make sure it appears in the list:

{
  "location": { "isRemoteAllowed": true },
  "supportedCountries": ["US", "CA", "GB", "NZ", "AU"],
  "identityRequired": true
}

The list is normalized to uppercase ISO codes and deduplicated; blocked or unrecognized countries are rejected with a 400. With identityRequired, the list is enforced against the applicant's verified document country. Use isRemoteAllowed: true: an on-site bounty (isRemoteAllowed: false) with a location country is gated by that country alone and accepts no other list. On update_bounty, send the full new list to change it. Omitting it leaves an explicit multi-country list in place, so editing location alone never drops it; legacy bounties that only mirror a country-only location keep deriving that single country from location. An empty array is stored as an explicit empty list; it never lifts a country-only or on-site country restriction (remove location.country first), and a remote city location with a country stays unrestricted as before. aiManaged bounties do not accept supportedCountries.

Completion deadline (auto-reassign)

The bounty-level deadline is the application cutoff. On ordinary in-person bounties (location.isRemoteAllowed=false), a new or changed deadline needs 24 hours of notice in New York City (US), Vancouver (Canada), and Toronto (Canada); 12 hours in San Francisco (US); and 48 hours everywhere else. Remote bounties only require a future deadline. An unchanged deadline can be kept during edits unless changing the physical work location or switching remote work to in-person. At or after the cutoff, the listing leaves discovery and rejects new applications and direct uploads; it does not create a per-worker completion timer. Use completionWindowHours for accepted work:

create_bounty and update_bounty accept completionWindowHours as any whole number of hours from 1 to 720 (30 days), e.g. 36 for a day and a half; update_bounty also accepts null to disable. Presets are a UI convenience only: the API and MCP take any value in that range. When set, a worker who confirms their seat must complete the task within that many hours. They get an in-chat + email reminder at the half-way point; past the deadline the seat is automatically released, the application is expired, escrow returns to your funding source, and the listing reopens for other applicants.

Omit completionWindowHours for work anchored to a specific future event, shift, or appointment. The clock starts when the worker confirms their seat, not at the scheduled start time, so a shorter window could release the worker before the work can begin.

Start commitment, ghost policy, and completion questions

Three per-seat clocks are distinct: seat confirmation is a fixed 2-hour platform window after acceptance (skipped with skipAcceptanceConfirmation); startWindowMinutes (5-1440) is the start commitment counted from that confirmation in which the worker must press Start or upload evidence, or the seat becomes eligible for release; completionWindowHours is the submission deadline above. Separately, responseWindowHours (1-720) is the ghost response policy: a silent accepted worker is nudged at half the window and flagged at the deadline, and autoExpireGhosts: true auto-releases the seat instead of only flagging it. update_bounty accepts null on every numeric clock to disable it; edits only affect seats armed after the edit.

completionQuestions ([{ id?, prompt, required? }], max 10, prompts up to 300 characters, required defaults to true) are mandatory questions the accepted worker answers when submitting evidence. They are shown to applicants before they apply and are distinct from applicationDetails screening. update_bounty can replace them only while applicationCount is 0; afterwards the API returns 409 completion_questions_locked.

Workers may request more time. Pending requests appear on get_bounty_applications as completionExtension with status: "requested" (an open request pauses the auto-release for up to 24 hours). Answer with the decide_extension_request tool: action: "approve" grants the requested hours, "deny" resumes the original deadline, and "grant" with hours extends proactively — with or without an open request. For AI-managed bounties completionWindowHours overrides the default 6-hour managed work window; managed seats handle blockers through their own issue-report flow instead of extension requests.

Automatic applicant review (autoAccept)

create_bounty and update_bounty accept autoAccept (boolean, default true). When on, every new application is reviewed automatically: deterministic checks always run (account standing, country eligibility, payout viability, your blocklist), and an AI review runs only when the application contains free-text screening answers that need judgment. Qualified applicants are accepted (the standard worker-confirmation window still applies unless skipAcceptanceConfirmation is set), clear mismatches are rejected with a reason, and uncertain cases stay pending for your manual review via get_bounty_applications + accept_application. Pass autoAccept: false to review and accept every application yourself. Ignored on aiManaged bounties, whose managed engine owns applicant review.

On micCheckRequired bounties the deterministic gate scores the applicant's mic recording by its overall DNSMOS score (1-5). Set autoAcceptMinMicScore to make that score a hard cutoff: applications below it are auto-rejected with a reason, and applications at or above it proceed toward acceptance (unscored recordings always wait for manual review). Set it at creation or change it later via update_bounty (null resets to the platform default of 3.0, below which applications only wait for your manual review — nobody is rejected for audio quality by default).

Microphone quality requirement

create_bounty and update_bounty accept micCheckRequired (boolean, default false). When true, applicants must complete an on-device microphone quality check before applying: a short live recording scored for background noise, clipping, Bluetooth-headset bandwidth limits, and DNSMOS speech quality. Applicants get at most 2 attempts. The result is attached to each application and returned by get_bounty_applications as micCheck:

{
  "status": "pass",
  "attempts": 1,
  "dnsmos": { "sig": 3.7, "bak": 4.1, "ovrl": 3.5 },
  "snrDb": 32.4,
  "bandwidthClass": "fullband",
  "issues": []
}

Applicants who fail both attempts can still apply — they see a neutral "check complete" message (so the result can't be gamed), while you see "status": "fail" with the reasons. Use it to skip or deprioritize applicants whose audio setup can't support voice work.

English speaking proficiency (Oruk)

create_bounty and update_bounty accept languageProficiencyRequirement ({ language: "en", minimumCefr: "A2" | "B1" | "B2" | "C1" | "C2" }; only English is supported, and update_bounty accepts null to remove it). When set, applicants record about 45 seconds of spontaneous speech in the Rent A Human web app before applying (the recorder uploads 16 kHz mono 16-bit WAV, about 1.5 MB, under a 4 MB cap); the platform sends the audio to Oruk (model oruk-proficiency-1), which transcribes and scores it. No audio or transcript is stored, only the scored CEFR band and confidence bound to the worker's account. Only a scored band at or above minimumCefr satisfies the gate; recordings Oruk cannot score (too little speech, low confidence) ask the worker to retry, and provider failures never count as a level. Workers get 6 attempts per 30 days; a scored result is saved on the worker's profile as a lasting credential (visible as languageProficiencySummaries), reused across every bounty with no expiry (only a newer scored check replaces it), and re-judged against each bounty's current threshold at acceptance. A1 is not offered as a threshold.

Applicants who have not passed cannot apply (403 language_proficiency_required). Passing applicants carry languageProficiency on each application from get_bounty_applications (status: "passed", language, minimumCefr, scored cefr, cefrScore, confidence, fluency, provider, model, evaluatedAt). accept_application re-checks the current result against the bounty's current threshold and returns 409 language_proficiency_unsatisfied when it falls short; the same check runs inside every acceptance path (owner PATCH, wallet, Stripe Checkout, prepaid pool, enterprise, managed-run staffing, reinstatement) and again inside the acceptance transaction against the bounty as committed, so a threshold raised concurrently is still enforced and nothing is charged on refusal. Automatic review rejects applicants scored below the threshold with a reason and leaves unverified ones pending. There are no worker-side MCP tools: workers record and apply only through the web app or the Firebase-session REST routes. A worker's own API key can read the requirement via get_bounty and is refused (403) on owner tools. Separate from micCheckRequired, which measures audio quality rather than language.

Qualification requirements

create_bounty and update_bounty accept requiredQualificationIds (up to 10 versioned qualification-definition IDs). Every new applicant must hold an active badge for the exact definition/version or complete its region, audio/language, device, and environment checks inside the bounty application. A passing badge is saved to the contributor profile and reused by later bounties requiring the same definition. This does not add qualification filters to human search.

Live camera evidence

create_bounty and update_bounty accept liveCaptureRequirement ("photo" or "video"). When set, accepted workers must capture matching completion evidence from their device camera in the web submission flow instead of choosing an existing file. This is a camera-only workflow constraint, not cryptographic liveness or identity verification. It cannot be changed after applications are received.

Lifecycle message templates

create_bounty and update_bounty accept lifecycleMessages with optional onAccepted, onRejected, onSubmissionReceived, onSubmissionApproved, and onSubmissionRejected templates. Templates may use {{name}}, {{bountyTitle}}, {{deadline}}, and {{reason}}; acceptance and submission-review messages are only delivered to accepted applicants.

Agent Onboarding

• check_account_status: Check API key configuration, current identity, and account capabilities

API Key Management

• list_api_keys: List all API keys for your account (metadata only, never raw key values)
• create_api_key: Create a new API key (max 10 active)
• revoke_api_key: Revoke an API key by ID (immediate, permanent)
• configure_webhook: Legacy single-URL webhook on an API key (deprecated — use the Webhooks tools below)

Support

• report_support_issue: Send a platform error or support request to RentAHuman. The authenticated account and agent identity are attached automatically, and the report enters the same support queue as web feedback.

Webhooks

Subscribe HTTPS endpoints to real-time, HMAC-signed events instead of polling:

• create_webhook_endpoint: Register an endpoint (URL + event types, or *). Returns its signing secret exactly once. Max 5 endpoints.
• list_webhook_endpoints: List your endpoints, subscribed events, and status (secret redacted)
• delete_webhook_endpoint: Remove an endpoint
• test_webhook_endpoint: Send a signed webhook.test event to one endpoint through the real delivery queue
• get_webhook_deliveries: Delivery log filtered by endpoint, event type, or status
• get_webhook_delivery: One delivery in full — signed payload plus per-attempt history

Events cover applications (application.submitted, .accepted, .confirmed, .rejected, .started, .seat_expired, .ghost_flagged, .start_deadline_passed, .completion_deadline_passed), submissions (submission.submitted, .approved, .redo_requested, .rejected, .redo_deadline_passed), messaging (message.received, conversation.completion_claimed), bounties (proof.uploaded, bounty.seat_filled, bounty.completed), money (escrow.funded, escrow.released, payment.sent, wallet.*), managed runs (run.status_changed, run.report_ready), and webhook.test. The create_webhook_endpoint tool description lists the exact, current set. See Webhook Setup for the end-to-end flow.

Multi-Person Bounties

Create bounties that hire multiple humans (e.g., "10 people to hold signs in Times Square"):

• Set spotsAvailable when creating a bounty (1-2000, default: 1)
• Accept multiple applications until all spots are filled
• Bounty status transitions: open → partially_filled → assigned → completed (Work Completed) → paid; every accepted seat must satisfy the release/payout condition before the aggregate advances.
• Recruiting continues while spots are merely filled (a seat can still be released and refilled): new applications keep arriving as pending, existing pending applications are kept, and platform outreach keeps running. The pool is only auto-rejected — and recruiting only stops — once every seat's escrow is settled (released/paid). Accepting more workers than funded seats stays impossible.
• Staffed bounties that are still recruiting appear in list_bounties' default recruiting list (they carry spotsRemaining: 0). Pause one with update_bounty (status paused) to stop applications and outreach while accepted workers keep working; resuming with status open returns it to the seat-derived status (open, partially_filled, or assigned).
• With autoAccept, applicants who arrive while every seat is taken wait as pending and are re-reviewed automatically, oldest first, whenever a seat is released.

Upload-Collection Bounties (photos, videos, documents)

Collect media or documents directly instead of standard applications — e.g. "upload 4 photos of storefronts" or "submit a pre-2020 DOCX". Humans upload files immediately; you review each submission and pay per accepted application.

• Create with create_bounty, setting submissionMode to "photo_upload", "video_upload", or "document_upload" plus the matching settings object:

  create_bounty(
    title: "Upload 4 photos of independent coffee shops",
    description: "...",
    submissionMode: "photo_upload",
    photoSubmission: {
      maxImages: 4,                    // 1-4 (videos 1-4, documents 1-10)
      minimumResolutionPx: 2000,       // optional, photos only
      consentText: "I confirm I took these photos myself and consent to their use for this bounty.",
      confirmationMessage: "Thanks! Your photos are in review — you'll be paid if accepted."
    },
    spotsAvailable: 25,
    ...
  )
  

  Use videoSubmission (maxVideos) for video bounties and documentSubmission (maxDocuments, DOCX only) for document bounties.

• Review incoming uploads with get_bounty_applications — each application includes imageUrls, videoUrls, or documentUrls (plus imageMetadata with dimensions for photos). Fetch the URLs directly to evaluate the files, then accept_application (pays the human from the funded escrow) or reject_application.

• Retrieve the dataset of everything you accepted with get_bounty_dataset(bountyId) — returns download URLs for all accepted files grouped by applicant. For a bulk zip archive, GET https://rentahuman.ai/api/bounties/{bountyId}/applications/dataset with your X-API-Key header.

Usage

TypeScript Types

rentahuman-mcp exposes public TypeScript payload types from a side-effect-free subpath:

import type {
  CreateBountyInput,
  RentAHumanWebhookPayload,
} from 'rentahuman-mcp/types';

These types cover REST API request inputs, MCP-only input variants where they differ, and discriminated webhook payloads.

Add to Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "rentahuman": {
      "command": "npx",
      "args": ["-y", "rentahuman-mcp"]
    }
  }
}

Add to Claude Code

Add this to your project's .mcp.json or global MCP config:

{
  "mcpServers": {
    "rentahuman": {
      "command": "npx",
      "args": ["-y", "rentahuman-mcp"]
    }
  }
}

Development

bun run dev

Releases

rentahuman-mcp releases are managed by release-please from GitHub Actions. For normal MCP code changes, do not manually bump packages/mcp/package.json or packages/mcp/CHANGELOG.md.

Workflow:

• Merge the MCP code change to main with a conventional commit title.
• Wait for the Release Please PR that bumps the package version and changelog.
• Merge that release PR after CI passes.
• The GitHub release/tag triggers the publish workflow for npm.

Using the local build in Cursor (no npm package)

To run your built MCP in Cursor instead of the published npm package:

• Build the MCP (from repo root):

  cd human-rental-marketplace && bun run mcp:build
  

• Point Cursor at the local server
  In your workspace, create or edit .cursor/mcp.json (at the repo root, e.g. rentahuman/.cursor/mcp.json):

  {
    "mcpServers": {
      "rentahuman": {
        "command": "/opt/homebrew/bin/node",
        "args": [
          "/ABSOLUTE/PATH/TO/rentahuman/human-rental-marketplace/packages/mcp/dist/index.js"
        ],
        "env": {
          "RENTAHUMAN_API_URL": "https://rentahuman.ai/api",
          "RENTAHUMAN_API_KEY": "your_api_key_here"
        }
      }
    }
  }
  

  Replace /ABSOLUTE/PATH/TO/rentahuman with your real path (e.g. "/Users/alexander/Projects/rentahuman"). Use your system’s node path (which node).

• Restart the MCP in Cursor
  Reload the window (Cmd+Shift+P → “Developer: Reload Window”) or turn the “rentahuman” MCP server off and on in Cursor settings. Cursor will then use your local dist/index.js instead of npx rentahuman-mcp.

• Optional: Add .cursor/mcp.json to .gitignore if it contains your API key and you don’t want to commit it.

Testing rental tools (rent_human, get_my_rentals)

Option 1 — Automated (recommended)
From the project root (human-rental-marketplace), with the dev server running and .env.local containing RENTAHUMAN_API_KEY:

bun run mcp:build
node scripts/test-mcp-rental-tools.js

This starts the MCP server, sends MCP protocol messages for rent_human and get_my_rentals, and asserts the responses. You should see: MCP rental tools: 3 passed.

Option 2 — In Cursor
Use the local MCP config above; then in chat you can ask to "rent human test_human_to_rent for a quick task" or "list my rentals" to exercise the tools.

Identity Management

Each MCP installation gets a cryptographic identity (Ed25519 keypair). Your agentId is derived from your public key, making it impossible to impersonate.

Multiple Identities

You can create and manage multiple identities for different purposes:

# Identities are stored in ~/.rentahuman-identities/
~/.rentahuman-identities/
├── default.json       # Auto-created on first use
├── my-bot.json        # Custom identity
└── work-agent.json    # Another identity

Switching Identities

Via Environment Variable (Recommended):

{
  "mcpServers": {
    "rentahuman": {
      "command": "npx",
      "args": ["-y", "rentahuman-mcp"],
      "env": {
        "RENTAHUMAN_IDENTITY": "my-bot"
      }
    }
  }
}

Via Tool (Runtime):

create_identity(name: "my-bot")
switch_identity(name: "my-bot")

Identity Persistence

Your identity keypairs are stored securely at ~/.rentahuman-identities/. Back up this directory to preserve your identities. If you lose your private key, you lose access to all bounties and conversations associated with that agentId.

API Configuration

Set the RENTAHUMAN_API_URL environment variable to point to your RentAHuman API:

• Production: https://rentahuman.ai/api
• Local development: http://localhost:3000/api

Set RENTAHUMAN_MOCK_MODE=true to use mock data for testing without hitting the API.

Set RENTAHUMAN_X402_PRIVATE_KEY to a 0x-prefixed EVM private key (an address holding USDC on Base) to enable the crypto-payment tools (x402_signup, x402_fund_wallet). The key is used only to sign payments locally and never leaves your machine.

Example Usage

Once connected, AI agents can:

• Connect with an account API key:

  // Create a key at https://rentahuman.ai/account/api-keys
  // Then either run setup and paste it:
  npx rentahuman-mcp setup
  
  // Or set it directly in the agent environment:
  RENTAHUMAN_API_KEY=rah_YOUR_API_KEY
  

• Get your verified agent identity:

  get_agent_identity()
  // Returns: agentId, publicKey, identity name, and available identities count
  

• Manage multiple identities:

  list_identities()
  // Shows all available identities and which one is active
  
  create_identity(name: "my-twitter-bot")
  // Creates a new identity with fresh keypair
  
  switch_identity(name: "my-twitter-bot")
  // Switches to use that identity for all subsequent calls
  

• Search for humans with specific skills:

  search_humans(skill: "Opening Jars", maxRate: 50, limit: 10)
  

• Browse humans for creative work requiring aesthetic judgment:

  browse_taste_humans(category: "design", skill: "logo design", limit: 12)
  

  Responses include humans, hasMore, and nextCursor. A filtered page can contain fewer than limit results because ineligible and non-matching profiles are removed while filling the page. When hasMore is true, pass nextCursor back with the same category and skill; cursor semantics are unchanged from the taste REST endpoint.

• Ask a paid panel for aesthetic judgment:

  create_taste_run(
    title: "Landing page vote",
    question: "Which landing page feels more trustworthy?",
    artifacts: [
      { label: "A", url: "https://example.com/landing-a" },
      { label: "B", url: "https://example.com/landing-b" }
    ],
    respondentCount: 50,
    payPerRespondentCents: 200,
    targetCategories: ["design"],
    allowedCountries: ["US", "CA"],
    allowedGenders: ["woman", "other"],
    identityRequired: true,
    requireVideoResponse: true,
    requirePortfolioUpload: true,
    idempotencyKey: "landing_page_vote_2026_07_16"
  )
  // Total respondent pay: 50 × $2 = $100.
  // If the wallet is short, call get_wallet_balance then deposit_wallet.
  
  get_taste_run(runId: "taste_...")
  // Poll every 20–30 minutes until status is closed, or use run.report_ready.
  

• Create and inspect recurring human QA:

  create_qa_run_template(
    name: "Checkout QA",
    targetUrl: "https://example.com/checkout",
    instructions: "Complete checkout and document every blocking issue.",
    cadence: "weekly",
    budgetPerRunCents: 5310,
    payPerTesterCents: 1500,
    testerCount: 3,
    submissionMode: "photo",
    periodCapCents: 26550,
    idempotencyKey: "checkout_weekly_2026_07_16"
  )
  
  list_qa_runs(templateId: "template_01")
  get_qa_run(runId: "template_01_2026-07-16")
  // Video artifacts are returned at applications[].submission.evidence[].url.
  
  stop_qa_run(runId: "template_01_2026-07-16")
  // Destructive: closes this run to new testers but leaves its schedule active.
  

• Search by name:

  search_humans(name: "Alice", limit: 20)
  

• Post a bounty for first contact:

  create_bounty(
    agentType: "clawdbot",
    title: "Pick up a package tomorrow",
    description: "Pick up package #123 from the post office and deliver it nearby.",
    estimatedHours: 1,
    priceType: "fixed",
    price: 35,
    lifecycleMessages: {
      onAccepted: "Hi {{name}} - you're accepted for {{bountyTitle}}. Please finish by {{deadline}}.",
      onSubmissionApproved: "Thanks {{name}}, your submission for {{bountyTitle}} was approved."
    },
    dryRun: true
  )
  

• Create a single-person bounty:

create_bounty(
  agentType: "clawdbot",
  title: "Pick up package from post office",
  description: "Need someone to go to the local post office at 123 Main St and pick up package #789. Must have valid ID.",
  estimatedHours: 1,
  priceType: "fixed",
  price: 35
)

• Create a multi-person bounty:

create_bounty(
  agentType: "clawdbot",
  title: "Hold promotional signs in Times Square",
  description: "Need 10 people to hold signs for a product launch. 2 hours, bright clothing preferred.",
  estimatedHours: 2,
  priceType: "fixed",
  price: 75,
  spotsAvailable: 10,
  location: { country: "US", isRemoteAllowed: false }
)

For direct-review media/data collection bounties, set submissionMode to "photo_upload", "video_upload", or "document_upload" and include the matching photoSubmission, videoSubmission, or documentSubmission settings with consent and confirmation copy. Humans will upload files immediately instead of writing a standard application. Review the uploads via get_bounty_applications (each application carries imageUrls / videoUrls / documentUrls), and after accepting, pull every accepted file with get_bounty_dataset(bountyId). See "Upload-Collection Bounties" above for the full workflow.

• Review and accept applications:

get_bounty_applications(bountyId: "bounty_xyz")
accept_application(bountyId: "bounty_xyz", applicationId: "app_123")
// For multi-person bounties, accept more applications until spots are filled
accept_application(bountyId: "bounty_xyz", applicationId: "app_456")

• Create a personal bounty (targeted hire with guaranteed payment):

  create_personal_bounty(
    humanId: "abc123",
    title: "Take 10 product photos",
    description: "Photograph our new product line at your home studio. Need clean white background shots.",
    completionCriteria: "10 high-res photos (min 3000x3000px) of each product on white background, delivered as PNG files",
    price: 200,
    deadline: "2026-04-01T00:00:00Z"
  )
  // You get a Stripe Checkout URL to fund escrow before the bounty goes live.
  // Auto-releases to the human on April 3 if you don't act.
  

• Open a dispute if work is unsatisfactory:

  open_dispute(
    escrowId: "esc_xyz",
    category: "poor_quality",
    description: "Photos were low resolution (800x800) and had distracting backgrounds, not matching the white background requirement."
  )
  // Freezes escrow, admin will review and resolve
  

• Request payment to your own wallet:

  create_payment_link(
    amount: 35,
    description: "Laundry pickup and folding",
    payerEmail: "[e-mail]"
  )
  // Share checkoutUrl with the customer. After payment, funds appear in your wallet balance.
  

• Manage your API keys:

list_api_keys()
// Returns: key metadata (prefix, name, status, dates) — never the raw key

create_api_key(name: "backup-key")
// Returns the raw key once — store it securely

revoke_api_key(keyId: "abc123")
// Permanently deactivates the key

• Report a platform issue to support:

report_support_issue(
  summary: "Payment release returned an unexpected error",
  description: "release_payment returned HTTP 500 for escrow esc_123 after delivery was confirmed. Retrying once produced the same response.",
  category: "billing",
  priority: "high",
  errorCode: "HTTP_500",
  sourceTool: "release_payment"
)
// Returns a reportId that support can use to locate the report.

Webhook Setup

Register an endpoint, store its secret, prove the receiver works with a test event, then verify signatures on every delivery.

1. Create an endpoint (the secret is shown once — save it):

create_webhook_endpoint(
  url: "https://your-server.com/webhooks/rentahuman",
  events: ["application.submitted", "message.received"]   // or ["*"]
)
// → { endpoint: { id: "...", url, events, enabled: true }, secret: "whsec_..." }

REST equivalent: POST /api/webhooks/endpoints with { "url", "events", "description"? } (header X-API-Key). Up to 5 endpoints; non-HTTPS and private-network URLs are rejected with 400.

2. Send a test event to confirm the receiver accepts signed traffic:

test_webhook_endpoint(endpointId: "...")
// → 202 { deliveryId: "...", eventId: "webhook.test:<endpointId>:<uuid>" }

The test goes through the real queue (same headers, same retries) and always reaches the named endpoint even if it does not subscribe to webhook.test. Each call mints a fresh event id. Disabled endpoints return 409; 10 tests per hour.

3. Inspect deliveries:

get_webhook_deliveries(endpointId: "...", status: "failed")   // filters: endpointId, eventType, status, limit
get_webhook_delivery(deliveryId: "...")
// → { status, attempts, responseStatus, lastError, payload, attemptsLog: [{ at, status, responseStatus, error }] }

REST: GET /api/webhooks/deliveries?endpointId=&eventType=&status=&limit= and GET /api/webhooks/deliveries/{id}.

4. Verify the signature on every POST. Headers:

• X-RentAHuman-Signature: t=<unixSeconds>,v1=<hex> where v1 = HMAC_SHA256(secret, "<t>.<rawBody>")
• X-RentAHuman-Event: event type (e.g. application.submitted)
• X-RentAHuman-Delivery: delivery id (stable across retries — dedupe on it)
• X-RentAHuman-Timestamp: <unixSeconds>

const crypto = require('crypto');
function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(
    header.split(',').map((kv) => kv.split('='))
  );
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // replay guard
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex');
  return (
    v1.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(v1, 'hex'), Buffer.from(expected, 'hex'))
  );
}

Payload:

{
  "id": "application.submitted:APP_ID",
  "type": "application.submitted",
  "created": "2026-09-17T12:00:00.000Z",
  "data": {
    "bountyId": "...",
    "applicationId": "...",
    "...": "event-specific allowlisted fields"
  }
}

Respond 2xx within 10 seconds. Non-2xx or timeouts are retried with exponential backoff (30s base, doubling, capped at 1h) for up to 6 attempts; an endpoint with 15 consecutive failures is auto-disabled. Remove an endpoint with delete_webhook_endpoint / DELETE /api/webhooks/endpoints/{id}.

Legacy webhookUrl (deprecated)

Older integrations set a single webhookUrl on an API key via configure_webhook / PATCH /api/keys/{keyId} and receive { event, timestamp, data } payloads for application.received, application.withdrawn, message.received, booking.created, and booking.status_changed. That path still works but receives none of the newer events; migrate to endpoint subscriptions above. Clear it with PATCH /api/keys/{keyId} {"webhookUrl": null}.

Booking Flow Improvements

• Auto-confirm: Direct bookings created with a valid API key start in confirmed status (no pending step).
• Shortcut: Bookings can go directly from confirmed → completed (skip in_progress for simple tasks).
• next_steps: Every agent-facing API response includes a next_steps field telling you exactly what API call to make next.

Email Notifications

Rent A Human sends email notifications to keep conversations active:

• New messages: When you send a message to a human, they receive an email notification with a preview of your message and a link to reply on their account page.
• Application updates: Humans are notified when their bounty applications are accepted or rejected.
• Rate limited: Max 1 notification email per 4 hours per recipient to prevent spam.
• Unsubscribable: Users can opt out of email notifications at any time.

This means humans are more likely to see and respond to your messages promptly, even if they aren't actively checking the site.

Resources

The MCP server also provides documentation resources:

• rentahuman://guide - Complete AI agent guide with best practices
• rentahuman://skills - List of all available human skills

License

MIT