MCP REFERENCE

Huint MCP

One tool call to a verified person, standing exactly where your agent’s data runs out.

SPEC 3.2

SERVER 0.2.0 (BETA)

AUGUST 2026

Download the PDF

12 pages · Letter / A4

01 / OVERVIEW

What This Is

Agents cannot see the physical world. Huint gives an agent one tool call to a photo of a real place, taken by a real person, on demand, with location, time, and device verification, settled against a prepaid balance.

There’s one task model. A public contest is an ordinary task with more slots, not a different object. Everything in this document applies to both.

MCP CLIENT

your agent

▼

BEARER AUTH

HUINT MCP

this server

▼

SERVICE ROLE

SUPABASE RPCS

security definer

▼

WRITES

POSTGRES

source of truth

Huint MCP never writes a table directly. Every mutation goes through a security-definer RPC that checks ownership, validation, balance, and escrow before Postgres sees it.

02 / GETTING IN

Connect

Hosted streamable HTTP at https://mcp.huint.io/mcp. Stateless: every request authenticates itself. Two auth schemes, both resolving to one operator account:

API KEY

Bearer hnt_…, minted at portal.huint.io, matched server-side by SHA-256.

OAUTH 2.1

A Supabase-issued JWT, audience-bound to the MCP resource. Discoverable from the WWW-Authenticate header on any 401.

Claude, Codex, Cursor, and ChatGPT all auto-register through Dynamic Client Registration. For Codex specifically:

# add once

codex mcp add huint --url https://mcp.huint.io/mcp

# reauth after an expired session

codex mcp logout huint

codex mcp login huint --scopes openid,email

Start a fresh session after adding, reauthenticating, or picking up a changed tool surface: a running session doesn’t reliably hot-reload it.

03 / VOCABULARY

Core Concepts

Operator: the account. Balance, spend limits, API keys. One operator can run many agents.

Agent: whichever client authenticated the request. Reads default to the calling agent; all_agents=true widens to the whole operator.

Task: the one object. A single observation or a 1,000-tasker contest: same tool, same shape, just max_taskers.

Escrow: held the moment a task is created, released only by verification, refunded only by cancel or expiry.

Clearing Huint’s own vision and human checks doesn’t pay the tasker by itself. It makes the submission official and starts a fifteen-minute window for the calling agent to accept it, reject it, or let the clock run out. Only the first and third end in a payout.

The full mechanism is in The Trust Architecture, section 04 of the Huint white paper.

04 / THE LOOP

The Workflow

Five tools cover the whole life of a task. Cancel is the escape hatch, valid any time a task is still open.

RESOLVE

→

CREATE

→

TRACK

→

INSPECT

→

DECIDE

Resolve is optional · Cancel refunds the hold, any time a task is still open

Resolve. Turn a place or coordinates into a provider-native payload before you spend anything. Optional; quote and create resolve city/ZIP input the same way automatically.

Create. quote_task to preview the hold, then create_photo_task. Idempotent on agent_task_id: a retry never charges twice.

Track. Poll list_pending_reviews or get_task_status until something’s submitted.

Inspect. Pull the photo itself with get_submission_image(s) before deciding anything.

Decide. accept_submission pays. reject_submission blocks that tasker and reopens the task; it never refunds.

Cancel works on any open task with no claim or review in flight, deadline or not.

05 / ALL 18

Tool Reference

Grouped by where they sit in the workflow. MUTATES tools move money or state and confirm before running; everything else is read-only.

SETUP

get_connection_status

Verify the server is reachable and the current credential resolves to an active operator. Safe to call after setup or re-auth.

get_capabilities

Return the capability contract: identity, product boundaries, the agent playbook, economic model, error tokens, invariants. Pass sections for heavy reference blocks: full schemas, the radius table, worked examples.

get_balance

Return balance_cents, daily_limit_cents, per_task_max_cents, and outstanding holds. Call before create_photo_task to confirm funds.

RESOLVE

resolve_location

Resolve a free-text place query into a provider-native payload: lat, lng, friendly name, formatted address, provider ids. Apple Maps first, Google fallback.

reverse_geocode

Reverse-geocode a lat/lng pair into the same provider-native payload create_photo_task expects.

resolve_location_scope

Preview the canonical Apple location scope Huint will store for a US city or ZIP. Optional: quote and create resolve the same input automatically.

CREATE

quote_task

Dry run of create_photo_task: same inputs, no hold, nothing mutated. Returns the projected charge and remaining credit.

create_photo_task

MUTATES

Create the task. Reach is anywhere, fixed_location, city, or zip_code; only fixed_location nests radius_meters. Add place_selection to require a matching nearby place. Raise max_taskers (1 to 1,000) for a contest. Idempotent on agent_task_id.

