Pavol Rašev
Available for remote contracts from December
Blog

An MCP server for a booking system: what the assistant must not reach

Put the boundary in your API, not in the MCP server, and make the default answer no. The MCP server I built for FyzioDesk gives an assistant six receptionist tools, goes through the same public API as any other integration, and cannot reach medical records with any key or token, because those paths are refused before scopes are even checked.

An MCP server with a boundary An AI assistant calls six tools on the MCP server. The server goes through the public API, which checks the scope of every request before it reaches the calendar, clients and invoices. Medical records, photos, attachments, consents and questionnaires never go through the API. An MCP server with a boundary What an assistant can reach in a physiotherapy booking system Assistant Claude, Cursor… MCP server 6 receptionist tools Public API checks every scope Calendar clients · invoices Never through the API, with any key medical records · photos · attachments · McKenzie · consents · surveys pavolrasev.com

The first thing I wrote in the permissions file for FyzioDesk’s public API wasn’t a permission. It was a list of six words: records, photos, attachments, mckenzie, consents, surveys. Any request whose path contains one of them is refused when it arrives with an API key or an assistant’s token, whatever scopes that key has. Everything else about the MCP server came later and was easier.

FyzioDesk is software for physiotherapy practices in Slovakia and Czechia: a calendar, online booking, client records with medical notes, exercise plans, invoices. The MCP server lets a receptionist (or a therapist without a receptionist) ask Claude or another assistant to do the front-desk part: find a client, check the day, offer a free slot, book, cancel, list unpaid invoices. This article is about what it is allowed to touch, and why most of that decision lives outside the MCP server.

If you run a SaaS where some data must never end up in a chat window (health, HR, finance, anything about children), the same questions apply to you. The MCP part is the small part.

Six tools, shaped like a receptionist’s day

MCP is the protocol an assistant uses to call your application’s functions. Most “build an MCP server” guides wrap the API one endpoint per tool. I didn’t, and I’d do it the same way again. “When is there a free slot for individual therapy?” is one question for a receptionist, but behind it are a clinic, a service, a therapist and their working hours. If the model has to assemble that from five endpoints, it spends half its calls looking up IDs, and sometimes it picks the wrong one.

So there are six tools. The names are in Slovak, the language of the people using them:

Tool What it does Scopes it needs
najdi_klienta Find a client by name, phone or e-mail; returns the ID needed for booking clients:read
terminy_dna The schedule for a day (“today”, “Monday” or a date) appointments:read
volne_terminy Free slots for a service over the next 1 to 30 days catalog:read, appointments:read
objednaj_klienta Book a client into a slot catalog:read, appointments:read, appointments:write
zrus_termin Cancel an appointment by its ID appointments:write
neuhradene_doklady Unpaid, partly paid and overdue invoices invoices:read

A few decisions inside them matter more than the list.

Booking needs an ID, never a name. objednaj_klienta only accepts the ID that najdi_klienta returned. Two clients with the same name are ordinary in any practice, and the tool description tells the model why it has to look the person up first.

The therapist comes from the free slot, not from the model. The booking tool asks the availability engine for that exact time and takes the therapist and room it returns. That’s the only answer that will pass the database constraint against double booking anyway.

Dates are resolved in code. “Tomorrow at nine” is turned into a timestamp in the clinic’s time zone by a small module with an injected clock. Late in the evening UTC it is already tomorrow in Bratislava, and I didn’t want the model doing that arithmetic.

Errors come back as answers. When the API says the therapist already has an appointment at that time, the tool returns that sentence with isError: true instead of throwing. The spec calls these tool execution errors and expects the model to use them to self-correct. For the person on the phone it’s the difference between “she has nothing at nine, how about 10:30?” and an assistant that just stops.

Output is plain text, not JSON. The model reads both equally well. When it misreads text, though, you can see the mistake in its answer and check what it is about to tell the client.

The boundary lives in the API

The MCP server has no database connection. It calls https://…/api/v1/… with a bearer credential, exactly like an accounting system or a clinic’s website would. That’s the main design decision, and the reason the server itself is about 850 lines of TypeScript, plus tests.

Everything that decides what the assistant may do sits in the API, where it already protects every other integration:

The credential belongs to a person, not to the clinic. An API key is tied to the membership of whoever created it. If that person is suspended or leaves, the key stops working at the same moment. A key can never do more than its owner, and only a SHA-256 hash of it is stored; the full key is shown once.

Scopes are derived from the request, not declared on each endpoint. The API has over a hundred endpoints, and an annotation forgotten on one of them would be an open door. So the required scope is computed from the method and the path, and anything not in the mapping is refused. A new endpoint is closed to keys until someone deliberately opens it. Shortened and with the comments translated, it looks like this:

