Building an MCP server · Surface and auth

The tool surface for an accounting server

Cut a 52-endpoint accounting API to a tool surface for three callers, with scopes, a resource and a never-list, and price the definitions against wrapping everything.

designhardExercise · 4 min · 50 of 75

On this page

The books are the next system a model will touch, and a mis-posted journal is found only when the accountant reviews the month. The surface decides whether that can happen at all.

The situation

This exercise returns to the agency, not the online retailer of this module's lessons. Bookkeeping prep: each month about 600 bank transactions are categorised against a chart of 40 accounts. The operations manager keeps the books and does it by hand at about a minute each, 10 hours a month at an assumed $30 an hour, $300, and your external accountant reviews the month and signs it. You want one MCP server over the accounting system for three callers: a nightly categorisation automation, the operations manager, and you, asking "what did we spend on software in Q3?" from a chat host.

The accounting system's API has 52 endpoints: bank transactions, bills, invoices, contacts, journals, reports, payroll, attachments, users and settings. A contractor proposes wrapping all 52. In the system's own interface today, the operations manager can categorise transactions and attach receipts but cannot post journals or open payroll; only you see payroll; only the accountant can lock a period.

Assume about 150 tokens per tool definition, 4 model calls per transaction if the automation runs as an agent over the server, and the large model at $2 per million input tokens.

The question

Design the server's surface: the tools split into reads and writes with a scope on each, what becomes a resource, and the never-list. Then price the definitions a month against the contractor's 52.

A strong answer · Rubric · Where answers go wrong

Write your answer first, then open

A strong answer

Start from the operations manager's month, not the endpoints. Six tools.

Reads, scope books:read, all three callers: list_uncategorised(since, limit ≤ 50); get_transaction(txn_id); find_contact(name); and spend_by_account(account_code, from, to), which returns totals and never rows, so your Q3 question is one call.

Writes: propose_category(txn_id, account_code, score, reason), scope books:categorise, for the automation and the operations manager. It writes a draft and never posts. account_code is an enum of the 40 codes, so an invented account fails the schema; below the score cut, or on a transfer, tax or payroll line, the transaction goes to the review queue instead. attach_receipt(txn_id, file_id), scope books:attach, is for the operations manager only and append-only.

Resource: the chart of accounts, about 1,200 tokens, attached once per automation run; as a tool it would be fetched and resent transaction after transaction.

Never-list: posting, editing or deleting journals; locking or reopening a period, which is the accountant's signature; payroll, which one person sees and no model provider should; users and settings; bank-feed credentials; a free-form report query.

Cost: 6 × 150 = 900 tokens a call against 52 × 150 = 7,800. The automation makes 600 × 4 = 2,400 calls a month, so the difference is 6,900 × 2,400 ≈ 16.6M tokens, about $33. The money is not the argument. The 46 extra tools include post_journal and delete_transaction, which none of the three callers can use by hand.

What would change it: if the accountant corrects more drafts than the rate you accepted, for two months running, every draft queues for the operations manager first. Posting journals stays a gate the accountant signs.

Rubric

Derives each tool from a task in the operations manager's month or a question you ask, not from an endpoint.
Splits reads from writes, with a named scope per tool and the callers who hold each.
Bounds the categorisation write: a draft that never posts, the 40 codes as an enum, low-score and sensitive lines routed to review.
Puts the chart of accounts in a resource and gives the reason in tokens or in who chooses it.
Writes a never-list covering journals, period locks, payroll and credentials, each tied to what the caller cannot do by hand.
Prices 6 against 52 definitions with the arithmetic shown, and says why the price is not the deciding reason.

Where answers go wrong

"Wrap all 52 and rely on the system's own permissions." The system's permissions apply only if every call runs as the caller. With one service key, the automation holds post_journal, and nothing on the surface stops a forwarded supplier email from steering it. See designing the tool surface.

"Give the automation the operations manager's login, so it can do exactly what they do." Their name then sits on 600 entries they never made, and when they leave the automation stops. An automation gets its own identity and scopes, as in auth and identity.

"Add a run_report(sql) tool so you can ask anything." It reads payroll as easily as software spend, and one SELECT * over the ledger fills a window. spend_by_account answers the question you actually ask.