Senzii Scheduling App & MCP Server
Staff scheduling your AI agent can operate directly. Senzii is an open-source (Apache-2.0) scheduling platform: tag-based skills matching, shift assignment with conflict detection, certification tracking, proximity ranking, and client staffing requests — exposed as MCP tools for Claude, ChatGPT, or any MCP-compatible client.
The MCP server ships inside this repo and shares the app's PostgreSQL schema — it is the scheduling engine's agent interface, not a generic database connector.
MCP tools
28 tools covering the full scheduling workflow:
| Area | Tools |
|---|---|
| Staff | list_staff get_staff create_staff delete_staff set_staff_availability add_staff_certification |
| Matching | find_candidates — rank staff for a shift by tags/certifications, proximity, availability |
| Shifts & assignments | list_shifts create_assignment unassign_assignment list_assignments delete_shift |
| Clients | list_clients create_client send_client_magic_link send_staff_magic_link |
| Staffing requests | list_staffing_requests create_staffing_request convert_staffing_request cancel_staffing_request |
| Certifications | list_certifications create_certification update_certification delete_certification |
| Work sites | list_work_sites create_work_site |
| Admin | get_org_metrics run_sql (platform-operator / super-only, SELECT-only) |
Every tool is scoped to the authenticated organization — the org ID is injected server-side into every query, so cross-org data access is impossible. Assignments are created pending by design: the agent proposes, a human confirms before the schedule goes live. That is a deliberate safety choice for regulated industries, not a limitation.
Stack
- Web framework: FastAPI
- Database: asyncpg (PostgreSQL)
- Sessions: Cookie-based, PostgreSQL-backed
- Email: Resend API (optional — only for notification features; the app runs fine without a key)
- Geocoding: Nominatim (OpenStreetMap) — free public endpoint, no API key
- MCP Server: Python MCP SDK (Streamable HTTP)
Requirements
| Component | Required? | Notes |
|---|---|---|
| PostgreSQL | Yes | Any instance works — Neon free tier is fine |
| Geocoding | Free by default | Public OpenStreetMap/Nominatim, no key (set a User-Agent per their usage policy) |
| Email (Resend) | Optional | API key only if you want email notifications |
Quick Start
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # set DATABASE_URL and SESSION_SECRET (generate: python -c "import secrets; print(secrets.token_urlsafe(48))"); add RESEND_API_KEY only for email features
uvicorn app.main:app --host 0.0.0.0 --port 3000 --reload
MCP server:
python -m mcp_server.main
Tool definitions live in mcp_server/tools/tools.toml — add or modify
tools by editing the TOML and their handlers under mcp_server/tools/.
Architecture
app/
main.py — FastAPI app, all routers wired
config.py — Environment configuration
db/ — Database layer (asyncpg pool, migrations, queries)
models/ — Pydantic schemas
middleware/ — Auth session extraction, rate limiting
routes/ — FastAPI routers (1:1 with Rust routes)
services/ — Email (Resend), Geocoding (Nominatim)
mcp_server/ — MCP server (Python MCP SDK), tools defined in tools.toml
static/ — App HTML/CSS/JS (login, dashboards, portals, SEO pages)
The marketing/landing site is a separate repo (Senzii-App/site) served from
Vercel at senzii.com. app.senzii.com serves only the app: GET / is the
sign-in page.
Deployment
Two targets, one CLI (see infra/README.md for full docs):
./infra/deploy.sh azure <flags...> # deploy to Azure (VMSS / staging VM)
./infra/deploy.sh linode <flags...> # deploy to Linode backends
./infra/deploy.sh help # list providers & flags
License
Open-source. See LICENSE.