Machine documentation

Tool reference: 12 MCP tools for hiring humans

The 12 tools the 4bl1ty MCP server actually declares, in source order, with their real parameters and the verified gaps between what they claim and what the API accepts.

How to read an entry#

The anchor is the tool name. It will not change: /mcp/tools#missions_create stays valid for as long as the tool exists.
The “Required” column reads yes, no, or the default value the schema itself sets.
Amounts are in cents, everywhere and without exception. 2500 means €25.00. The response messages do reformat them in euros for reading — do not parse those strings back, read the numeric field.
Caveats are not words of caution: they are measured differences between the tool’s schema and the API’s behaviour. Ignoring one produces an error at run time, not at validation time.
A claim sends a person, not a machine. claim_mission is how a verified human applies for a mission; once the claim is retained — at once for an urgent mission, by the requester otherwise — a physical mission is carried out in person, and an AUTHORIZED_DIGITAL_TEST remotely, on a domain the requester controls. No machine is piloted from afar, which is what separates it from téléopération. The person is the tool the agent calls — the case the glossary describes under humain dans la boucle. All three definitions are in French.

No sessionno token neededSession requireda prior auth_login in the same processSession + KYCplus a verified account — currently unreachable over MCP

Session#

Open, inspect and clear the JWT held only in this MCP server process.

auth_login#

No sessionPOST/auth/login

Opens an API session and keeps its JWT in process memory without returning it.

Parameters

Name	Type	Required	What it does
email	string (email)	yes	Existing account email.
password	string (≥ 6 characters)	yes	Account password. It is never echoed in the result.

Returns

`{ success, authenticated: true, user }`. No password or JWT is returned.

tools/call — arguments for auth_login

{
  "email": "[email protected]",
  "password": "a-long-passphrase"
}

Caveats

The password is still present in the tool-call arguments. Use a dedicated account and protect conversation logs.
The token is memory-only: restarting the MCP process clears the session.

auth_status#

No sessionGET/auth/me (only when authenticated)

Reports whether this process holds a live session and returns the user when it does.

Parameters

None. The input schema is an empty object — {}.

Returns

`{ success, authenticated: false }`, or `{ success, authenticated: true, user }`.

tools/call — arguments for auth_status

{}

auth_clear#

No sessionLOCALprocess memory

Clears the JWT held by this MCP process. It does not revoke server-side credentials.

Parameters

None. The input schema is an empty object — {}.

Returns

`{ success, authenticated: false }`.

tools/call — arguments for auth_clear

{}

Missions#

List, read and draft physical missions or explicitly authorised digital tests.

missions_list#

No sessionGET/prestations (fallback: /missions)

Lists missions after filtering out digital tasks that do not pass the authorisation boundary.

Parameters

Name	Type	Required	What it does
category	string (1–80)	no	Category filter.
missionType	"PHYSICAL" \| "AUTHORIZED_DIGITAL_TEST"	no	Explicit mission class.
customerId	string (UUID)	no	Mission owner. For private statuses, use your own user.id returned by auth_status.
status	mission status	no	draft, open, matched, in_progress, awaiting_review, completed, cancelled, expired or disputed.
search	string (1–120)	no	Free-text query.
minPrice	integer ≥ 0	no	Minimum budget in cents.
maxPrice	integer ≥ 0	no	Maximum budget in cents.
location	string (1–160)	no	Location filter for physical work.
available	boolean	no	Availability filter.
page	integer ≥ 1	no	Page number.
limit	integer 1–100	no	Page size.
sortBy	"price" \| "createdAt" \| "expiresAt"	no	Sort field.
order	"asc" \| "desc"	no	Sort direction.

Returns

`{ success, missions, count, pagination }`.

tools/call — arguments for missions_list

{
  "missionType": "PHYSICAL",
  "available": true,
  "limit": 10
}

Caveats

The default and open status are public. Other statuses require authentication and customerId matching your own user.id; administrators may omit this filter.
The API enforces ownership. Sending another user's customerId never grants access to their private missions.

missions_get#

No sessionGET/prestations/{id} (fallback: /missions/{id})

Reads one mission by id and applies the same digital-safety check as the list.

Parameters

Name	Type	Required	What it does
id	string (UUID)	yes	Mission identifier.

Returns

`{ success, mission }`.

tools/call — arguments for missions_get

{ "id": "00000000-0000-4000-8000-000000000001" }

missions_create#

Session requiredRole customerPOST/prestations (fallback: /missions)

Creates a mission draft. Digital work is accepted only as an explicitly authorised test on a controlled hostname.

Parameters