TRACK

get_task_status

Status, cancellation eligibility, and exit policy for one task. Lookup by task_id or agent_task_id.

list_tasks

List recent tasks for the calling agent, or the whole operator with all_agents=true. Offset-paged.

list_pending_reviews

The lightweight queue: submitted tasks still inside the fifteen-minute review window, oldest first.

get_task_result

Every submission for a task, with verification evidence, entry answers, and signed image URLs. Returns the task’s current state instead if nothing’s official yet.

INSPECT

get_submission_image

Download one submitted photo as an image content block.

get_submission_images

Download every submitted photo for a task as image content blocks, for review before a decision.

DECIDE

accept_submission

MUTATES

Verify a claim’s submissions, mark the task verified, release the payout.

reject_submission

MUTATES

Reject a claim’s submissions with one of five typed reason codes and an optional note. No refund: blocks that tasker, reopens the task.

set_auto_review

MUTATES

Turn Huint-hosted AI auto-review on or off, account-wide. Gated: needs either an allowlisted Huint pilot slot or the operator’s own Anthropic/OpenAI key on file at portal.huint.io (their billing from that point on). Only fires under the operator’s auto-review bounty ceiling and daily cap, and disables itself after repeated LLM errors.

CANCEL

cancel_task

MUTATES

Cancel an open task with no in-flight claim or review and refund the unused escrow. Works on deadline-bound and multi-slot tasks too.

06 / THE NUMBERS

Pricing & Limits

Bounty floor

$1.00

Platform fee

10% of bounty

Per-task cap (default)

$25

Daily cap (default)

$100

Contest size

1–1,000 taskers

Fixed-location radius

30–2,000 m

Selected-place capture gate

804.672 m

GPS freshness required

≤15 sec, ≤100 m

Claim window

30 min

Agent review window

15 min, then auto-pay

Create rate limit

10/min, 100/hr

Reject rate limit

20/min

Task deadline range

1 hr–30 days

Active API keys per operator

The hold is bounty plus the 10% platform fee, per slot, taken the moment the task is created. There’s no separate Vision Gate fee: every image runs through it regardless of bounty or radius, at no additional cost.

07 / JUDGMENT CALLS

Rejection Codes

Five codes for reject_submission, all judgment on content that already passed upload. Don’t reject for GPS, timestamp, device, or photo count. Those fail automatically, before anyone sees the photo.

unclear

Image unclear

Blurry, dark, glare, obstructed, or otherwise unreadable.

wrong_subject

Wrong subject

Right location, wrong thing in frame.

framing_or_angle

Bad framing

Right subject, cropped, wrong angle, or the requested detail is out of frame.

suspected_reuse

Suspected reuse

Recycled, screen-photographed, or staged. Use sparingly: it’s a fraud signal against the tasker.

policy_violation

Contains PII

Identifiable bystanders, plates, or IDs visible in frame.

08 / WHEN IT FAILS

Errors

read_only_token

The credential is scoped read-only; mutation tools are refused.

per_task_limit_exceeded

bounty_cents exceeds per_task_max_cents (default $25).

daily_limit_exceeded

This task would push today’s holds past daily_limit_cents (default $100).

task_has_in_flight_work_cancel_unavailable

An active claim, submission, or review is blocking cancellation.

location_not_found, outside_required_area, &c.

The location system’s own tokens. See get_capabilities(sections: [“location_resolution”]) for the full list.

An unrecognized error token is surfaced verbatim. Don’t retry a validation failure: the input was rejected on purpose.

09 / THE LINE

Safety & Scope

USE IT FOR

A current photo or a simple visible-condition check at a real place.

A specific target: a sign, entrance, storefront, dock door, lot, or facility.

Something capturable lawfully from a public or otherwise accessible viewpoint.

NEVER FOR

Digital research, errands, delivery, or physical manipulation.

Following, identifying, or surveilling a person.

Trespassing, forced entry, or bypassing locks and security.

Questioning employees, residents, guards, or bystanders.

Vague investigation: “find out who lives here.”

A real place, a real person, a photo you can verify. That’s the whole scope.

Download the PDF

The full reference, print-ready.

Huint is a product of Nanu Connect LLC, doing business as Huint Labs. Companion to The Ground Truth Network white paper. Prepared August 2026. MCP Reference · Spec 3.2 · Server 0.2.0 (beta)

Point your agent at the real world.

Create an operator account in the portal and connect over MCP. Tasks settle against a prepaid balance.

Start Building

ELSEWHERE IN DOCS

Task Variables

Every live field on a task, and who sets it.

The Ground Truth Network

Why the network exists and how trust is constructed.