// Health records, photos, attachments, McKenzie assessments, GDPR consents
// and questionnaires never go out through the API. No scope opens them.
const FORBIDDEN_SEGMENTS = ['records', 'photos', 'attachments', 'mckenzie', 'consents', 'surveys'];

export function scopeForRequest(method: string, path: string): ApiScope | null {
  const segments = path.replace(/^\/+/, '').split('/').filter(Boolean);
  const start = segments[0] === 'api' ? 2 : 0; // drop /api/v1
  const resource = segments[start];
  if (!resource) return null;

  if (segments.slice(start).some((s) => FORBIDDEN_SEGMENTS.includes(s))) return null;

  const write = method.toUpperCase() !== 'GET';
  switch (resource) {
    case 'clients':
      // /clients/:id/appointments is the calendar, not the client file
      return segments.includes('appointments')
        ? (write ? 'appointments:write' : 'appointments:read')
        : (write ? 'clients:write' : 'clients:read');
    case 'appointments':
      return write ? 'appointments:write' : 'appointments:read';
    case 'availability':
      return write ? null : 'appointments:read'; // read-only, even if someone tries
    case 'invoices':
      return write ? 'invoices:write' : 'invoices:read';
    case 'clinics':
    case 'services':
    case 'team':
      return write ? null : 'catalog:read';
    // …exercises, reports
    default:
      return null; // null means "never with a key", not "no limit"
  }
}

There’s an end-to-end test that creates a key with clients:read, asks for /clients/:id/records and expects 403. Another one checks that a key cannot create another key, which would otherwise be a neat way to widen your own permissions.

The assistant gets fewer scopes than the API has. The connect screen in the app only offers five: clients:read, appointments:read and catalog:read are required (without them it can’t answer “what do I have today”), appointments:write and invoices:read are optional. Write access to exercise plans exists in the API, but no tool uses it, so the assistant never asks for it. Asking for permissions you never use is the best way to teach people to click “allow” without reading.

For the remote version, where Claude connects over HTTP and the person signs in through OAuth, there’s one more rule that I think is the one people forget. The scopes actually granted are the intersection of three sets: what the client asked for, what the person ticked on the consent screen, and what that person’s role may have at all. A receptionist can hand the assistant invoices but not reports; a therapist can’t hand it invoices, because she doesn’t see the practice’s revenue in the app either. Without the third set, the assistant would become a way around the app’s own permissions.

What the spec asks, and where I’m not done

I checked all of this against the MCP specification version 2026-07-28 on 5 October 2026. Two things didn’t line up, so I fixed them and checked production again on 14 October. Two more are still open, and I’d rather say so here than have you find it.

Local and remote are different rules. The spec says a server running over stdio (a process on your own computer) should not use the OAuth flow and should take credentials from the environment. That’s the local mode: the API key sits in an environment variable. Over HTTP, the server must publish OAuth Protected Resource Metadata (RFC 9728) and answer an unauthenticated request with 401 and a WWW-Authenticate header pointing at it. FyzioDesk’s server does that, and it checks the token against the API before it starts streaming a response, because once a 200 has gone out, the client can no longer learn that it should sign in again.

The OAuth details are there. PKCE with S256 only, authorization codes valid for 60 seconds and usable once (a second use revokes the whole grant), exact redirect URI matching, refresh tokens rotated on every use, a resource parameter checked against the server the token is for. A person can see their connected assistants in their account and disconnect one, which kills its tokens immediately. Dynamic client registration is still accepted even though the spec now marks it as deprecated, because the clients people actually use still rely on it.

Tokens now belong to one server. My first version simply forwarded the caller’s token to the API and let the API decide. The spec says an MCP server must check that a token was issued for it and must not pass on tokens meant for anything else; its security page calls passthrough an anti-pattern. So I changed it. A token is now issued either for the API or for the MCP server, following the resource parameter from RFC 8707, and it only works where it was issued for. The resource is stored with the authorization code and the tokens, and it can’t be changed when the code is exchanged or the token refreshed. The MCP server checks on every request that the token is its own and answers 401 with WWW-Authenticate otherwise. The API accepts a token meant for the MCP server only from the MCP server itself, which has to prove who it is with a secret of its own. Older tokens without a resource keep working as before, so nobody connected had to sign in again.

