API, MCP and Workflows Together: One Balance, Three Doors

The three server-side doors on ToolForte (the REST API, the MCP server and workflows) are often described one at a time, and each is useful alone. The setup I actually run uses all three, and it is simpler than it sounds: a workflow is the recipe, the API is how a program runs the recipe, and MCP is how a person with an assistant runs it. All of it draws from one balance, so there is one number to watch.

Here is a concrete example, then the rules that keep it boring.

The example: a new-client check

A freelancer takes on a new client and wants the same four checks every time: is the IBAN valid, is the VAT number valid, is the billing email address well formed, and what is the VAT on the first invoice amount.

That is a four-step workflow. Step one is the IBAN validator taking the declared input iban. Step two is the VAT number checker taking vat_number. Step three is the email validator taking email. Step four is the VAT calculator taking amount and the rate. Four declared inputs, four steps, every one of them pure computation. The template called "New client billing check" on the workflows page is this exact chain, so you do not have to build it.

Door one: the button

Saved on the account, the workflow is a form with four fields. Because every step is pure computation, a run from the form happens in the browser and costs nothing; the inputs never reach us. For the freelancer this is already the whole product: one page, three fields, one JSON result to paste.

Door two: the REST API, for the invoicing tool

The bookkeeping tool wants the check to happen when a client record is saved, without anyone opening a page. So the backend calls POST /api/v1/workflows//run with {"iban": ..., "vat_number": ..., "email": ..., "amount": ...} and the key in the X-API-Key header. The answer carries every step's output and the cost of the run, which for this chain is 4 credits (one per utility step).

The thing to notice is that the backend did not have to know the four tools. It knows one workflow id. When the freelancer adds a fifth step next month, the backend keeps calling the same id and gets a fifth output.

Door three: MCP, for the person with an assistant

The same freelancer, in Claude, pastes an email from a prospective client and says "run my new client check on this". The assistant calls workflow_list, sees a workflow that wants iban, vat_number, email and amount, reads those four values out of the message, and calls workflow_run. Four credits again, same outputs, and the assistant summarises them.

This is the door I use most, because the data arrives in prose (an email, a ticket, a PDF) and the assistant is good at pulling four values out of prose. It is bad at validating an IBAN. The workflow makes that split explicit.

One balance is the point

Every call above, whichever door it came through, drew from the same monthly balance: 1,000 credits on a free account, 7,500 on Pro at €19 a month, plus any extra credits you bought (100 for €1.00, 1,000 for €5.00, 5,000 for €20.00 at the time of writing, and they never expire).

That sounds like an accounting detail. It is a design decision. With separate quotas per door, the backend hits its limit while the assistant has plenty, and somebody spends an afternoon moving budget around. With one balance, the question is only "how much work did we do this month", and the usage history on the account page answers it per door.

Rules that keep it boring

Read the 429. When the balance is empty the API answers 429 with the reset date in the headers, and an MCP tool result says the same in words. A client that retries blindly gains nothing.

Turn on automatic top-up if a machine depends on it. Threshold, amount, monthly ceiling; it charges the saved card at the public price and stops at the ceiling. You can remove your own ceiling, in which case ToolForte's own limit of €500 a month is the stop. I keep a ceiling. A ceiling that is too low fails loudly; no ceiling fails expensively.

Keep renders out of the hot path. A render step is 25 credits and runs on our servers. A chain that renders a PDF on every save of a client record will burn a free month in forty saves. Render on the action that needs the document, not on every edit.

Pin the workflow, version the caller. The workflow id is stable. If you change the chain in a way the backend must know about (a renamed input, a removed output), make a new workflow and move the id in the caller. Editing in place is fine for adding a step at the end.