Clinic Reception
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
mcp-api-boundary
A small, working example of an MCP server that lets an assistant do a physiotherapy clinic's front-desk work (find a client, check the day, offer a slot, book, cancel, list unpaid invoices) without ever being able to reach clinical notes, photos or questionnaires. The point is where that guarantee lives. The MCP server here has no data access of its own and no rules of its own: it calls the clinic's public API with a bearer key, and the API decides. The boundary lives in the API, not in the MCP server, and the default answer is no. Everything runs in memory with fictional seed data, so you can clone it, run it and connect Claude Desktop in a few minutes.
The design
The API derives the required scope from method and path.
scopeForRequest('POST', '/v1/appointments')returnsappointments:write. Anything not in the table returnsnull, andnullis a 403. A new endpoint is closed until someone opens it on purpose.Sensitive paths are refused before scopes are checked. Any request from an API key whose path contains
records,notes,photos,attachments,consentsorsurveysgets a 403, whatever scopes the key holds. The check decodes percent-encoding and ignores case and extensions, so%72ecordsandRecords.jsonare refused too. A mistake in the scope table cannot open them.Every key belongs to a person. A key's effective scopes are the intersection of what it was granted and what its owner's role allows today. Demote the owner and the key shrinks. Suspend them and it stops working. Only the SHA-256 hash of a key is stored.
The MCP server is thin. It has an HTTP client and six tools. If the API would refuse something, the assistant cannot do it, so there is one set of rules instead of two that drift apart.
Tools are shaped like a receptionist's day, not like the API.
free_slotslooks up the service and asks the availability engine in one call.book_clienttakes a client ID (never a name) and gets the therapist and room from the free slot, so the model never picks them.Dates and money are handled in code. "Tomorrow", "Monday" and "2026-11-03 09:00" are resolved in the clinic's timezone with an injected clock. At 23:30 UTC it is already tomorrow in Bratislava, and the tests check exactly that.
Errors are answers. When the API refuses ("That time is not free for this service", "This key does not have the invoices:read scope"), the tool returns that sentence with
isError: true, so the model can tell the person what happened and what to try next.
Related MCP server: voxfactura-mcp
How a request flows
sequenceDiagram
participant A as Assistant
participant M as MCP server
participant API as Clinic API
A->>M: tools/call book_client(cl_004, "massage", "tomorrow 13:00")
Note over M: resolve "tomorrow 13:00" in Europe/Bratislava
M->>API: GET /v1/services (Bearer key)
M->>API: GET /v1/availability?serviceId=...&from=...
Note over API: 1. known key, owner active? else 401<br/>2. sensitive segment? 403<br/>3. scopeForRequest: unmapped? 403<br/>4. key holds the scope? else 403
API-->>M: free slots with therapist and room
M->>API: POST /v1/appointments (slot's therapist)
API-->>M: 201, or 409 "That time is not free..."
M-->>A: one plain-text sentence (isError on refusal)Running it
You need Node 20.19 or newer and pnpm.
pnpm install
pnpm build
DEMO_API_KEY=cbk_local_demo pnpm apiThe API starts on http://localhost:8787 with a fictional clinic and one API key for the receptionist. Without DEMO_API_KEY, a random key is printed on every start.
Try the boundary by hand:
curl -H 'authorization: Bearer cbk_local_demo' 'localhost:8787/v1/clients?search=anna'
curl -H 'authorization: Bearer cbk_local_demo' localhost:8787/v1/clients/cl_001/records
# {"error":403,"message":"Clinical data is never available to API keys or assistants."}Connecting Claude Desktop
Add this to claude_desktop_config.json (Settings, Developer, Edit Config), with the absolute path to your clone, and restart Claude Desktop while the API is running:
{
"mcpServers": {
"clinic-reception": {
"command": "node",
"args": ["/absolute/path/to/mcp-api-boundary/packages/mcp/dist/main.js"],
"env": {
"CLINIC_API_URL": "http://localhost:8787",
"CLINIC_API_KEY": "cbk_local_demo",
"CLINIC_TIMEZONE": "Europe/Bratislava"
}
}
}
}Then ask something like "Who is booked tomorrow?" or "Find a free sports massage on Friday and book Zuzana Molnár in." For development, pnpm mcp runs the server from source with tsx.
Checks
pnpm typecheck
pnpm lint
pnpm testThe end-to-end tests start the API on a random port, connect a real MCP client to the server and call the tools. One of them throws path traversal and encoded segments at the tools and at every sensitive path with a key that holds every scope a key can hold, and checks that nothing clinical comes back.
Tools
Tool | What it does | Scopes the key needs |
| Search by name, phone or e-mail; returns the client ID booking needs |
|
| Who is booked on a day ("today", "Monday", a date) |
|
| Free times for a service over the next 1 to 30 days |
|
| Book a client by ID; therapist and room come from the free slot |
|
| Cancel by appointment ID; marked destructive, the model is told to confirm |
|
| Unpaid and partly paid invoices, overdue first |
|
No tool, and no API key, can get clinical:read. It exists only for people signed in to the app.
Adding an endpoint safely
Add the route in
packages/api/src/app.ts. At this point it answers 403 to everyone, becausescopeForRequestdoes not know it.Add one line to
ROUTESinpackages/api/src/scopes.tswith the narrowest scope that fits. Match the full path with an anchored pattern and a strict ID character class.If you need a new scope, add it to
SCOPES, decide which roles get it inROLE_SCOPES, and decide whether keys may hold it at all (KEY_SCOPES).If the endpoint touches data that must never reach an assistant, put its path segment in
FORBIDDEN_SEGMENTS. That rule wins over any scope.Add cases to
scopes.test.tsfor the request that should pass and for the ones that should not (other methods, trailing slash, encoded segments).Only then think about whether the assistant needs a tool for it. Most endpoints do not.
What is intentionally not here
OAuth 2.1. A remote MCP server in production should not ask people to paste API keys. It should follow the MCP authorization spec: protected resource metadata,
401withWWW-Authenticate, PKCE with S256, tokens bound to this server as their audience, and no passing the client's token through to other services. The granted scopes would still be capped by the user's role exactly as keys are here. That flow is what a production deployment adds on top of this repository; the API-side boundary stays the same.Streamable HTTP transport. Only stdio is implemented. A remote transport belongs together with OAuth.
Rate limiting per assistant, and an audit trail that records whether a person or an assistant made a change.
Persistence and multi-tenancy. The store is an array in memory and there is one clinic. In a real system the double-booking check would be a database constraint, and every query would be scoped to the tenant.
Background
I wrote up the reasoning behind this design, using a production booking system as the example, in An MCP server for a booking system: what the assistant must not reach. This repository is a fresh, generic version of the same idea with nothing taken from that product. More about my work is at pavolrasev.com.
License
MIT, copyright Pavol Rašev.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Hosted MCP server for Cliniko — patients, appointments, availability, and invoices for AI agents.
MCP server for lacita - appointment management software
Hosted MCP server for the Healthie EHR & telehealth API: patients, appointments, charting, tasks.
MCP server exposing klokin time-tracking operations (employees, time entries, stores) to AI clients.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server exposing a PostgreSQL booking datastore to MCP clients, enabling read/write operations on staff, schedules, clients, and bookings with optional human-approval workflow integration.5MIT
- AlicenseBqualityBmaintenanceMCP server for VoxFactura enabling AI assistants to query business data (invoices, expenses, project margins, clients, VAT) and create draft quotes or mark invoices paid via a scoped API, with no direct client sends.25MIT
- AlicenseAqualityDmaintenanceEnables MCP-compatible clients to act as an AI receptionist for a small medical clinic, handling appointment booking and rescheduling, patient registration, intake, reminders, and FAQ answers.151MIT
- FlicenseNot gradedqualityDmaintenanceMCP server providing guarded access to a B2B SaaS billing database (customers, subscriptions, invoices, credit notes) and live ECB exchange rates, with read-only tools and one capped, idempotent write for issuing credit notes.-