Rate limits follow whoever is calling. The tools section of the spec says servers must rate limit tool invocations. The first version only had the API’s general limit, counted per IP address. For the remote server that meant every clinic behind it shared one counter, because every request came from the same container. Now the limit follows the caller: an API key by its own ID, a connected assistant by its consent, a signed-in person by their account, and only anonymous requests by IP. Each has its own default (120 a minute for a key or an assistant, 300 for a person, 60 anonymous). Sign-in, token, registration and revocation endpoints are still counted per IP, registration has a shared hourly cap, and an assistant that goes over gets 429 with Retry-After. While I was there I found that the API trusted the X-Forwarded-For header from anyone, so a caller could pick their own IP address. It now trusts it only from the internal network.

The audit trail has a gap. Creating and revoking keys is in the audit log, and every key and connected assistant records when it was last used. A booking the assistant makes is recorded as made by the person who connected it. What I can’t yet tell you afterwards is which bookings were made by a receptionist with her own hands and which by her assistant. For a clinic that’s a reasonable question, and the answer should be in the data.

And “no medical records” is not the same as “no health data”. I used to describe this server as one that “can’t see health data”. Reading GDPR more carefully, I wouldn’t say that any more. Article 9 prohibits processing data concerning health unless an exception applies, and Recital 35 counts information “collected in the course of the registration for, or the provision of, health care services” as health data. A list of who is booked at a physiotherapist’s on Tuesday arguably falls under that. What the boundary really does is keep the assistant at the level of what a receptionist sees, and keep clinical notes, photos and questionnaires out of it entirely. The clinic still decides whether to connect an assistant at all, and which provider’s terms it accepts for the data that does pass through. I’m an engineer, not a lawyer; a practice should ask its DPO.

The AI built into FyzioDesk itself, which drafts replies to client messages and notes from a therapist’s dictation, is a different case, because there FyzioDesk picks the model provider, not the clinic. So it goes further. The client’s name is never sent; the greeting is filled in on our side after the draft comes back. E-mails, phone numbers, birth numbers and IBANs are stripped from the text, and so is the client’s name in its declined Slovak forms. Photos and attachments never leave. It stays off until the practice owner switches it on, a reply or a booking only happens when someone clicks, and every use goes into the audit log without its content. The provider is Anthropic, under a data processing agreement and without training on the data, and the clinic names it in its own privacy notice. One thing I want to be plain about: FyzioDesk runs in Frankfurt, but it calls Anthropic’s API directly, and there the only choices today are “US” or “global”. With the default, a request may be processed in the US, Europe, Asia or Australia, and Anthropic stores API data in the US. Keeping it inside the EU would mean calling Claude through a cloud provider’s EU region instead. That’s data minimisation as Article 5 means it, and it still isn’t “no health data”: a request about a sore knee is about health, with or without a name.

A checklist for scoping an MCP server over sensitive data

This is what I’d go through before connecting an assistant to any SaaS with data you’d be embarrassed to see leak. You can do all of it without me.

  1. Write the “never” list first. Name the data no tool, key or token may reach, and enforce it in the API as a path or field rule that no scope can override. Test it with a key that has every other scope.
  2. Make the API refuse by default. Compute the required scope from method and path, and return 403 for anything unmapped. New endpoints should be closed until someone opens them on purpose.
  3. Keep the MCP server thin. No database access of its own. If it can only do what the public API allows, you have one set of rules instead of two that drift apart.
  4. Tie every credential to a person. Keys and tokens inherit that person’s role and die with their membership. Store hashes, show the secret once.
  5. Grant the intersection. Requested scopes, consented scopes and the role’s ceiling. An assistant must never see more than its owner sees in the app.
  6. Ask only for scopes a tool uses. Mark which are required for the assistant to work at all, and make the rest optional.
  7. Shape tools around a job, not an endpoint. Fewer calls, fewer wrong IDs. Require an ID for anything that writes, so the model can’t act on a name it guessed.
  8. Do dates, time zones and money in code. Not in the model.
  9. Return errors as tool results the model can act on, and say in the tool description when something can’t be undone (a cancellation that notifies the client, for example).
  10. Follow the spec’s auth rules for remote servers: protected resource metadata, 401 with WWW-Authenticate, PKCE S256, token audience checked, no token passthrough.
  11. Rate limit per assistant, not only per IP or per user.
  12. Record who acted through which assistant, so “did a person or the assistant do this?” has an answer in the data.

I’m not finished with the last three on FyzioDesk, as you’ve read. The first nine took most of the work, and they’re also the ones that would have been expensive to add later.

If you have a product with data like this and want your users to reach it from Claude or ChatGPT without handing an assistant the keys to everything, that’s the kind of work I take on. The FyzioDesk case study shows the rest of the system, and the AI page has what else I’ve shipped. Send me the list of things your assistant must never touch, and I’ll tell you what I’d build around it.

Sources