Engineering
One tool registry behind an MCP server, a REST API and an assistant
Software can act on a Bookatu business three ways: an AI app over MCP, a developer's code over REST, and the owner's own assistant in the admin. Each used to keep its own list of tools, and their checks drifted apart. Here is how one registry entry per tool now feeds all three, and how we moved to it before changing any behaviour.
The short version
- Each tool is one registry entry: its name, description, input schema, API scope, the permission its admin screen asks, whether it reads or writes, and the REST endpoint that does the same.
- Handlers are joined to entries when the module loads. A missing handler, or a handler with no entry, fails the build.
- One runner runs every call on every product in a fixed order, and marks every audit row with the product and the tool.
- Each product keeps its own transport and its own way of checking who is calling.
- A parity test fails when an entry is missing from a product, unless it sits on a named list with a reason.
There are three ways for software to act on a Bookatu business. A connected AI app talks to our MCP server. A developer's code calls the v1 REST API. The owner can ask the assistant inside the admin. All three end up doing the same jobs, such as adding a product or moving a booking.
They were built at different times, and each kept its own list of tools. The MCP route declared its tools inline. The REST API had its own route handlers. The assistant had its own dispatch table. Each list carried its own checks. Checks kept in three places drift.
How the drift showed up
The clearest case was the person behind an API key. On MCP, a key may never do more than the person who made it may do on that tool's own admin screen. If that person lost the permission, or left the team, the key's writes stopped. The REST route for the same action asked only whether the key held the scope. So an older key could keep doing on REST what MCP had already refused it.
The second case was the own-column rule. Some team members may only see their own column of the calendar. MCP held their keys to it. The REST route for the same action did not, so the same key reached anyone's booking there.
Neither bug came from a hard problem. Both came from one rule written twice and then changed once.
One entry per tool
The fix was to make the tool the unit, not the product. Each tool is now an entry in one registry, and the entry carries everything a product, a docs page or a test needs to know about it. Simplified, an entry looks like this:
type Channel = "mcp" | "rest" | "assistant";
interface ToolSpec {
name: string;
title: string; // owner words, also the MCP title
description: string; // written for the model
inputSchema: JsonSchemaObject;
scope: ApiScope; // what an API credential must hold
permission: Permission | null; // what the tool's admin screen asks of a person
access: "read" | "write";
destructive?: true; // changes or removes something already there
openWorld?: true; // emails a client, calls out, or publishes
rest?: { method: "GET" | "POST" | "PATCH" | "DELETE"; path: string };
column?: "bookingId"; // acts on one booking: held to the caller's column
audit?: (args: Args, result: unknown) => AuditRow | null;
}Specs are plain data with no server imports. The developer docs, the OpenAPI file and the MCP annotations read them without loading a database driver. Handlers live in server files and are joined to the specs once:
export function joinHandlers(specs: readonly ToolSpec[], handlers: Record<string, Handler>): Tool[] {
const tools = specs.map((spec) => {
const handler = handlers[spec.name];
if (!handler) throw new Error(spec.name + " has no handler");
return { ...spec, handler };
});
const extra = Object.keys(handlers).filter((n) => !specs.some((s) => s.name === n));
if (extra.length) throw new Error("handlers with no entry: " + extra.join(", "));
return tools;
}This runs when the module loads. A typo fails the build and the tests. It is never found by a caller.
One runner
Every call, from any product, goes through one function. The order matters, and it is the same everywhere:
export function runTool(tool: Tool, ctx: ToolContext, args: Args): Promise<unknown> {
return withToolMark({ channel: ctx.channel, tool: tool.name }, async () => {
await assertInColumn(ctx, tool, args); // the own-column rule
if (isDryRun(tool, args)) return dryRunPreview(ctx, tool, args);
return withIdempotency(ctx, tool, args, async () => {
const own = handlerArgs(tool, args); // the tool's own arguments only
const result = await tool.handler(ctx, own);
recordToolAudit(ctx, tool, own, result);
return result;
});
});
}withToolMark puts a small value in AsyncLocalStorage for the length of the call. The audit logger reads it. So every row recorded during the call gets two extra changes: the product it came through and the tool that ran. That holds for rows the tool writes itself and for rows written deep inside a shared library it calls. The Audit log page reads them back, for example as made through a connected AI app, with the tool's name beside it.
Some writes recorded no audit row at all before, such as a few catalog and content changes. Their entries now carry an audit function, and the runner records the row for them.
Dry runs and idempotency keys are answered here too, once, so no handler has to implement them. Our posts Dry runs that never write and Idempotency keys that survive a cut-off request cover those two steps.
What each product keeps
The registry does not try to be a transport. Each product still owns what is truly different about it.
- MCP keeps JSON-RPC, its credential checks for an API key or a connected app, the scope and read-only gates, and its rate limits. tools/list is built from the entries, with titles and annotations from the same fields.
- REST keeps the v1 conventions: the key in a header, the error envelope, paging with limit and cursor. A new tool's route file is one line: export const POST = registryRoute("create_product").
- The assistant asks the signed-in person's permission on the business's own role grid before a write, and a person confirms on a card. What it may propose at all is its own list, kept in code. Our post The allowlist is the boundary explains why.
- Each answers a refusal the way its callers expect: a tool error the model reads on MCP, an HTTP status and an error code on REST, a sentence in the chat.
The context a handler receives has the same shape on every product. MCP and REST fill it from the credential and the person who made it. The assistant fills it from the signed-in person. The handler does not know which.
Routes that already existed
Many tools already had a REST endpoint with its own handler and its own exact answers. Integrations depend on those answers, down to the error messages some code matches on. Rewriting them through the new path would have changed them.
So those routes keep their handlers, and are wrapped. The wrapper acts only on a call the route itself would let through. Anything the route refuses, it still refuses, word for word.
export function registryGated(name: string, inner: RouteHandler): RouteHandler {
const spec = toolSpec(name);
return async (req, routeCtx) => {
const key = await verifyApiKey(req);
// Anything the route would refuse, it refuses itself, as before.
if (!key || !(await keyHoldsScope(key, spec.scope))) return inner(req, routeCtx);
const maker = await keyMaker(key);
const refusal = await screenRefusal(spec, maker); // the same check MCP makes
if (refusal) return apiFail(refusal.message, 403, refusal.data);
return withToolMark({ channel: "rest", tool: name }, () => inner(req, routeCtx));
};
}The real wrapper also applies the own-column rule, dry runs and idempotency keys. For the own-column rule it hands the route an id that cannot exist. A booking outside the caller's column then gets the route's own not found answer, in the route's own words, and nothing runs.
A pure move first
We did this in two steps. The first moved every tool into the registry and changed nothing. Before it, we wrote characterization tests that captured what each product answered, from every byte of tools/list to every refusal. The move had to pass them unchanged.
Only then did later steps change behaviour, such as holding REST keys to their maker's permission. Each change was marked as deliberate in the tests it touched, with a note on why.
That split is what made review possible. A diff that moves two thousand lines and changes behaviour is unreadable. A diff that moves two thousand lines and passes the old snapshots is boring, which is what you want.
The parity test
A registry is only shared if every product actually uses it. A test holds that:
- Every entry is served by MCP, REST and the assistant, or sits on a named exception list with a reason.
- Every MCP entry names its REST endpoint. The test finds the route file at that path, checks it exports that method, and checks the route asks the entry's own scope.
- Every server action on an admin screen is covered by a tool, or by a guide entry that gives the steps and a link to the screen, or is on a list of things never done through an AI.
- The number of gaps is pinned. It may go down. It cannot go up without someone editing the test.
The last point does the work. A new admin feature fails the build until someone decides how AI and API callers reach it.
How this differs from shared booking rules
Our post One rule, every door is about a different layer. There, the rules of a booking, such as which services may share a visit, live in one function that the booking page, the staff form, REST, MCP and mobile all call. That keeps the answer the same wherever a booking is made.
This post is about the layer above it: the gates a caller passes, and the record left behind. The booking rules keep a booking right. The registry keeps the gates in front of it the same.
Trade-offs
- An entry is bigger than a function signature. A new tool needs its scope, permission, REST path and audit row decided up front. That is the point, but the first tool in a new area is slower to add.
- Specs and handlers live in separate files, so the MCP route never loads the assistant's code and the docs load neither. You trade one file per area for two.
- Some differences are real and stay. The assistant confirms with a person on a card. MCP and REST have no card, so a caller there checks first with a dry run and retries safely with an idempotency key.
- Wrapping the old routes keeps their answers stable, but REST has two code paths until those routes are retired.
What we take from it
- Make the tool the unit, and let each product be a thin adapter around it.
- Fail at load, not at request time, for anything structural.
- Move first and change second. Keep the snapshot tests that prove the move.
- A parity test that only lets the gap shrink is worth more than a checklist.
Building on Bookatu?
Bookatu has a public REST API and webhooks. Have a look at the developer docs.
Developer docs