HTTP reference: the REST API for physical tasks

The server is a translator#

Most MCP tools translate to the route shown below. The server also keeps the authentication token in memory, tries compatibility route fallbacks, rejects unsafe digital missions and validates proof URLs. The auth_clear tool is local and makes no HTTP call.

The API is not public either: it listens on http://localhost:3001 by default (API_PORT). No domain, no API version in the path, no rate limit.

Tool to route#

The complete table, in the order the server declares the tools. {id} is substituted with the tool’s identifier parameter.

Authentication#

A JWT carried by the Authorization header. It is issued by POST /auth/register and POST /auth/login, and signed with the API’s JWT_SECRET: change that secret and every token in circulation becomes invalid.

Authorization: Bearer <jwt>
Content-Type: application/json

The identity verification wall#

Three routes go through an extra check that reads the account’s kycStatus and demands the value verified: POST /prestations, POST /bookings and POST /bookings/{id}/pay. An admin account is exempt.

{
  "error": "KYC non validé",
  "kycStatus": "pending",
  "message": "Vous devez compléter la vérification d'identité avant de pouvoir effectuer cette action."
}

Roles#

The role is chosen at registration and no MCP tool changes it. It decides everything else:

• customer — the only role that can publish a listing, accept an application, pay for it and leave a review.
• provider — the only role that can apply to a listing and set up Stripe Connect.
• admin — exempt from both the role check and identity verification.

Application statuses#

An application is created as pending. Any transition not listed below is rejected with a 400, and a transition asked for by the wrong role with a 403. The paid status is not reachable through this route: it is set by the payment.

Moving an application to completed timestamps the end of the task, but does not release the funds: that is POST /bookings/{id}/validate, and that route has no tool.

Amounts and escrow#

• Everything is in cents. price, totalAmount, platformFee and providerAmount are integer counts of cents. The tools’ response messages reformat them in euros for reading; never parse those strings back.
• The fee is frozen at application time. The moment a provider applies, the API computes platformFee from STRIPE_PLATFORM_FEE_PERCENT (10 % by default) and derives providerAmount from it. Editing the listing’s budget afterwards does not recompute applications already filed.
• The payment goes to the platform, not to the provider. That is what escrow means here: the funds are held, then paid out on validation.
• Payment has two possible responses. If the provider has no Stripe Connect account, the API answers demoMode: true and simulates the escrow — no real money moves. Otherwise it returns a Stripe Checkout URL.

Errors#

Every error carries an error field written in French. Validation errors add details, which is the raw output of the validator — in English, and the only place where the API does not speak French.

{
  "error": "Données invalides",
  "details": [
    {
      "code": "too_small",
      "minimum": 10,
      "path": ["description"],
      "message": "String must contain at least 10 character(s)"
    }
  ]
}

On the MCP side, all of this arrives in the same shape: isError: true and a JSON { "success": false, "error": "…" }. The validation details field is lost in translation — only the main message survives.

Routes with no tool#

The API serves more than the MCP server exposes. These routes exist and work; they are simply only reachable over direct HTTP.

• GET /healthLiveness probe. No authentication.
• PUT /auth/meEdit your own profile.
• POST /auth/kyc/startStart identity verification.
• GET /auth/kyc/statusRead the state of the verification.
• GET /prestations/meta/categoriesCategories the API knows about.
• POST /bookings/{id}/validateDouble validation, then escrow release.
• POST /bookings/{id}/disputeOpen a dispute.
• GET /bookings/disputes/listOpen disputes.
• PUT /bookings/disputes/{id}/resolveArbitrate a dispute.
• POST /stripe/webhookSigned Stripe callback. Raw body, not JSON.
• GET /stripe/connect/refreshResume a Stripe onboarding flow.
• POST /chat · GET /chat/configMessaging.