booking-mcp
The booking-mcp server provides an interface to a cleaning service booking system, supporting read-only access to resources, conditional write operations, workflow integration, and high-level prompts.
Resources (read-only via URI)
Active staff list:
booking://staffIndividual staff details:
booking://staff/{staff_id}Daily schedule:
booking://schedule/{date}Client info (contacts & preferences):
booking://clients/{email}
Read Tools
search_availability: Find staff with a required skill, free at a given date/time, optionally within a geographic radius.find_next_available: Search forward up to 30 days to find the first day with a free, qualified staff member at a specified time.list_staff: List active staff, optionally filtered by skill.daily_schedule: Get all appointments booked on a specific date.get_client: Look up a client by email (PII-sensitive; phone/address redacted by default).
Write Tools (require READ_ONLY=false; all require confirmation via MCP elicitation)
create_booking: Add a new client, job, and appointment (idempotent).cancel_booking: Cancel an existing appointment.reschedule_booking: Move an existing appointment to a new time.add_customer_preference: Store notes or preferences for a client.book_from_text: Parse a natural-language booking request via LLM sampling and attempt to book.
Workflow Tools (require BOOKING_AGENT_URL to be set)
book_via_workflow: Route a booking request through a human-approval workflow.get_workflow_run: Poll the status of an approval run.decide_workflow_run: Submit an approval or rejection decision.
Prompts
book_cleaning(...)andsummarize_schedule(date)for high-level interactions.
Access Control: When using HTTP, API_KEYS with granular scopes (read, write, workflow, pii) are enforced across all tools.
Integrates with a PostgreSQL database to manage booking data, providing tools for staff management, appointment scheduling, client records, and availability search.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@booking-mcp book a cleaning for next Tuesday morning"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
booking-mcp
A standalone MCP server (built on
FastMCP) that exposes the booking datastore used by
booking-agent to any MCP-compatible client. It is
decoupled from booking-agent and connects to the shared DB with its own
SQLAlchemy layer. booking-agent owns the
schema and migrations; a schema-contract test guards against drift.
Features
Resources (read-only, URI-addressed)
URI | Returns |
| active cleaners (skills + location) |
| one staff member |
| appointments on a date |
| client + contacts + saved preferences |
Read tools (readOnly, idempotent)
search_availability(service, date, time, latitude?, longitude?, radius_km?): staff who can do the job, are free at the slot, and are within range. This uses the same skill/free/geo filter as the booking engine.find_next_available(service, date, time, days?, …): first day within the window with a free, qualified cleaner.list_staff(skill?),daily_schedule(date),get_client(email).
Write tools (only when READ_ONLY=false; each asks for confirmation via MCP elicitation before writing)
create_booking(...): client + job + appointment, idempotent (deduped on a hash of all material fields).cancel_booking(appointment_id): idempotent delete.reschedule_booking(appointment_id, date, time): moves a slot and rejects staff conflicts.add_customer_preference(email, note).book_from_text(request): parses a free-text request using the client's LLM via MCP sampling, then confirms and books. Requires a sampling-capable client. Idempotent.
Writes go directly to the DB and bypass booking-agent's approval workflow. Use the workflow bridge below if you want human approval.
Workflow bridge tools (only when BOOKING_AGENT_URL is set; routes through booking-agent's human-approval workflow over HTTP)
book_via_workflow(message): start an approval run from a natural-language request and return{run_id, status}.get_workflow_run(run_id): poll status and the final response.decide_workflow_run(run_id, approve, by?, reason?): submit the approve/reject decision.
Prompts: book_cleaning(...), summarize_schedule(date).
All inputs are validated (real calendar dates/times, email format); all outputs are typed (structured content).
Related MCP server: PostgreSQL MCP Server
Quickstart
cp .env.example .env # point DATABASE_URL at the shared Postgres
make install # uv sync --dev
make dev-up # start Postgres on :5433 (Docker)
make seed # create_all + demo data (requires STANDALONE_MODE guard)
make server # run in stdio modeFor the HTTP transport on the host: make server-http (binds :8000).
Fully standalone (own DB + data). No booking-agent needed. One-shot the whole stack:
make stack-up # docker compose up (db + seed + mcp on :8000)booking-mcp-seed bootstraps the schema with create_all and populates demo staff, clients,
appointments, and preferences so the read tools return data immediately. STANDALONE_MODE=true
is required. The guard prevents accidental schema mutation against a shared DB. When sharing a
DB with booking-agent, skip the seed: booking-agent owns the canonical Alembic migrations.
API / Usage
Any MCP client takes the standard mcpServers config (the same JSON an mcp add accepts).
Local (stdio). The client launches the server as a subprocess. This is local and trusted, so no auth is required:
{
"mcpServers": {
"booking": {
"command": "/ABS/PATH/booking-mcp/.venv/bin/booking-mcp",
"env": {
"DATABASE_URL": "postgresql+psycopg://booking:booking@localhost:5432/booking",
"READ_ONLY": "true"
}
}
}
}(booking-mcp is the console script installed into the venv.)
Remote (HTTP). Connect over the streamable-HTTP transport with a Bearer key. Mint a key, then
pass the hash in API_KEYS (the server refuses to start write-enabled over HTTP without credentials):
# 1. Mint a key (prints plaintext once + the JSON record to add to API_KEYS)
# Available scopes: read, write, workflow, pii (grant only what the client needs)
booking-mcp-mintkey --client claude-desktop --scopes read,write,pii
# 2. Start the server
API_KEYS='[{"hash":"<paste-hash>","client_id":"claude-desktop","scopes":["read","write","pii"]}]' \
READ_ONLY=false booking-mcp{
"mcpServers": {
"booking": {
"url": "http://your-host:8000/mcp",
"headers": { "Authorization": "Bearer <plaintext-key>" }
}
}
}A client with no or wrong key gets 401. Scope enforcement is strict: a key without read cannot
see read tools; write/workflow/pii are additional gates on top. stdio needs no token
because it is local/trusted, so all surfaces are open.
Legacy:
AUTH_TOKEN=<token>still works as a single full-access fallback but is deprecated It grants read+write with no scope isolation. Migrate toAPI_KEYS.
Development
Common make targets:
Target | What it runs |
|
|
| Postgres container lifecycle |
| Schema + demo data ( |
| stdio server on host |
| HTTP server on host ( |
| Full containerised stack |
| Mint an API key |
| psql shell into the running container |
|
|
|
|
|
|
|
|
|
|
Testing
make test # pytest --cov=booking_mcp, requires 100% coverage to passIn-memory client: tools/resources are exercised through
fastmcp.Clientagainst the server object, with no subprocess.Testcontainer Postgres: the MCP's own
create_allschema, truncated per test (real FK/types).Schema-contract test (
test_schema_contract.py): when../booking-agent/backendis checked out, it applies booking-agent's real Alembic migrations to a fresh container and runs the MCP queries against them. This catches drift between this server's models and the owning service's schema. Skips when booking-agent isn't present.
Configuration
Copy .env.example to .env. All settings are read from the environment (or .env).
Variable | Default | Purpose |
|
| The same Postgres booking-agent uses; booking-agent owns the schema, this is a client. |
|
| Set to |
|
| Must be |
| (empty) | Preferred HTTP auth. JSON array of |
| (empty) | Deprecated: single static token granting full access (all scopes). Superseded by |
|
| Mask phone numbers (last-4 digits) and addresses ( |
|
| Redirect |
| (empty) | When set, the workflow-bridge tools are registered and POST to booking-agent so a booking goes through its full approval workflow. Decoupled: HTTP only, no import. |
|
| HTTP timeout (seconds) for workflow-bridge calls to booking-agent. |
|
| Cap on the client's LLM sampling call in |
|
| Connection pool size (sized for FastMCP's sync-tool threadpool). |
|
| Pool overflow beyond |
|
| Recycle connections after this many seconds. |
|
| Seconds to wait for a pooled connection. |
|
| Per-query statement timeout (ms). |
|
| Logging level. |
Notes
Schema ownership: in standalone mode (
STANDALONE_MODE=true),booking-mcp-seedbootstraps the schema withcreate_all. When sharing a DB with booking-agent, booking-agent owns the canonical Alembic migrations. Skip the seed entirely; the schema-contract test guards against model drift.No FastAPI/LangGraph. FastMCP brings its own (Starlette/uvicorn) HTTP stack for the HTTP transport.
MCP client features used: elicitation (write confirmation), sampling (
book_from_text). Both degrade gracefully. A client that does not support them just cannot call those tools.Per-resource content subscriptions and argument completions are not supported. Neither is first-class in this FastMCP version. Clients re-read
booking://schedule/{date}for fresh data.
License
MIT. See LICENSE.
Available Tools
5 toolsdaily_scheduleARead-onlyIdempotent
All appointments booked on a given date.
Inputs: date (required). Returns: result
find_next_availableARead-onlyIdempotent
The first day from date (within days) with a free, qualified
staff member at time — or null if none in the window.
Inputs: service (required), date (required), time (required), days, +3 more. Returns: result
get_clientARead-onlyIdempotent
Look up a client by email with their contacts and saved preferences. Phone and address are masked by default (REDACT_PII=true); set false only for internal/admin tooling backed by a scoped token.
Inputs: email (required). Returns: result
list_staffARead-onlyIdempotent
List active staff, optionally filtered by a skill.
Inputs: skill. Returns: result
search_availabilityARead-onlyIdempotent
Find staff who can do the service, are free at the slot, and (if coords given) within range. Same skill/free/geo filter the booking engine uses.
Inputs: service (required), date (required), time (required), latitude, +2 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clearly distinct purpose: daily_schedule shows appointments, find_next_available finds next slot, get_client looks up client info, list_staff lists staff, search_availability finds matching staff. No overlapping functionality.
All tool names use snake_case, and most follow a verb_noun pattern (get_client, list_staff, search_availability). However, daily_schedule uses a noun_noun pattern, creating a minor inconsistency.
Five tools is an appropriate number for a booking server, covering core read operations without being excessive or insufficient.
The tool set lacks any mutating operations such as create_booking or update_appointment, making it impossible to complete a booking workflow. This is a significant gap for a booking server.
Maintenance
Related MCP Connectors
Hosted MCP server for Cliniko — patients, appointments, availability, and invoices for AI agents.
MCP server for lacita - appointment management software
MCP server exposing klokin time-tracking operations (employees, time entries, stores) to AI clients.
MassageBook massage practice management MCP server: book appointment, reschedule appointment.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server that connects to a PostgreSQL database to manage appointment scheduling.-
- AlicenseNot gradedqualityDmaintenanceAn open-source MCP server for PostgreSQL schema introspection and guarded read-only queries. It enables MCP clients to discover schemas, tables, columns, indexes, relationships, and safe queryable data from a configured PostgreSQL database.8 npmMIT
- AlicenseAqualityDmaintenanceA production-grade MCP server that gives AI agents safe, authenticated access to a PostgreSQL database.3MIT
- FlicenseNot gradedqualityDmaintenanceA production-grade MCP server over Postgres, providing secure data operations with tenant isolation, exact-once mutations, loop-aware rate limiting, and a tamper-evident audit trail.1-