HumanFn for AI agents

HumanFn is a remote MCP server that lets an agent get a physical-world task done at an address — checked, photographed, measured, picked up — by a local person, and receive structured proof. HumanFn currently serves the Phoenix, Arizona metro area only. Requests elsewhere are recorded and declined.

Endpoint & transport

https://humanfn.com/mcp — Streamable HTTP. Speaks MCP 2026-07-28 (stateless) and falls back to 2025-era clients automatically.

Authentication

None required. Each request returns an access_token; every later call needs request_id + access_token. The human also gets a status link by email.
Platform keys (optional): Authorization: Bearer ak_… identifies a platform. Keys are issued by HumanFn; an invalid key gets HTTP 401.

Tools

request_execution

write · not sensitive (nothing is charged) · readOnly=false · destructive=false · idempotent=true (with client_request_id) · openWorld=true

Creates a request for a quote and emails the customer a status link. A person reviews it. Returns request_id + access_token (store both).

objective	string	What must be true or be captured when the job is done. Be specific: what to photograph, measure, check, deliver.
address	string	Full street address in the Phoenix, AZ metro area.
access_notes?	string	Gate codes, who to ask for, where to park, hours.
complete_by?	string	Deadline for the outcome. ISO 8601 with offset (Phoenix is UTC-07:00).
max_budget_usd?	number
contact_email	string	The human customer's email. Quotes and status links are sent here.
contact_name?	string
contact_phone?	string
client_request_id?	string	Your idempotency key. Retrying with the same key returns the same request instead of creating a duplicate.

get_request

read · readOnly=true · destructive=false · idempotent=true · openWorld=false

Returns phase, quote, job and — once completed — the result with answers and photo links (valid 1 hour; call again for fresh links).

request_id	string
access_token	string

answer_clarification

write · not sensitive · readOnly=false · destructive=false · idempotent=false · openWorld=false

Sends the answer to the reviewer and puts the request back in review.

request_id	string
access_token	string
answer	string

confirm_execution

write · SENSITIVE (purchase) — get the human's approval of seller, price, deadline, scope and cancellation policy first · readOnly=false · destructive=true · idempotent=true · openWorld=true

Returns phase payment_required and a payment_url on HumanFn's site that the human opens to pay with Stripe. It never charges by itself and is NOT a confirmation; the job is confirmed only when get_request shows phase confirmed.

request_id	string
access_token	string
quote_id	string

cancel_execution

write · SENSITIVE (may trigger a refund) · readOnly=false · destructive=true · idempotent=true · openWorld=true

Before payment: withdraws (nothing charged). After payment, before a person is assigned: cancels and refunds automatically (minus processing fees). Later: files a cancellation request reviewed per the policy shown with the quote.

request_id	string
access_token	string

Every result includes structuredContent (schema_version 1) and a text summary. Errors return isError: true with { error: { code, message } }.

Status (phase)

Jobs take hours or days. Tools return immediately; poll get_request and respect next_poll_after_seconds. Treat unknown phases as pending.

quote_pending	A person is reviewing the request (typically < 4 business hours).
needs_clarification	Read clarification.question; reply with answer_clarification.
declined	Not taken; see decline.reason (unsupported_region, unsupported_task, prohibited, capacity_unavailable, other).
quoted	Show the human the quote; call confirm_execution only after they approve.
quote_expired	The quote lapsed; the human can ask for a new one.
payment_required	Returned by confirm_execution: the human must open payment_url and pay.
payment_processing	Payment received, confirming; poll again shortly.
confirmed	Paid; a local person is being arranged.
in_progress	A person has accepted and is working / work is under review.
completed	Done; read result (summary, answers, photos).
failed	HumanFn could not complete it; refunded in full.
cancelled	Withdrawn or cancelled.
cancellation_requested	A post-payment cancellation is being reviewed.

Errors

not_found	Unknown request_id, or the access_token doesn't match it (same message either way).
invalid_state	The action doesn't apply right now (e.g. quote expired or superseded, not awaiting clarification).
validation_error	Bad input (e.g. deadline in the past). The message says what to fix.
conflict	client_request_id was reused with different content.
rate_limited	Too many requests for this email today (limit 10/day).
unauthorized	An API key was sent but isn't valid (HTTP 401 for the whole call).

Rate limits

120 MCP calls per minute per IP (HTTP 429 with Retry-After).
10 new requests per customer email per 24 hours.

Payments & cancellation

Prices are fixed quotes in USD. The human pays on HumanFn's Stripe-hosted page; agents never handle card data. The cancellation and refund policy is returned with every quote (quote.cancellation_policy) and on the terms.

Sandbox (testing without real charges)

Ask support@humanfn.com for a sandbox key. Sandbox requests get an instant $1.00 quote, pay through Stripe test mode (card 4242 4242 4242 4242), never dispatch a person, and can be finished with “Simulate completion” on the status page so you can see a full completed result.

Data handling

HumanFn receives the task, address, access notes and the customer's contact details. The address is shown only to the local person who accepts the job. Results contain photos, answers and photo location; never the worker's identity. Job data is kept 12 months after the job ends (covers card-dispute windows and claims), then deleted. See the privacy policy.

What we don't do

We don't take: anything illegal, weapons, drugs or prescriptions, medical or caregiving tasks, childcare, work requiring a professional license, dangerous work, major construction, or custody of high-value items.

Support: support@humanfn.com · Security: security@humanfn.com