Senzii Scheduling MCP server

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:

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

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 mcpserver/tools/tools.toml — add or modify tools by editing the TOML and their handlers under mcpserver/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):

Shortened. The full README is on GitHub.