MCP and AI agents
Connect Claude, ChatGPT or your own agent to the Fiuit MCP server to look up times, book and run the business with your API key.
Updated:
Fiuit includes an MCP server (Model Context Protocol) so AI agents use the same engine as the WhatsApp bot: same holds, same validation and same audit trail. The server is a thin client of the API: every tool calls the API with your own key, so MCP never grants more permissions than the key.
The hosted server is https://mcp.fiuit.com/ (https://mcp.fiuit.com/mcp is the same address). To connect Claude or ChatGPT with one button, without copying keys, follow Connect Fiuit to your AI. What follows is for connecting it with an API key or running it yourself.
Partner material
The partner toolset includes partner_courses, partner_league, partner_kit and partner_news: reviewed courses with your progress and score, your league, messages and templates with your referral link, and updates ready to share. All four tools are read-only, accept lang (pt, es or en) and only appear with the partner:read scope.
They work with an API key or OAuth connection. They read the partner of the person who created the key or authorized the connection, while that person remains an active project member. If no courses have been reviewed yet, the list is empty; progress stays in the browser and cannot be read through MCP.
Run the server
You need Python 3.12+ and uv.
cd packages/mcp
uv sync
WAGEND_API_URL=https://api.fiuit.com MCP_PORT=8700 uv run python -m wagend_mcp
# escucha en http://127.0.0.1:8700/ (Streamable HTTP)
Variables:
| Variable | Purpose |
|---|---|
WAGEND_API_URL | API URL (default https://api.fiuit.com) |
MCP_TOOLSETS | Toolsets to expose: booking, admin, tasks, payments, customers, inbox, finance, partner and setup (rarely used configuration: services, resources, schedules, flows, automations, website, store, zones and payment accounts). Default: all nine; without setup the list drops to about 130 tools |
MCP_HOST, MCP_PORT | Where it listens (default 127.0.0.1:8700) |
MCP_ALLOWED_HOSTS | Allowed hosts (DNS rebinding protection) |
Connect a client
Authentication is an API key in the Authorization header. Without a key in a valid format, the server answers 401 before entering the protocol.
With Claude Code:
claude mcp add --transport http wagend http://127.0.0.1:8700/ \
--header "Authorization: Bearer wg_live_xxx"
Or with the JSON configuration of any client that supports HTTP:
{
"mcpServers": {
"wagend": {
"type": "http",
"url": "http://127.0.0.1:8700/",
"headers": { "Authorization": "Bearer wg_live_xxx" }
}
}
}
To try it without an agent: npx @modelcontextprotocol/inspector (Streamable HTTP transport, the same URL and header).
Public MCP for your customers' AI assistants
Besides the business MCP (with a key), Fiuit publishes a keyless MCP for people's AI assistants (ChatGPT, Claude, Gemini and others): https://mcp.fiuit.com/clientes. With it, an assistant can find your business, see what your bot offers and request a booking for a real person.
claude mcp add --transport http fiuit-customers https://mcp.fiuit.com/clientes
| Tool | What it does |
|---|---|
find_business | Searches by exact name or subdomain, or by directory text («padel Uruguaiana»). Up to 10 results per page and 3 pages, in neutral order: distance, a free slot that day and open now. |
list_offer | What the bot offers, with prices already formatted. |
find_slots | Free times for a service. |
quote_order | Quotes a product order: each line with its price and the total, already formatted. It only quotes (it holds or orders nothing); to change the cart, quote again. Only at businesses that have it enabled. |
my_assets | The person's assets (their vehicle), only in a verified chat. It only reads: to save or fix one, the person tells the business through talk_to_business. Only types the business already turned on. Only at businesses that have it enabled. |
my_context | The person's context, only in a verified chat: their first name, what's active (open bookings and orders, plans with what's left, whether there's a pending charge, without the amount) and what they usually book or buy (service, day, part of the day and resource). Use it to greet them by name and suggest repeating the usual once, really looking it up with find_slots or quote_order. Nothing from the team (no notes or tags). Only at businesses that have it enabled. |
request_booking | Holds the time for a few minutes and sends the person a code by WhatsApp (default), Telegram or email. |
confirm_booking | Confirms with the code the person received. Without the code, the time is released on its own. |
talk_to_business | Talks to the business bot, like on WhatsApp. Returns conversation to continue the chat and the reply with amounts and dates already formatted. |
end_conversation | Ends the chat before it expires, if the person asks: anything after starts without their data. |
search_knowledge | Answers questions about your business with what your knowledge base says. |
handoff | Hands the chat to someone on your team when the customer asks. |
request_task | Requests a service without a time slot (an assessment, a quote) for the person, only after they confirmed a code in the chat. |
my_bookings | Shows the person's open bookings and orders, only after they confirmed a code in the chat. |
cancel_booking, reschedule_booking | Ask to cancel or move one of the person's bookings: a new code is sent and only that code makes it happen. |
The assistant never confirms on its own: the code the person receives is always required. Only businesses with a published website and «Accept AI agents» on show up; the directory also requires «Show in the Fiuit directory». Both are on by default and change with update_site (accept_agents, in_directory), through the API (PATCH /v1/site) or by asking Wagy. Products and plans are ordered through the business website. The same routes are in the API without credentials: /v1/public/agents/*.
Talking to the bot (talk_to_business). The same bot as on WhatsApp answers, with your rules: what it sells, stages, handoff to a person, tone and greeting. The chat shows up in the Inbox marked «Via AI» and your team can take it over; if they do, the assistant reads the person's reply. To hold a time the assistant must send the person's name and phone (or email): the «yes» to the summary doesn't confirm, the person receives a code and the booking is made only with confirm_booking. Until the person confirms a code in the chat, requests without a time, cancelling or rescheduling can't be done from an assistant. Each chat uses AI usage from your plan, like any channel. API routes: POST /v1/public/agents/businesses/{business}/conversations and .../conversations/{conversation_id}/messages (POST to send, GET to read, with optional wait).
Verified session. When the person confirms the code of a booking requested in the chat, the chat isn't cut off: it continues for 24 hours on their record (verified_until). The bot greets them by name and knows their bookings, orders and plans (debt, only the total). Booking or ordering again with nothing to pay needs no other code; cancelling, rescheduling and paying need a new one each time, sent to the contact the person confirmed and used in confirm_booking. Chatting doesn't renew the 24 hours: only another confirmed code does. After that, or in a new chat, the assistant starts without the person's data; with end_conversation (DELETE .../conversations/{conversation_id}) the person ends it earlier.
Tools
The tasks and payments tools only appear in the list if the key has the scope they need (a key without payment permissions neither sees nor can use them). For the rest, each one only works if the key has the scope; otherwise it returns the API's 403 error. Writes are audited with actor mcp.
Every tool carries its MCP annotations: readOnlyHint (only reads), destructiveHint (cancels, deletes, voids or refunds), idempotentHint and openWorldHint (messages a customer, charges through a provider or publishes on the internet). That way ChatGPT and Claude know what they can use without asking for confirmation. On connect, the server introduces itself as Fiuit and tells the model where to start (list_today, list_tasks, list_conversations).
Bookings (booking): for assistants that book on behalf of a customer.
| Tool | Scope | Does |
|---|---|---|
list_services | config:read | Services with duration and price |
find_slots | slots:read | Available times for a service between two dates or for one opening day (day, includes its night after 00:00) |
hold_slot | bookings:write | 10-minute hold |
confirm_booking | bookings:write | Confirms a hold with the customer's data |
cancel_booking | bookings:write | Cancels a booking. Requires confirm=true: without it, it only shows the booking and does not cancel |
reschedule_booking | bookings:write | Moves an existing booking to another time |
get_booking | bookings:read | Booking detail |
Administration (admin): so the Owner can run the business from their AI assistant.
| Tool | Scope | Does |
|---|---|---|
list_resources | config:read | Team, rooms, machines and teams, with their icon and color if set |
list_today | bookings:read | The day's bookings, plus unfinished multi-day tasks running through it |
block_time | config:write and bookings:read | Closes whole days of a resource (max. 31). It does not cancel existing bookings: it returns them for a person to decide |
list_service_pauses | config:read | Lists a service's pauses by date |
pause_service | config:write | Pauses a service from one date to another (inclusive) without blocking the resources that provide it: their other services keep being offered |
resume_service | config:write | Reopens a service paused over a date range |
create_service, update_service | config:write | Creates or changes a service, with its booking form |
update_schedule | config:write | Changes the weekly schedule or the time zone |
list_booking_series, get_booking_series | bookings:read | Recurring bookings («every Tuesday at 8 pm») and their dates: with a task, skipped or in conflict |
create_booking_series | bookings:write | Creates a recurring booking: same service and customer every 1 to 4 weeks, on one or more days, until a date (up to one year) or a number of times (up to 52). Each date is a normal task charged on that day. Without confirm=true it returns the preview (dates for the next 8 weeks and which ones conflict); conflicting dates are skipped with skip_dates or skip_conflicts |
update_booking_series, cancel_booking_series | bookings:write | Edits or cancels the whole series or, with from_date, «this and following». Future dates not started or paid are rebuilt (or cancelled without notice); past or paid ones are untouched. «Only this one» is reschedule_booking or cancel_booking on that task. Require confirm=true |
get_coverage | config:read | Business coverage: active zones and what happens to anything outside (out_of_coverage) |
set_coverage | config:write | Chooses what to do out of coverage (also for a delivery that doesn't reach that zone): out_of_coverage = take (take and notify) or reject (do not take) |
get_stats | bookings:read | Bookings, occupancy and no-shows per resource; people only by default, pass kind=all for courts or places |
get_control_summary | bookings:read (conversations with messages:read, amounts with finance:analyze) | "How are we doing?": attention now, tasks in progress by stage, numbers for the period (sold, collected, outstanding) and saturation by weekday and hour. Optional filters date_from/date_to (today by default), service_id and resource_id. Read only; what the key cannot see comes back null Stages are counted by service and the task’s actual status. Collected uses the payment date, including work from another day; payments under review are current pending payments, including undated tasks. Each response preserves a single point-in-time view of the project. |
list_flows, get_flow, list_flow_versions, get_flow_version | config:read | Flows (the path of stages that services pick), their services, exits and requirements; version history. get_flow also returns procedure: the flow as text per language, regenerated from the current version |
validate_flow | settings:write | Validates without writing; returns impact with the tasks to move and shared_with |
simulate_flow | settings:write | Entry dry run of an intent flow: where each entry phrase lands (the given one, unsaved) and whether it clashes; uses the project's AI for phrases the keywords don't decide |
copy_flow | settings:write | Copies a flow (system flows too) into your own independent one with a new name, after confirmation; no service changes |
customize_flow | settings:write | Edits a system flow in the business's own copy (created the first time, taking over the services that used the base), after confirmation |
restore_flow | settings:write | "Back to original" from the own copy: services return to the system flow and open tasks finish with the version they had |
delete_flow | settings:write | Deletes a flow with no use and no tasks, after confirmation |
create_flow, update_flow | settings:write | Create a flow or publish a version after preview and confirmation; publishing moves the tasks of every service on the flow. Each stage can carry bot_offers (what the bot offers while the task is there; an unknown item returns 422 bot_offer_unknown_item) |
upload_stage_image | settings:write | Stores the «Mark on image» background image and returns its id, published in sketch_background with update_flow |
revert_flow | config:read + settings:write | Creates another version from the selected one; retains history |
get_flow_examples, get_base_states, get_flow_message_catalog | config:read | Flow examples to copy, fixed engine states and the protected variables with the default text of each stage's customer message |
get_flow_usage | bookings:read | How much each flow is used: without flow_id, tasks that entered in the last 7 days against the previous 7; with flow_id, entered and completed per day and open tasks per stage with their average wait (bottleneck, the stage that holds things up most). Read-only. |
get_business_traits, set_business_traits | config:read / settings:write | Business traits (from the closed catalog: «place calendar», «with spaces», «sells products»…) and the free business label, informational only. Saving replaces the list and label after confirmation; omitting business_label or sending null clears the label. To keep it, read get_business_traits and send the label when saving; it does not change booking rules or the calendar |
get_item_performance | bookings:read (service, product); prepaid:read (plan) | Performance of a service, product or package/club in quantities (completed, units, sold, active today) per day, week or month, with the previous period. With a key these are the business totals (scope: business). Never returns amounts: they live in Finance. |
Tasks (tasks): tasks with and without a time, the "to schedule" ones and the queue.
| Tool | Scope | Does |
|---|---|---|
list_tasks | bookings:read (and payments:read_balance if you ask for the balance) | Lists tasks by status, to schedule (scheduling_state=pending), unassigned (unassigned=true), late (late=true), queue, origin (origin=conversation is the chat order) and, optionally, with their balance and a payment-status filter on the page. With flow_id it keeps one flow's tasks and with group_by (stage, status, resource, priority, type, tag, day, zone, customer or flow) it adds counts per group; with group_by=stage and flow_id it returns every stage of the flow in order, like the columns of the panel's Board; statuses and resource_ids filter by “any of” those statuses or resources before paging; group_by=tag exposes the free text of tags and requires include_sensitive=true with customers:read; match applies the criteria of a Work view: several statuses, a date with its field and a relative range (today, last month, last N days…) resolved in the project's time zone, and “or” groups (any_of) |
create_task | bookings:write | Creates a task with a time, a queue task, or a to-schedule task with no time (schedule_later=true); with the flow_id of an intent flow, a task with no service (complaint, quote), no time and no amount; with internal=true, a team task with no customer (for a service with no price) |
schedule_task | bookings:write | Gives a time to a task without one, or changes the one it has; the API checks availability |
assign_task | bookings:write | Assigns people or resources to a task |
list_task_lines | bookings:read | The task's items, its two blocks (services and products) and the margin (only with the costs permission) |
add_task_line | bookings:write | Adds a catalog service or product, or a free-form item with a price and optional cost; raises the amount due, requires confirm=true |
edit_task_line | bookings:write | Corrects price (also of a catalog item, only on that task), quantity and cost; on a free-form item, also the name; requires confirm=true |
remove_task_line | bookings:write | Removes an item and lowers the amount due (never below what was already paid); requires confirm=true |
list_task_checklist | bookings:read | The task checklist: its to-do points, which are checked and who checked them. Internal: the customer never sees it |
add_task_checklist_item | bookings:write | Adds a point to the checklist ("check the brakes"); doesn't touch the amount due or what the customer sees. Undone by removing it |
change_task_checklist_item | bookings:write | Checks or unchecks a point (done) or renames it (name); expected_version avoids overwriting someone else |
remove_task_checklist_item | bookings:write | Removes a checklist point; requires confirm=true |
preview_task_discount | payments:adjust | Shows the total with a discount, without saving anything |
apply_task_discount | payments:adjust | Applies or changes the task discount, as an amount or percentage (value in basis points); staff up to 10%; requires confirm=true |
remove_task_discount | payments:adjust | Removes the discount so the total returns to list; requires confirm=true |
preview_plan_discount | prepaid:sell | Shows the installments with a special price, for a plan to sell or already sold, without saving anything |
apply_plan_discount | prepaid:sell | Special price on a sold plan, from the next installment; manual billing only; requires confirm=true |
remove_plan_discount | prepaid:sell | Removes the special price: later installments return to the plan price; requires confirm=true |
accept_work_item_offer | bookings:write | Accepts an offer («Offer…») from the task's current stage (listed in offers on the task detail): a product is added to that task at the catalog price and raises the amount due; a service creates another, independent task for the same customer. Requires confirm=true; never takes a price |
Item tools keep identifiers, quantities and amounts in the minimal response. To see names and units, use include_sensitive=true with the listed read scope. Changing the total of an accepted quote may send a revision to the customer, so these tools require confirmation.
Payments (payments): manual payments and balances. Balances are always computed by the API; the MCP never adds or subtracts.
| Tool | Scope | Does |
|---|---|---|
record_payment | payments:record | Records a manual payment (cash, card, transfer, Pix, Mercado Pago or other; the method is required and stays in the audit log), optionally split across tasks |
void_payment | payments:void | Voids a payment, with a mandatory reason |
expense_categories | expenses:read | The project's 11 expense categories (fixed names, kind and whether it is hidden). «Staff commissions» is a calculated line: it is not entered by hand |
expense_list | expenses:read | Recorded expenses by period, category or resource; the API adds up total_minor (approved only: without pending, rejected, voided or test ones; status filters by state). With tag_id, only the expenses with that tag: its total does not add up with another tag's, because an expense can have several. With no resource, the expense is «General» |
expense_record | expenses:record | Records an expense in the project's currency (local date, never in the future). Requires confirm=true; if the amount is large for the business (from twice the monthly price of its plan), also confirm_high_amount=true, a second confirmation from the person. Accepts tags (tags by name; new ones are created) and, without category_id, uses the category remembered by the first tag that has one (if none, 409 expense.category_required) |
expense_void | expenses:void | Voids an expense with a reason; an expense is never deleted. Requires confirm=true |
income_record | payments:record | Records income that did not go through a task («+ Income»): a quick sale with its collection. What was sold is a category (product_sale, rental, tip, other_income), a service or a product (income_options lists them). collection: paid (already paid, with method), mercadopago (still to collect; the link is created separately with create_payment_link, always with the person's OK) or debt (requires customer_id). Without a customer it goes to «Walk-in sale». Without confirm=true it returns the preview without writing |
income_void | payments:void | Voids income with a reason: its receipts are voided and it stops counting. A Mercado Pago payment already credited is refunded, not voided |
expense_tags | expenses:read | The project's expense tags («motorbike», «downtown store»), most used first, with the category each one remembers and how many expenses have it |
expense_tag_rename | expenses:record | Renames a tag; if another already has that name, merge them with expense_tag_merge. Requires confirm=true |
expense_tag_merge | expenses:record | Merges two tags: the expenses of one move to the one that stays and the other is deleted. Cannot be undone. Requires confirm=true |
expense_tag_delete | expenses:record | Deletes a tag and removes it from its expenses; the expenses are not touched. Requires confirm=true |
expense_pending | expenses:approve | How many expenses recorded by the team are waiting for approval and how much they add up to (without test ones) |
expense_history | expenses:read | History of an expense: who, when and what changed (before and after). There is no month close |
expense_get | expenses:read | One expense: amount, category, date, status (approved, pending, rejected or voided), receipt and review. It is the detail of an expense in Transactions |
expense_approve | expenses:approve | Approves a pending team expense: from now on it counts. Nobody approves what they recorded. Requires confirm=true |
expense_reject | expenses:approve | Rejects a pending expense with a reason; it stays rejected and does not count. Requires confirm=true |
recurring_expense_list | expenses:read | Expenses that repeat (rent, fixed salaries), with their next date and whether they are active, paused or ended |
recurring_expense_create | expenses:record | Creates an expense that repeats every week or every month; Fiuit records it on each date, only once. Requires confirm=true |
recurring_expense_update | expenses:record | Changes the amount or the day, pauses or resumes it, or ends it, from now on. Requires confirm=true |
recurring_expense_skip | expenses:record | Skips the next date without recording the expense. Requires confirm=true |
apply_refund_due_to_account | payments:adjust | “Use for another debt”: a late payment kept apart as “to refund” (refund_due) moves to the customer's balance and covers their oldest debts. Requires confirm=true; the API refuses it while a Mercado Pago claim is open |
refund_payment | payments:refund | Refunds a Mercado Pago charge to the customer (full or partial), with a reason; without an amount, everything left. Requires confirm=true with the preview key: repeating it never refunds twice and never more than what was collected. Returns succeeded, failed (Mercado Pago rejected it), pending (retried automatically, checking Mercado Pago first) or review (Mercado Pago did not confirm it: it is not requested again, the amount stays reserved and Owner/Manager get an alert). Owner/Manager only |
get_payment_refunds | payments:refund | A charge's refunds: refunded, in progress and what can still be refunded (or why not) |
charge_fiscal_get | payments:fiscal | Tax marker of a charge and the business issuer's documents, if any. Fiuit never issues tax documents. Owner/Manager only |
charge_fiscal_mark | payments:fiscal | Marks whether a charge needs a tax document: not required, pending or issued outside Fiuit (with number and date). Only charges with money received. Requires confirm=true. Owner/Manager only |
charge_fiscal_issue | payments:fiscal | Requests the tax invoice (Brazilian NFS-e) with Fiuit Fiscal, or retries it if it failed, never issuing two invoices per charge. Only projects whose tax country is Brazil (otherwise fiscal.country_not_supported) and BRL charges with money received. Requires confirm=true. Owner/Manager only. Activating Fiuit Fiscal and marking an invoice cancelled on the city hall portal are done in the panel |
get_task_balance | payments:read_balance | A task's balance and, if you want, its payment history |
get_customer_account | customer_balance:read (and customer_account:read for the detail) | The customer's account: balance, on-account payments and debts; with include_movements=true, a per-task breakdown and payments |
get_commissions | commissions:read | Team commissions calculated by the API on what was collected: with day, the day per team member (collected by method, tips, commission, adjustments and cash box); without day, the report between start and end. refund_amount_unavailable lists tasks with a partial refund whose amount was not reported; they still count in full. Read only |
get_commission_settlements | commissions:read | Commission settlements for a period: frozen amounts, automatic adjustments already frozen from other periods and what is still pending for the next open period. Read only |
settle_commissions | commissions:settle | «Settle commissions»: freezes one team member's period in an entry that is never rewritten, with a reason. A later change (void, refund or rule) becomes an automatic adjustment on the first unsettled day. Settling the same period again returns the same entry. Requires confirm=true |
finance_overview | finance:analyze | Finance summary calculated by the API: In, Out and Left done for 2 previous periods and the current one, and what is still to come for the current and next period, confirmed (already received, fixed expenses) or expected (unpaid balance, estimated team commission, expenses awaiting approval). Only dated things. |
finance_result | finance:analyze | Result calculated by the API, with basis cash (cash flow, default) or accrual (income statement: work done in the period, paid or not, with «to collect» shown apart). On cash basis: In (collected minus refunded), Out (approved expenses, team commissions and reported payment fees) and Left, with margin and the previous period, by period, resource, service or category. Expenses with no resource or service stay as «General», not split. missing_expenses warns that money came in and no expenses were recorded. Read only |
finance_result_lines | finance:analyze | What makes up a Result figure: the payments, refunds, payment fees, team commissions and approved expenses it adds up, with signed amount, day, category, resource, service, person and customer. Open a row (row, «General» with general), In or Out (side) or one type (kind), or a cell of the year's income statement (dre); total_minor is the opened figure even if the list is cut at limit. Read only |
finance_year | finance:analyze | The year's income statement, month by month: gross revenue, refunds, taxes, direct costs, gross profit, operating expenses by category and each month's result (surplus or shortfall), cash or accrual (basis). The year total matches finance_result. Read only |
export_finance_result_csv | finance:analyze and finance:export | Exports the period's Result as a CSV for the accountant: one movement per row (payment, refund, payment fee, team commission or expense) with category, resource, service, person, customer, readable amount and signed minor-unit amount; the sum is what was left. Same separator and decimals as Excel in the currency's country. Up to 50,000 movements. The 8-sheet Excel file is downloaded through the REST API. It is logged |
create_finance_package · list_finance_packages · get_finance_package | finance:analyze and finance:export | Requests the period's accountant package (8-sheet spreadsheet and one-page PDF summary, with the same numbers as the Result) and checks its status. A small one comes back ready with a download link valid for 5 minutes; a large one is put together separately. With an API key it does not include receipt photos: those are only downloaded from the panel. The file expires after 48 hours. It is logged |
| list_prepaid_plans | prepaid:read | Packages (N sessions with an expiry), clubs (N per month) and memberships (fixed monthly price, no usage count) in the catalog, with price, per-unit value and per-day/time-band quota |
| get_customer_plans | prepaid:read | A customer's packages, clubs and memberships: units left, reserved, expiry and fee due. Each period is an installment, a task that gets charged (period.booking_id); open_fees lists the installments to collect (task, due date and amount) and next_due_at the next due date. active = up to date, past_due = an installment past due and unpaid. Paying an installment = collecting its task (record_payment with that booking_id); there is no separate tool |
| sell_prepaid_plan | prepaid:sell and payments:record | Sells a plan paid in person (cash, card, transfer, Pix, Mercado Pago or other; the method stays in the audit log). Unpaid (unpaid=true), the first installment stays To collect and is charged like any task (record_payment with its booking_id), as are the following ones. A club or membership billed by card is sold with the customer's email (payer_email), only when list_prepaid_plans returns card_billing_available=true: it waits for authorization and returns checkout_url, the Mercado Pago link where the customer authorizes their card (prepaid:sell is enough for this). If the customer already has that plan by card in force, it returns 409 prepaid_card_sale_exists with that sale's subscription_id: no second sale. Requires confirm=true |
| cancel_prepaid_plan | prepaid:sell (refund: also payments:void and payments:record) | Cancels: no more installments are created and existing ones don't change (an unpaid one is still owed; the response lists them in open_fees); frees the sessions of future tasks. With refund=true returns what was not used in the current period's installment of a plan paid in person (expired sessions are lost). Requires confirm=true |
| extend_prepaid_plan | prepaid:sell | Manually extends the expiry of a package or membership (or reopens an expired package). Unused sessions are lost at expiry. Requires confirm=true |
| remove_task_plan | prepaid:sell | Removes the plan from a task: frees the session and the task goes back to its normal price. Needed before changing its customer or service. Requires confirm=true |
cancel_booking also requires confirm=true: without it, it returns the booking and confirmation_required and cancels nothing. Show the booking to the person before repeating the call with confirm=true.
record_payment and void_payment move money: they require confirm=true and, without it, do not execute the monetary operation (the protocol may query GET /me). Always pass idempotency_key to retry without charging twice; amount limits and duplicate detection are the API's. received_by is the membership of whoever received the money: it is required with an API key.
expense_record, expense_void, income_record, income_void, expense_approve, expense_reject and the recurring_expense_* tools that write are money too: they require confirm=true and idempotency_key. Renaming, merging and deleting tags do not move money, but they also require confirm=true (no idempotency_key). To correct an expense from an agent, void it and record it again; editing with history is done in the panel. The photo or PDF of an expense receipt does not go through MCP or an API key: it is attached with a panel session.
Preparation without confirm returns idempotency_key; confirmation requires that key or an agent-supplied key (1-128 characters). Reuse the same key, destination and payload for every retry, including lost responses. A new operation requires a new key, even for an identical payment.
By default, list_tasks omits contacts, exact addresses, coordinates, notes and forms. include_sensitive=true requests full details and also requires customers:read. Movements in get_customer_account and charge history in get_task_balance omit receiver names, notes and reasons; the same opt-in also requires payments:read. Keys with mode=test only see read tools.
Writes to configuration, tasks and payments require confirm=true. Without it, the tool does not execute the write (it may read data for the preview): it returns confirmation_required with what it would send, so the agent can show it to a person and repeat with the confirmation.
OAuth connection: permissions and tools that do not appear
When the owner connects Claude or ChatGPT (see Connect your AI), the AI uses a token with the permissions they ticked on the permissions page. What differs from an API key:
- Several projects in one connection. An API key belongs to one project; an OAuth connection can cover several.
list_projectslists them (id, name, slug, role and permissions in each) and every tool takes an optionalprojectwith that id or slug, which the MCP sends as theX-Wagend-Projectheader. With a single project it is not needed. With several and noproject, the tool answers400 project_requiredwith the list so the AI can ask; a project outside the connection gives403 project_not_in_connection, whether it exists or not. Permissions and role are checked on every call, in the chosen project. With an API key,list_projectsreturns its only project. - The tool list is trimmed. Only the tools the token can use appear.
get_task_balanceandlist_taskswithinclude_balance=trueneedpayments:read_balance(the «See money» permission): without it, the tool does not appear or answers403 insufficient_scope. To add it, connect again ticking «See money» (only the owner can grant it)./.well-known/oauth-protected-resourcepublishesscopes_supportedso the client knows what to ask for. - Editing the products of an order (
replace_task_items) needs onlybookings:write; seeing money is not required. The amount due is recalculated and the API does not let the order drop below what was already collected (409order_below_paid). - Cash payments:
record_paymentwithmethod: "cash"and thepayments:recordpermission («Record payments and send payment links»). Manually adjusting the amount due (payments:adjust) is not granted through OAuth: do it from the panel. - Zone of an address:
match_zoneneeds coordinates (latandlng), neighborhood, city or postal code; a free-text address alone returnszone: null. With coordinates the drawn area wins, and the zone of a customer's saved address uses the same rule. - Customers:
list_customerswithoutinclude_sensitive=truereturns onlyidandlocale; to pick a customer by name you needinclude_sensitive=true(andcustomers:read). - Customer habits:
get_customer_summaryreturnshabits(how often they come, day and slot, service, expected date and status by their rhythm:on_track,due,late,at_risk,lost) and, for candidates,fixed_proposalto set up the fixed slot withcreate_booking_series.list_customersfilters byhabit(one status:on_track,due,late,at_risk,lost; orfixed_candidate); «who did I lose this month?» ishabit=lostwithlost_sincethe first day of the month. - Timeline:
customer.updatedandbooking.updatedcarryfieldsorchangedwith the names of the edited fields, never their values.
Partner panel (partner)
If you are a Fiuit partner, your AI can read your portfolio with the same rules as your panel. All of them are read-only (readOnlyHint) and need the partner:read scope: over OAuth, the "View your partner portfolio" permission, which the permissions page only offers to a partner. Without that scope, they are not listed.
| Tool | Scope | Does |
|---|---|---|
partner_today | partner:read | The next action, portfolio progress and alerts |
partner_clients | partner:read | Your clients with plan, last use, counts and health light; sort, cursor and quick filter |
partner_client_detail | partner:read | One client and its milestones. A project outside your portfolio returns 404 client_not_found |
partner_activity | partner:read | Your clients' milestones, newest first |
The partner is whoever issued the credential (created the key or authorized the connection), never a field of the request. A key with the scope issued by someone else returns 403 partner_required; if the partner is deactivated or leaves the credential's project, it stops working on the next call. Counts and statuses only: neither the businesses' content nor their amounts. Creating a project for a client stays panel-only.
Example requests
- "Book a haircut with Juan tomorrow morning, under the name Carlos."
- "Block the laser machine next Monday for maintenance and tell me which bookings are affected."
- "How many no-shows did we have this month?"
- "Show me the unassigned tasks and schedule them tomorrow at 10."
- "Record a cash payment of 50,000 from Ana for her last task and tell me the balance."
Docs for LLMs
/llms.txtlists every documentation page./llms-full.txtcontains the full documentation in Markdown.
Flows: flow tools require flow_id (list_flows); create_service and update_service accept flow_id to pick a service's flow. update_flow validates before previewing (impact and shared_with, the services sharing the flow, all of which change); confirm=true creates a version. System flows are not edited directly: customize_flow gives the own copy (edited with update_flow) and restore_flow goes back to the original; or copy_flow (or create_flow) and assign it. delete_flow deletes a flow with no use and no tasks. revert_flow creates another version (read config:read and write settings:write). validate_flow, get_flow_examples and get_base_states cover configuration.
“How the task looks”: update_flow with task_view picks what goes on top of the task (main: auto, when, destination, order or none), the “Items” switch (items: off, the task doesn't offer “+ Add item”; items already added stay visible). chips (customer and payment) no longer has any effect: it is accepted for compatibility and ignored. Whatever you don't send stays the same and clear_task_view=true goes back to automatic. Without confirm it shows task_view_diff with the before and after; it doesn't create a version or move tasks and also works on a system flow. Each task carries the current setting in task_view.
MCP adds get_work_item_next_steps, move_work_item_stage and use_work_item_tool. Writes require confirm=true and Idempotency-Key. complete_task is removed. Electronic charge remains pending F4-29. get_work_item_stage_history (scope bookings:read) reads the immutable stage history (up to 100). Scopes: reading bookings:read; moving and using tools bookings:write (plus payments:record when charging); editing service stages settings:write. A 403 (permission or scope), 409 (stage_conflict, already_claimed) or 422 (stage_requirements_missing) reaches the agent unchanged; retrying with the same idempotency_key and body returns the same result without duplicating. Wagy explains the current capability and the panel includes Next step and the stage editor. Enabled effects are queued through the outbox; this does not prove delivery to a customer.
Fill in from photo (FIU-672): fill_stage_from_photo reads a task photo and suggests the stage's empty text or number fields. It saves nothing: the values are confirmed with move_work_item_stage. Doubtful values don't come back and saved values aren't overwritten. Same permissions as completing the stage. Each reading counts against the plan's AI; without quota it answers ai_limit_reached.
create_service and update_service accept price_per_time («Price by time», with confirm=true): when a task of that service changes duration, its amount is recalculated proportionally, except with a payment or deposit recorded or an amount adjusted by hand.
create_service and update_service accept duration_options (the durations the customer picks when booking, for example 1 h, 1 h 30 and 2 h: [{"minutes": 90, "price_cents": 17000000}], up to 6; without a price, prorated; with confirm=true); clear_duration_options removes them. find_slots and hold_slot accept duration_min (one of those durations): the booking is a single task with that duration and its price; any other duration returns 422 duration_not_offered.
create_service and update_service accept location_mode (local, customer_address, customer_choice or remote: remote, no address) and meeting_url, the http(s) meeting link of a remote service that the business adds (Fiuit does not generate it); clear_meeting_url removes it and switching to another mode deletes it. The bot and reminders share that link instead of an address.
update_service accepts title_template: the pieces of the title of that service's tasks (1 to 3: customer, order, address, number or field:<key> for a form or stage field), joined by « · »; clear_title_template goes back to «Customer · Order». update_task_metadata accepts title to write a task title by hand (it stays fixed) or null to make it automatic again. Both are writes: they show the proposal with the change and apply with confirm=true.
update_service also changes lead time and cancellation: lead_time_min (minimum minutes before the booking; 0 = no minimum), max_advance_days (how many days ahead customers can book; clear_max_advance_days = no limit) and cancel_policy ({"deposit_refund_hours": N}, 1 to 2160: cancelling at least N hours ahead refunds the deposit paid through Mercado Pago; also requires payments:refund; clear_cancel_policy removes it). create_service and update_service accept accepts_chat_requests (customers request it by chat without picking a time) and bot_offered (false: the bot does not offer it). If a service form repeats keys of its flow items, the 422 invalid_service_stages error names each repeated key.
create_service and update_service accept booking_payment («Charge when booking»: none, deposit or total) and deposit_cents, with confirm=true. With total the appointment charges the task's full value through the deposit flow; deposit without a deposit returns 422. Values are validated before calling the API.
They also accept full_day («Full day»): drop off and pick up, and the customer picks the day, not the time. There is a single slot per day, from opening to closing; with a place that serves 3 at a time, 3 fit per day. It is not valid for a service that assigns a person (a team with a staff resource): it returns 422 service_full_day_invalid.
list_tasks(date_from=…, date_to=…, include_carried=true) adds the started tasks that are past their end and still take their place on those dates (full-day service or no person, up to 7 days after the end): they come with carried_over=true and carried_until. It is the same rule availability uses, with the bookings:read scope.
By default (fees=due), list_tasks shows only club and membership fees that are overdue or due within the plan's notice days, like Today and Work: it leaves out paid and waived fees and those charged to a card while the charge is on track. fees=all returns them all (for example, to see a customer's fee history).
create_service and update_service accept chat_payment («Chat payment», with confirm=true): mode (on_delivery|ask|link), prepare (anyway|after_payment) unpaid (keep|cancel) and remind (boolean: a single reminder to the customer before the link expires); it carries no amounts, the link is for the task balance that Fiuit calculates and requires Mercado Pago to be ready.
update_service accepts payment_requirement: required|optional|off: it previews the change and uses the same catalog PATCH with confirm=true (config:write). Changing the rule creates an audited version; the executor applies the current service policy to completed destinations. Explicit payments_enabled=false does not require collection resolution or erase balances (changed from F3-177).
Mercado Pago
Brazil and Argentina connect only with OAuth. Chile, Uruguay, Colombia, Mexico and Peru connect only with a token in Payments, with no Fiuit platform fee. Paraguay does not offer Mercado Pago. Existing accounts are preserved.
With a production account and a service requiring a deposit, BRL/ARS use a payment link expiring before the temporary booking. In Brazil, Pix is paid inside Mercado Pago. The portal shows the link and chat sends it through the available conversation.
The booking awaits its deposit until verified payment. Applied prepayment covers or reduces the deposit. Late payments require team review: they never automatically reconfirm or refund.
A rejected or cancelled payment attempt allows another checkout attempt. If a late payment leaves unapplied money under review, the pending booking expires and releases the slot; the receipt and alert remain. Reconciliation detects additional payments even when they arrive together in Mercado Pago search.
A late, refunded or charged-back payment without applied coverage retains its receipt and review when the slot is released. A locally cancelled snapshot does not prove absence of money: a final query is required. The 24-hour credential-loss grace only releases bookings without applied coverage or unverified replaced links.
MP availability includes country (collection country based on the business currency) even without an account; Pix only for BR. No new tools, scopes or refund actions.
Before expiring a booking, the worker reconciles every electronic link awaiting verification, including links replaced and cancelled after a price change, even when their retry is deferred. Failed queries or lost access to a replaced link retain the slot. Already verified receipts retain their financial state.
A timely payment through the old link is applied even when partial: it reduces the outstanding deposit and creates a link for the difference. The booking remains pending and retains its slot; the difference link keeps its original deadline and never extends past two hours before the appointment. Once the deadline is exhausted, the booking stays under review without further links or customer notices; Owner/Manager receives one notice when the partial payment is first retained. Confirmation requires full coverage. Later credential loss does not remove applied coverage. The team must finish collecting or resolve the booking; there is no automatic refund.
Checkout Pro receives only known contact and description data. The card statement descriptor uses ASCII letters and digits, without accents or symbols, up to 13 characters. Returns open the customer’s private portal through the existing link; without an active link or after revocation, returns go to /payment-return, a neutral page with no customer data. Returns never create or revoke portals. Its token stays in the fragment and never confirms payment. The receiver requires public HTTPS and rejects .test, .example, .invalid and .localhost. Tests explicitly enable reserved test domains; production does not.
An ambiguous creation POST releases the slot after seven days of successful empty searches, with a business notice and audit. An error, observed payment or lost credentials resets the window. Owner/Manager can confirm “Release the slot” next to the review: audited cancellation preserves recorded money and does not refund it. Requires tasks:work and payments:accounts_configure in the panel; no tool or API key uses this reserved reason.
F4-25: get_mercadopago_account (payments:read) also returns workspace_currency, mismatch (currency or country when the account collects in another currency or country than the project: no links are created), methods (link, Pix, QR and card with available and a reason when unavailable; QR and card do not exist yet) and deposit_hold_minutes. list_mercadopago_charges (payments:read, read-only) lists the latest Mercado Pago payments with status, amount, purpose and task, without payer data or link. The account is connected and each service's deposit is edited in Finance → Charges.
F4-23: get_mercadopago_account adds the point method (Point Smart terminal; reason terminal_required when no terminal is linked) and account.point_terminal_id. Linking the terminal and «Charge with Point» are panel-only: there is no MCP tool (the operations do not accept API keys).
F4-20: create_payment_link (payments:link) creates the Mercado Pago link for a task balance («Charge»); without amount_minor, the API calculates the amount. Without confirm it returns a preview with idempotency_key; confirm=true requires that key. deliver="conversation" also sends it in the customer’s conversation. An open link for the same amount is reused; with another amount open it answers 409 payment.link_pending.
F4-92: «Charge a part». create_payment_link accepts an optional amount_minor (integer in minor units, the one a person gave): it creates a separate link for that part, alongside other open parts. Open charges never add up to more than the balance: if it does not fit, it answers 422 payment_part_exceeds_balance with remaining_minor (what is left to cover) and open_minor. Retrying with the same idempotency_key returns the same part; another key is another part even for the same amount. Without an amount, the link charges what is left without a part. cancel_payment_charge (payments:link, confirm=true) voids an open link, either a part or the balance link (QR and Point are voided only from the panel); a paid one answers 409 payment.charge_not_open. The get_task_balance history with include_charges=true marks each part with part=true. QR and Point with an amount are panel-only.
Feedback after the service
get_feedback(kind, identifier) (bookings:read): booking, service, customer, resource; 0–100. get_feedback_settings (config:read).
What the bot sells: bot_offer (config:read) returns what the bot offers in chat today (enabled kinds, services, products of each order mode, plans and the «see all or sign up» link). stages lists the flow stages that narrow that list; with flow_id and stage together it returns what a customer whose task is at that stage would see. list_services and search_products include bot_offered per item: when off, the bot never names or sells it. Item links: create_service and update_service accept offer_url (clear_offer_url removes it) and save_product takes it in the product; https, up to 500 characters. When set, the bot shows it next to the item; otherwise it uses the bot link. bot_offer returns it on every service, product and plan. search_products accepts stock (out, low, in), missing (photo, price, category; repeatable), variant (size or color) and sort (name, price_asc, price_desc, stock_asc, best_selling, recent); q also searches by SKU. The cursor is only valid with the same sort and filters.
Search your store: get_store_search shows the live product search in your online store (Tiendanube, WooCommerce, Shopify, Make, n8n or your own URL): the template, the search URL with {q}, the field mapping, the chat-order service the products go into, how many results the bot shows and whether it is on; for credentials it only gives their names. list_store_search_presets lists the ready-made templates. save_store_search creates or edits it and disable_store_search turns it off: both show before and after without writing and only change with confirm=true. Credentials go in headers, are stored encrypted and are never returned. test_store_search runs the same search as the bot and shows the products with their price. All of them need products:write.
Bot service: bot_tree (config:read) returns the bot's service tree: the branches (services, products, subscriptions, own flows, questions, my appointments and talk to a person) with whether they are paused, whether they can be paused and which task and flow each leads to. Pausing services, products or subscriptions is the sells field of “What the bot sells”. Branches come in the order the bot offers them, with the root flow_id, its greeting (greeting) and the saved order (order): update_flow on that flow_id with order or greeting changes them (config:write, the same permission as “What the bot sells”). A paused own branch can be ordered too and keeps its place. The root cannot be deactivated or duplicated.
Conversation path: bot_tree_funnel (config:read) tells, per branch of the bot service tree and over the last days (days, 7 by default), how many conversations created a task, were answered, went to a person or dropped off, and at which step; bot_conversation_path shows the path a conversation took and where it stopped. Neither includes what the customer wrote.
Your website: get_site (config:read) shows «Customer care → Website»: template (booking, catalog or showcase), the optional sections ticked (gallery, team and resources, reviews, plans), the hero and «About us» texts, the subdomain (business.fiuit.app) and whether it is published. update_site changes those fields and publish_site / unpublish_site turn it on or off (config:write); all three show before and after without writing and only change with confirm=true. The website starts off. What it shows from the catalog is exactly what the bot offers (bot_offer), and its FAQ are the bot's. The subdomain is 3 to 40 lowercase letters, digits and hyphens, never reserved or taken; changing it on a published website turns the old link off (there is no redirect) and requires confirm_link_break: true inside changes; without it the API answers 409 and nothing changes. If Fiuit revokes a website, it cannot be published again until it is restored. «Made with Fiuit» shows in the website footer: on a paid plan it is removed with made_with_fiuit: false (can_hide_made_with_fiuit tells whether your plan allows it); on the free plan the API answers 409 and it stays visible.
Document base (FIU-774, FIU-795): one base per brand for the quote, receipt and account statement. get_quote_base (config:read) shows «Settings → Documents»: the brands (header with logo and company details, footer and page header), the fixed blocks (terms and conditions, warranty, confidentiality) with the documents each one appears in (document_types: quote, receipt, statement) and the available variables. With nothing set up it returns configured: false and a single brand with id: null, the project's: nothing needs to be configured. preview_quote_base (config:read, saves nothing) shows how a send of the requested document would freeze it (document_type: quote by default, receipt or statement; only its blocks appear), with sample customer and quote values. create_quote_brand and update_quote_brand (config:write) add or fix a brand's details and always ask for confirm=true: only use details the business gives you, never make up the legal name or tax ID. Fixed blocks are legal texts the business writes in the panel or through the API; there is no tool to draft them, choose which documents they appear in, delete brands or upload the logo.
Owners can enable feedback after completing a task: configurable form, single-use link, business branding and satisfaction indicators with a minimum sample. Comments follow privacy permissions. Low scores enter attention and create email and Telegram notices, subject to preferences and availability. Off by default; delivery depends on the channel and its reply window. A worker crash can cause the same link to be sent again; the response remains single-use.
F3-143 adds admission state to API conversation reads. The Inbox remains excluded from MCP: blocking/releasing contacts requires an Owner/Manager panel session (contacts:moderate). This initial delivery has no external moderation tool or anti-bot challenge.
Telegram policy is configured in the panel or through confirmed Wagy proposals. WebChat may require Turnstile when opening a session. These are public/panel surfaces without API key scopes: MCP does not open WebChat sessions or moderate contacts.
Review with an already applied electronic deposit does not trigger repeated final searches. Remaining charges use bounded retries; verified webhooks continue to be processed. Ambiguous creation uses exponential backoff capped at one day between searches during the seven-day successful empty-search window; release occurs on the next search, at most one day after completing the window. Errors, observed payments or lost credentials reset the empty-search evidence.
Guided turns, undo and restart of the setup interview require an Owner panel session and CSRF; they are not MCP tools. The public setup API is pending (F3-220).
confirm_booking uses the current core guards: a pending hold whose service was deactivated returns 409 service_inactive. A committed confirmation keeps its replay. Interview turns, undo and restart require an Owner session and CSRF and remain outside MCP.
Customer identity review and merging (F3-154) requires an Owner/Manager panel session with CSRF. MCP cannot merge by declared contacts; matches do not verify identity. Codes and merging financial history are still pending.
Reconfirmation and unanswered-request alert rules (F3-75) are configured through the automations API and remain excluded from MCP. They only alert after a sent request remains unanswered. There is no MCP tool for reconfirmation replies or releasing times because of silence.
Product import (F3-153, FIU-859): export_products_csv(template=false), preview_products_csv(csv) and confirm_products_import(import_id, confirm=false, actions) in the admin toolset; products:write scope, including export. Preview does not change products. Confirmation requires confirm=true, is atomic and idempotent by ID (result retained 7 days); previews expire in 30 minutes and catalog/currency changes require a new preview. Maximum 1 MiB / 2000 rows; UTF-8, shared amount rule (PYG/CLP integers; BRL «1,500» ambiguous). Wagy directs uploads to the panel; it cannot confirm CSV in chat.
Setup from Claude or ChatGPT (FIU-525)
Owner guide: Set up Fiuit with Claude or ChatGPT.
- Prompts (
prompts/list), one per task and language, no arguments:setup_from_scratch_{pt,es,en}(a short interview like Wagy's: calendar, hours, what it sells, how it gets paid),setup_bot_and_knowledge_{pt,es,en}(bot and knowledge base) andimport_catalog_{pt,es,en}. They are fixed instructions that name existing tools; every write still goes through preview andconfirm=true. The setup audit (audit_setup) ships separately. - Resources:
fiuit://setup/{pt,es,en}/guide(best practices and example business types, Markdown) and the templatefiuit://setup/{lang}/examples/{key}(services, flows, automations off, questions and typical hours of a business type; applied withapply_examples). - Import from files (one single import):
preview_products_csvtakescsv,file_base64,xlsx(base64 Excel file) orrows(up to 2000 rows the model read from an Excel file, PDF or photo), detects the columns on its own, andcolumns{header: column}corrects them (name,unit,price,category,sku,ean,stock,option1/value1…). It returns the counts for each action:update(update data),create(create what it did not find),stock(quantities, only if the file has them) andarchive_missing(archive, never delete, what the file does not have; unchecked by default and it lists what it archives);actionspicks the checkboxes. A file with only a code and a quantity touches only stock.undo_products_import(import_id, confirm)undoes EVERYTHING that was applied (data, creations, stock and archived items) while nobody touches it (409products.import_undo_stale), up to 7 days. - Services in bulk:
preview_services_import(same sources; columnsname,duration_min,price,team,full_day,bot_offered; create only),confirm_services_importandundo_services_import, withconfig:write. The API builds the table and validates. preview_service_from_text(config:write): reads free text ("haircut 30 min $8,000 with optional wash") and proposes name, duration, price and suggested add-ons. It returns the same preview aspreview_services_import: nothing is created untilconfirm_services_import, and the price is confirmed before saving.- Origin: the MCP sends the app's name (
clientInfoor User-Agent) inX-Wagend-Client-Name; the audit log stores it asclientnext to themcpactor («MCP · Claude»). It grants nothing.
Business operations (F4-45)
The repository server adds 76 tools: customers/addresses (customers), Inbox (inbox), read-only
finance (finance), task transitions (tasks) and catalog, schedules, automations and JSON knowledge
(admin). All seven toolsets are enabled by default.
tools/list publishes each scope and the schemas for path (IDs), query (filters) and body (JSON
command). Do not send a URL or project. New writes return a preview and a key; repeat with
confirm=true and a stable idempotency_key. The API validates permissions, requirements and
availability on confirmation; a preview does not guarantee success.
| Area / examples | Base scope |
|---|---|
list_customers, get_customer, addresses, summary and history | customers:read |
create_customer, update_customer, save/delete address; delete a customer (preview_customer_deletion, delete_customer: without history it is erased, with history it is archived) and restore_customer | customers:write |
Customer vehicles (FIU-609): list_customer_assets, get_customer_asset / create_customer_asset (the plate or the model is enough), update_customer_asset, delete_customer_asset | customers:read / customers:write |
Add a detail with free text (FIU-962): add_customer_detail spreads «phone 11 5555-1234, has a Fiat Uno ABC123» into contact, address, notes and assets | customers:write + customers:read |
A car's history (FIU-611): list_customer_asset_tasks; and assets (asset_id or a new car with text: «Model or plate») when creating or editing a task | customers:read / bookings:write |
Asset types: list_customer_asset_types / turn on Vehicles with create_customer_asset_type ({"preset": "vehicle"}) or turn it off (active: false: cars stay read-only) | customers:read / config:write |
list_conversations, list_conversation_messages, counts | messages:read |
send_conversation_message, mode, resolve, read, intent, open conversation and add_conversation_note (system notice, never sent to the customer) | messages:write |
move_work_item_stage, use_work_item_tool, unschedule, metadata and items | bookings:write |
fill_stage_from_photo (FIU-672), suggests values without saving | bookings:write |
Stage «update_work_item_asset corrects the task's asset (e.g. the mileage) and, if it is the asset's latest task, the contact's | bookings:write |
| Task history, comments, attachments and locations | bookings:read |
| Product detail / categories and suggestions | products:read / products:write |
Sales per product (get_products_stats) / performance per package or membership (get_prepaid_plans_stats); money only with finance:analyze | bookings:read / prepaid:read |
| Schedules, zones, resources, automations and knowledge | config:read / config:write |
| Financial summary, reports, debt, accounts, customers and forecast | finance:analyze |
Collection figures (get_finance_collections): gross, refunded, Mercado Pago fee, Fiuit fee and net by method, service and day or week, plus the estimate with no payment | finance:analyze |
| Finance availability/movements; cash; cash settings | payments:read; cash:read; cash:configure |
Customers omit names, contacts, documents and exact addresses by default; other sensitive views omit
free text and contacts. include_sensitive=true requires the advertised read scope in addition to the
base scope; it enables message/comment content. Finance preserves API amounts, warnings and estimates.
An action that collects money also needs the core financial permission: bookings:write is insufficient.
Exclusions drop from 134 to 58. Full panel equivalence remains pending: 26 routes do not accept
API keys (comment writes, conversation summaries and others; tracked in F4-47). Personal session/bell,
SSE, simulator, secrets/webhooks, binary/bulk CSV transfers and new money writes remain excluded.
Check the catalog with your key. A pending message does not prove delivery to the customer.
Customer notices and delivery log
Configure notices by service for requests without a time, assignments, edits and progress. They start disabled. Review sent, skipped, deferred and failed attempts in Settings, Activity and the customer profile. The log retains 90 days without copying messages or contacts; sent does not confirm delivery. Wagy and MCP read the same results.
list_customer_notice_deliveries, get_customer_notice_policies: config:read. update_customer_notice_policy: config:write, confirm=true.
get_notices_overview (config:read) returns the “Notices” index: everything the customer receives, ordered from the appointment, with each notice’s effective value, why it is held back and where it is edited. With config:write, set_notice_item_enabled turns a notice on or off in its source (rule, per-service policy, stage or flow) and set_all_notices_enabled is “turn off all customer notices”; both ask for confirm=true. The most specific wins: each notice’s own switch decides, and the general one beats everything. Stage rows publish the source flow and also require settings:write; without it, toggleable=false and writes return 403.
PUT and revert preserve the current catalog payment rule in every completed stage. Saving payment_requirement again repairs divergent versions; restoring historical stages does not change payment policy.
Reviews of overdue bookings with replaced links share the booking’s increasing retry delay, capped at one day. Each final search checks all unresolved preferences; errors prevent release and reset the empty-search evidence. Verified webhooks remain active.
The link expires 15 minutes before the booking; for shorter periods, the margin is half the available time, with a minimum of 5 minutes. The page and chat show the link deadline. The booking keeps its own deadline to verify delayed approvals. A local expired state cannot block a verified payment approved on time: it covers the deposit while the booking remains pending; a closed booking or late payment keeps the money under review without automatic reopening or refund. If the link would live less than 5 minutes (with the minimum margin, under 10 minutes to the booking deadline), it is not created: manual collection remains. A late payment after the place was released is kept apart as “to refund” (refund_due) on the task, the customer account and Finance, with one team alert per payment: it is not deducted from the customer's other debts until Mercado Pago's refund arrives or the team (Owner/Manager) moves it to the balance with “Use for another debt” (audited). With an open claim in Mercado Pago (in_mediation) it is not marked “to refund”: do not refund until it is resolved. Nothing is automatic.
Reserved sessions are also lost at expiry: the task returns to its normal price and the team receives a notice. Consumption failure returns prepaid_consumption_failed and leaves the task incomplete. Remove the plan before adjusting the amount or collection; internal notes remain editable.
If the window expires during sending, another usable channel for the same customer is tried. The no-se-pudo-avisar mark has a reserved slot in addition to twenty business tags, preserving them all. Reconfirmations and review requests remain in their original conversation and do not switch channels.
Configure the business over MCP and Fiuit help (FIU-397)
Everything onboarding sets up can also be configured over MCP, with the API key's permissions:
| Tool | Scope | Does |
|---|---|---|
duplicate_service | config:write (settings:write to copy stages) | Creates a paused copy of a service |
delete_schedule | config:write | Soft delete: keeps future bookings and returns them |
delete_service, delete_resource, delete_resource_group | config:write | Without mode it pauses (reactivate with update_* and active=true). mode=remove deletes when there is no history and archives when there is; archive archives; delete deletes or fails with 409 catalog_item_has_history. With future bookings it fails with 409 catalog_item_future_bookings and their list |
delete_product | products:write | Same, remove by default |
set_product_photo, remove_product_photo | products:write | Sets, replaces or removes the product photo the bot sends in chat: image_url (public https; Fiuit downloads it without following private addresses, up to 2 MiB) or image_base64 (PNG, JPEG or WebP). Without confirm it shows the product, type and size |
suggest_product_from_text | products:write | Reads free text ("sneaker size 42, $15.00, stock 10") and proposes name, size, price, stock, category, color and material. Saves nothing: the price is confirmed before saving. |
suggest_product_from_photo | products:write | Reads a product photo (public https url, or base64 image with mime) and proposes name, category, color, material, a sales description and synonyms; never the price. With product_id, only what is empty. Saves nothing: save what is accepted with save_product and the photo with set_product_photo. Uses AI energy from the plan |
list_product_variants, set_product_options, create_product_variant, update_product_variant, delete_product_variant | products:read / products:write | Sizes, colors and other product options (up to 3) and their variants, each with its SKU, barcode (EAN) and optional own price. available=true lists only the ones that can be sold. Writes require confirm=true |
adjust_product_stock, list_stock_movements | products:write | With «track stock» on for the product (save_product, track_stock): sets (qty) or adds and subtracts (delta) a variant's units, never below zero, and lists the movements (sale, return, manual, import) |
export_product_variants_csv | products:write | Variants and stock spreadsheet (one row per variant, by SKU, EAN or product and options); it is imported back with preview_products_csv, the single import for products, variants and stock (also your system's daily file: CSV, Latin-1 and semicolon-separated) |
get_service_removal, get_resource_removal, get_resource_group_removal, get_product_removal | config:write / products:write | What removing would do: delete or archive, and which future bookings it has |
restore_service, restore_resource, restore_resource_group, restore_product | config:write / products:write | Takes an item out of «Archived»; it comes back paused |
get_bot_settings, update_bot_settings | config:read / config:write | Bot personality (name, tone, greeting, what it sells, product photos), versioned |
create_prepaid_plan, update_prepaid_plan | prepaid:manage | Defines packages and memberships: price, units, validity, quotas and services, and their installments: due date (due_rule: signup, month_start, month_end or fixed_day with due_day 1–28), notice days (notice_days, 5 by default), first_fee_full (without it installment 1 is prorated) and sign-up flow (flow_id). A new price applies to the next installment of each live subscription (the customer is not notified; the response includes live_subscriptions). Selling is still sell_prepaid_plan |
suggest_plan_from_text | prepaid:manage | Reads free text ("pack of 4 haircuts $280, expires in 60 days") and proposes kind, name, price, units, validity and services. Saves nothing: it is money, so it is shown and, after the OK, created with create_prepaid_plan |
list_recommended_automations, install_recommended_automations, set_recommended_automation_active, activate_recommended_automations, undo_recommended_automations | config:read / config:write | Automations recommended by the business example; installed inactive and activated one by one |
get_automation_stage_options | config:read | Valid stages and actions for stage rules |
preview_customer_notices | config:write | Preview of customer notices with sample data; sends and saves nothing |
list_faq_suggestions, approve_faq_suggestion, dismiss_faq_suggestion | config:read / config:write | Automatic FAQ: questions that two or more customers asked, with no personal data and a proposed answer (when there is a source for it). Approving (as is or edited) adds it to the knowledge base; dismissing means it won't come back. Both ask for confirmation |
list_knowledge_sources, get_knowledge_source, list_knowledge_source_pages | config:read | Web sources and listings of the knowledge base |
preview_knowledge_source, create_knowledge_source, update_knowledge_source, refresh_knowledge_source, delete_knowledge_source | config:write | Register, pause, refresh or delete a source (deleting also removes what it imported) |
list_live_queries, create_live_query, update_live_query, test_live_query, disable_live_query | config:write | Live HTTP queries the bot uses |
apply_business_template | settings:write | Applies the industry template (barbershop, beauty, clinic…): vocabulary plus inactive automations and flows. Only on a new, empty project; it cannot be picked again |
apply_examples, undo_example | settings:write | Composes 1 to 3 examples by part (vocabulary, flows, automations, catalog) and undoes them without touching what the business changed |
get_vocabulary, update_vocabulary | config:read / settings:write | Project glossary (what tasks, customers and the team are called) |
export_project_template | config:read | The project configuration as a template (flows, catalog, plans, help, bot and automations), without customer data or secrets |
get_bot_channel_policies, update_bot_channel_policy | config:read / config:write | Bot policy per channel: required contact, reply limit, handoff and channel instruction |
update_feedback_settings | settings:write | Configures feedback after the service (read with get_feedback_settings) |
search_help | any key | Searches Fiuit help: how-to guides, "What happens if…?" and live product policies, with links to the guide and to contact. Reads no business data |
Credentials for sources and live queries never travel through MCP: they are entered in the dashboard and the API never returns them. Only what makes no sense to open stays out: the dashboard session and CSRF, streams, the simulator, webhook and channel secrets, the personal bell, large binary downloads (you get the link), the guided onboarding chat (its results are above), revoking a feedback link and cancelling the subscription.
Labels on every write. Every tool that writes declares in its description and in _meta["wagend/labels"] whether it notifies the customer (notifies_customer), whether it moves money (moves_money) and whether it is reversible, with the tool that undoes it (inverse). Anything that reaches the customer or moves money should always get a person's explicit confirmation.
Pause and duplicate
Pausing stops offering the service for new requests through the bot, public booking, Wagy and MCP. Already scheduled tasks continue normally. Reactivating offers it again. Pause and deactivate are the same action.
In the detail open ⋯ → Duplicate or Pause. Desktop also has a list menu. Wagy proposes both actions and waits for plan confirmation. MCP allows pausing with update_service(active=false, confirm=true); duplication is duplicate_service (paused copy, with confirmation).
API: POST /v1/services/{id}/duplicate, Idempotency-Key, config:write; settings:write to copy stages.
Unpaid memberships
list_prepaid_subscriptions lists project subscriptions with debt and pause (limit/offset); memberships include standing: up to date, in grace (grace, with the days left) or blocked (blocked, no coverage until paid; it unlocks by itself on payment). With unpaid=true, only unpaid ones (club or membership), with the customer name and the months owed (months_due), blocked first and clubs last. The response carries unpaid_count, the project's total of unpaid subscriptions even when there are more than limit. set_prepaid_benefits pauses an unpaid club or reactivates benefits with confirm=true, without charging or clearing debt. Both require prepaid:benefits. Paying an installment does not reactivate: use set_prepaid_benefits.
With the membership blocked, hold_slot and creating tasks for the member for that membership's services return 409 membership_blocked (with plan): the fee must be settled and it unlocks by itself once paid.
If your project is «Awaiting payment» (Fiuit's plan payment did not arrive and the grace period ended), every tool returns 402 workspace_awaiting_payment, read tools included, until the payment arrives.
Flows v2
Flows v2: validate_flow, create_flow and update_flow take flow with
format:2, stages and exits. Preview returns impact (total, up to 100 moves, by_service and shared_with);
confirm=true confirms publishing/restoring and moving open tasks to the first stage
with the same base status, without running entry notices. The team sees every item;
with visible_to customer, the bot asks those items and presses those buttons in the chat where the task was born
(source customer_chat in the history). A stage can move on by itself: a timer item with
timer: {until: duration|task_start|task_end|no_reply, minutes, to} (to is a button of the stage without mandatory items; task_start and task_end take no minutes, follow the task's start or end time and only exist in scheduled flows) or
auto: payment_received on a button (the task fully paid through Mercado Pago). Tasks carry stage_deadline for the
countdown and the move is logged with source auto. If the move fails, the task carries auto_advance_failed until someone moves it. A payment recorded by hand also triggers auto: payment_received. Also auto: customer_replied (the customer wrote on any channel after the task entered the stage) and auto: form_completed (every required item the customer sees is filled; the stage needs at least one), one per event in each stage; the reason is in data.automatic. move_work_item_stage and
use_work_item_tool require from_stage; also send config_version read from the
task. A 409 stage_conflict requires refreshing the task. Button requirements use
item.<key>; Close without completing uses exit.reason and stores a private reason.
Restoring v1 returns 422 version_format_unsupported. V2 excludes public customer
links, the simulator, payment/product items and conditions. Existing manual payments
keep the service policy.
SLA and escalation (F3-595), until: duration only: alert: {roles} or alert: {resource: assignee} instead of to alerts the team when it expires and the task stays in the stage (one alert per entry; stage_deadline.alert is true); by_item: {item, minutes: {option: min}} takes the minutes from the answer to an options item (with no answer minutes applies) and from: created counts from creation. In a queue flow, the entry stage (held) accepts a duration timer to escalate what nobody took. Cap: 43200 minutes (30 calendar days).
get_work_item_stage_history returns actor, source, kind and items with historical labels, including moves caused by publishing a flow. It returns the latest 100 events, newest first; the API accepts order=asc for chronological display. Photos and signatures are private references: fetching a file requires an authorized task download. visible_to only restricts the customer; team members retain their authorized task scope. Wagy can explain this journey through get_work_item within its existing scope.
The live_location item («Live location») is never filled through MCP or a form: on entering that stage the Telegram team bot asks the assignee to share their live location and the item is fulfilled by the first position. A task's last position is read with GET /v1/bookings/{id}/location-events (same permissions as the task); the team map (GET /v1/tasks/live-locations) is panel-only.
Review every service before changing a flow
When changing shared stages, you see which other services change and confirm the updated scope.
Several photos: the photo item accepts max_photos (1 to 10; without it, one). With more than 1, move_work_item_stage takes a list of attachment ids for that key. If the item is required, one photo is enough, and an extra one is rejected. Each photo counts toward the task quota (20 files and 50 MB).
«Mark on image»: the sketch item accepts sketch_background, the id returned by upload_stage_image (PNG, JPEG or WebP, up to 2 MiB). Without that field, whoever completes the stage attaches an image.
update_flow / revert_flow: Send the reviewed and accepted IDs from validation.impact.shared_with in shared_with_ack. On 409 stage_shared_unconfirmed, validate again and request a new confirmation; do not retry automatically.
The list includes every service using the flow, including the edited one.
get_work_item_journey (tasks, bookings:read) reads a complete task journey with historical maps: chronological events and referenced v2 versions, including retired stages. It preserves authorized task access and never substitutes the current flow for a missing version. By default it returns keys and dates; include_sensitive=true reads historical labels, actors and answers with bookings:read.
configure_customer_habits previews and saves when a customer is Due back, Late, At risk or Lost by their own rhythm: due_window (0.15), late_multiple (1.5), at_risk_multiple (2), lost_multiple (3) and lost_cap_days (optional cap); anything you leave out goes back to its default and null resets all (scope settings:write, confirm=true). The panel has no screen for this.
configure_pay_info previews and saves the payment details used without Mercado Pago (bank transfer, Pix), one text per language: texts with pt, es or en, up to 600 characters each; {} clears them (settings:write, confirm=true). The bot shows them when chat payment is «ask» and Mercado Pago isn't ready; «I paid» only alerts the team and never records a payment. Reading these details is for the panel and Wagy: an API key can't read GET /v1/workspace; the confirmed response returns what was saved.
configure_chat_payment previews and saves the business default chat payment rule (settings:write, confirm=true). update_service sets a custom rule with chat_payment or restores inheritance with inherit_chat_payment=true (config:write, confirm=true). The server calculates the amount; these tools do not create links.
Cancelling the subscription (GET /v1/subscription, POST and DELETE /v1/subscription/cancellation) is only for the Owner's panel session: an API key gets 403 and there is no MCP tool. Wagy reads the state and links to the screen, but never cancels.
get_control_summary: Attention matches Today: late respects the project grace period; notice_undelivered only open tasks; feedback_review includes finished tasks; out_of_coverage only open tasks, excluded from unzoned. Reasons may overlap: do not sum their counts.
list_tasks(attention="notice_undelivered") uses the same selection as the Control counter. attention accepts all eight attention reasons, combines with other filters before pagination and grouping, and adds no implicit dates. The scope remains bookings:read.
Intent flows can declare entry when created or edited: when to use them, examples, exclusions, keywords, and whether customers may start them. MCP previews these changes before confirmation. At most eight intent flows may be active. The bot collects initial details through chat and asks for confirmation before creating a task; direct task creation through MCP remains an explicit action.
With list_tasks(group_by="flow"), flow_capabilities returns only outcomes and delivery: the statuses supported by the project’s active flows, even without tasks, without names or IDs. A queue served at the business location does not imply deliveries.
Saving traits builds the glossary automatically if none is saved, preserving your edits. To change its names, use Settings → Vocabulary or ask Wagy and confirm the proposal. Glossary editing requires a panel session and is not offered through MCP.
Propose a new trait with Wagy
get_trait_catalog (config:read): pt/es/en. list_trait_proposals(cursor) (config:read). propose_trait(trait, confirm=false) / confirm=true (settings:write). Wagy prepares a name and questions in three languages. Review the proposal and confirm sending it: it stays as your own label until the team approves, rejects or merges it. Your customer service stays the same.
What happens if the AI-assistant channel reaches its limit?
Capacity is shared by the business: 600 AI calls and 200 new conversations per day, and up to 10 time slots held at once. Different people share these limits and can use them up. You receive a notice in Customer care → Channels notifications; the channel returns when the allowance renews or held slots are released. Other channels keep working. If the AI limit is reached during a reply, the bot asks the assistant to wait without handing the conversation over for that reason.
Closure reasons
get_flow → exits.close.reasons / exits.cancel.reasons: {key, label: {pt, es, en}}; update_flow → confirm=true. get_outcome_reasons(start, end, service_id?, resource_id?) → bookings:read.
Set reasons in My business → Stages. When closing, choose one or Other with an explanation. Cancellation allows omitting it. Results shows counts by flow, exit and reason.
list_tasks(sales="hide") excludes all quick sales from «+ Income» (like Today and the calendar). sales="work" keeps sales with an outstanding balance alongside regular work (like Work); sales="only" lists quick sales only and sales="all" (default) includes everything. Filtering happens before pagination and counting; permissions and amounts stay the same.
list_tasks(pay="unpaid"|"partial"|"paid") applies payment status to the entire selection before counting and paginating, together with the other filters. paid includes overpayments; no charge or an unknown status does not match. Requires payments:read_balance and keeps staff restricted to assigned jobs. The earlier payment_status parameter keeps its page-only filter.