Building the Tolt MCP Server

Some weeks ago we shipped Tolt's MCP server. Monday to Friday, idea to production. This is what we learned along the way.

If you haven't touched MCP yet: it's a protocol that lets AI tools like Claude or ChatGPT call your API directly. You expose a set of tools, the model picks which one to call based on what the user asks, and it gets back a real answer instead of a hallucinated one. For Tolt, this means someone can ask their AI "who are my top five affiliates this month" and the data just shows up. No dashboard, no CSV export.

Simple idea. Surprisingly opinionated implementation.

Thin wrappers aren't enough

We started the way most people probably start: by auto-generating tools from our existing API. One endpoint, one tool. list_partners, get_partner, list_commissions, and so on.

It worked. But the first real question we tried killed it.
"Show me partners who generated over $10k last quarter but dropped 40% in the last 30 days."

With only thin wrappers, the agent has to page through every partner in the program, then page through every transaction for each one, computing totals as it goes. By the time it's halfway done, the context window is cooked.

So we added a second layer of tools on top of the API wrappers. Tools that do the aggregation on the server instead of forcing the agent to do it:

- top_partners scans every partner and ranks them by revenue, commissions, clicks or customers.

- partner_performance_snapshot pulls every customer, transaction and commission for one partner in parallel, then returns status breakdowns and totals.

- commission_reconciliation cross-references transactions against commissions by ID to find orphans and compute effective commission rate.

- get_program_summary fires four parallel requests with limit=1 and reads only total_count from each. A whole-program overview in roughly one round trip.

These are what the agent actually reaches for. The thin wrappers are there for the weird edge cases.

The rule we ended up with: fewer, richer tools beat many atomic ones. Every extra tool call costs tokens and gives the agent another chance to go off the rails.

Cheap answers to cheap questions

The best tool we wrote doesn't hit the API at all.

schema_introspect returns hardcoded field lists and recommended CSV columns for every resource we expose. The agent calls it first to figure out what it's allowed to ask for, then reaches for real data. Answering "what fields exist on a partner" shouldn't cost a network round trip. Once you stop making it cost one, the agent becomes dramatically better at planning queries before executing them.

We didn't see this one coming. schema_introspect was built as a small debugging aid and turned out to be one of the most-called tools in the entire server.

Exports need their own flow

Some questions require touching every record in a program. "Export all commissions from last year." "Pull every transaction above $5k." You can't stream a million rows back through a single tool call. The response alone would blow out the context window.

The fix was an async job system with three tools:

- export_job_start returns a job ID immediately and starts paging the API in the background.

- export_job_status lets the agent poll progress and watch row counts climb.

- export_job_result pages through collected rows 500 at a time with a numeric cursor.

The agent handles this pattern natively. Polling and paging is something it's seen a thousand times before. What surprised us is how willing it is to wait. If you tell it the job takes thirty seconds, it checks in, reports back to the user, and picks up where it left off. No prompt engineering required.

What we'd do differently

Honestly? Not much. The biggest lesson is that the right mental model for an MCP tool is closer to a good CLI command than a REST endpoint. REST is designed for programs that know exactly what they want. MCP is designed for something halfway between a user and a program. It needs hints, shortcuts, cheap ways to explore, and a clear picture of what's possible.

If you're adding MCP to your own product, the first thing to write isn't tools. It's a list of the questions you want someone to be able to ask. Then work backwards. The shape of your tools will be obvious once you know what the agent needs to do with them.

We'll keep iterating on ours. The landscape is moving fast. Tool search layers are already changing the advice around tool count, and streaming responses are on the horizon. What ships today is not what ships in six months.

But the core idea isn't going anywhere. AI tools are going to be the new front door to SaaS, and the products that feel natural through that door are the ones that thought about it on purpose.