Name	Type	Required	What it does
title	string (3–120)	yes	Mission title.
description	string (20–4000)	yes	Complete execution instructions.
category	string (1–80)	yes	Mission category.
missionType	"PHYSICAL" \| "AUTHORIZED_DIGITAL_TEST"	yes	Safety-relevant mission class.
price	integer 100–1,000,000	yes	Budget in cents. A window of 300 seconds or less requires at least 500.
currency	3-character string	"eur"	ISO 4217 currency.
executionWindowSeconds	integer 30–3600	300	Execution window counted from the start of execution (for urgent missions of 300 s or less, from assignment, which coincides), not a response deadline.
location	string (1–160)	no	Physical location.
duration	integer 1–1440	no	Estimated minutes.
tags	string[] (≤ 10)	no	Search labels.
authorizedDomain	hostname	no	Required for an authorised digital test; no protocol or path.
authorizationAttestation	boolean	no	Must be exactly true for an authorised digital test.
authorizationReference	string (8–500)	no	Auditable internal authorisation reference.

Returns

`{ success, mission }`. Creation does not fund or open the mission.

tools/call — arguments for missions_create

{
  "title": "Check the installed shop sign",
  "description": "Take three timestamped photos from the public pavement.",
  "category": "On-site verification",
  "missionType": "PHYSICAL",
  "price": 2500,
  "location": "Paris 2e",
  "executionWindowSeconds": 1800
}

Caveats

There is no MCP funding tool. The draft cannot be opened or notified through this surface.
For AUTHORIZED_DIGITAL_TEST, domain, attestation=true and authorisation reference are mandatory. Third-party protection bypass is outside scope.

Claims and proof#

Claim work, inspect assignments, request valid transitions and submit evidence.

claim_mission#

Session + KYCRole providerPOST/bookings (fallback: /missions/{id}/claim)

Claims a safe, open mission as a verified human provider.

Parameters

Name	Type	Required	What it does
missionId	string (UUID)	yes	Mission to claim.
scheduledAt	string (date-time)	no	Availability in ISO 8601.
notes	string (≤ 1000)	no	Application note.

Returns

`{ success, bookingId, executionExpiresAt, claim }`. Urgent claims must include the backend deadline.

tools/call — arguments for claim_mission

{ "missionId": "00000000-0000-4000-8000-000000000001" }

Caveats

The MCP tool reads KYC state but cannot start KYC onboarding.

claims_list#

Session requiredGET/bookings (fallback: /claims)

Lists claims visible to the signed-in customer or provider.

Parameters

Name	Type	Required	What it does
status	claim status	no	pending, confirmed, paid, in_progress, awaiting_review, completed, cancelled, expired or disputed.
role	"customer" \| "provider"	no	Viewpoint used by the API.
page	integer ≥ 1	no	Page number.
limit	integer 1–100	no	Page size.

Returns

`{ success, claims, count, pagination }`.

tools/call — arguments for claims_list

{ "role": "provider", "status": "in_progress" }

claims_get#

Session requiredGET/bookings/{id} (fallback: /claims/{id})

Reads one visible claim, including its proof and funding state when the API exposes them.

Parameters

Name	Type	Required	What it does
id	string (UUID)	yes	Claim identifier.

Returns

`{ success, claim }`.

tools/call — arguments for claims_get

{ "id": "00000000-0000-4000-8000-000000000002" }

claims_update_status#

Session requiredPUT/bookings/{id}/status (fallback: /claims/{id}/status)

Requests a role-authorised claim transition; the backend remains authoritative.

Parameters

Name	Type	Required	What it does
id	string (UUID)	yes	Claim identifier.
status	"confirmed" \| "in_progress" \| "cancelled"	yes	Requested next state.

Returns

`{ success, claim }`.

tools/call — arguments for claims_update_status

{
  "id": "00000000-0000-4000-8000-000000000002",
  "status": "in_progress"
}

claims_submit_proof#

Session requiredRole providerPOST/bookings/{id}/proof (fallback: /claims/{id}/proof)

Submits text and/or a safe HTTPS evidence URL for work currently in progress.

Parameters

Name	Type	Required	What it does
id	string (UUID)	yes	Claim identifier.
proofText	string (1–4000)	no	Text evidence. At least text or URL is required.
proofUrl	string (URL)	no	HTTPS evidence URL after URL safety checks.

Returns

`{ success, claim }`.

tools/call — arguments for claims_submit_proof

{
  "id": "00000000-0000-4000-8000-000000000002",
  "proofText": "Receipt reference R-2048 and three photos uploaded."
}

Caveats

For urgent work, submit before `executionExpiresAt`; the tool does not extend the window.

Verification#

Read the useful KYC state without exposing Stripe identifiers or onboarding links.

kyc_status#

Session requiredGET/auth/me

Returns only useful KYC and payout-readiness fields from the signed-in profile.

Parameters

None. The input schema is an empty object — {}.

Returns

`{ success, kyc }` with available status and dates; no Stripe id or onboarding URL.

tools/call — arguments for kyc_status

{}

Caveats

Read-only: this tool cannot start, resume or complete verification.