Senzii MCP Server
Connect Claude, ChatGPT, or any MCP-compatible client to Senzii's staff scheduling engine. 19 tools for managing staff, shifts, assignments, certifications, and staffing requests. OAuth 2.1 for remote, API keys for local.
Quick start
Claude (claude.ai)
Connect directly in claude.ai — no local installation needed. Claude discovers the OAuth flow automatically.
- Go to Settings → Connectors → Add custom connector
- Enter the connector URL: https://senzii.com/mcp
- Claude discovers OAuth endpoints and prompts you to log in through Senzii
- Senzii's 19 tools appear in Claude's tool list
ChatGPT (OpenAI)
Connect through Developer Mode (Plus, Pro, Business, Enterprise, and Education plans).
- Enable Developer Mode: Settings → Apps → Advanced settings → toggle Developer mode
- Create a connector: Settings → Apps → Create app
- Fill in:
- Connector name: Senzii
- Description: Manage staff scheduling, shifts, and staffing requests
- Connector URL: https://senzii.com/mcp
- Click Create — ChatGPT connects and prompts you to authenticate
- Use it: new chat → + button → More → select Senzii
💻 Local (stdio) — any MCP client
Run the senzii-mcp binary locally. Generate an API key in Settings → API Keys in the Senzii dashboard.
mcp_servers:
senzii:
command: /opt/senzii/senzii-mcp
env:
SENZII_API_KEY: "your-api-key-here"The server reads DATABASE_URL from /opt/senzii/.env automatically — no database credentials in the client config. The API key resolves your org automatically. Legacy ORG_ID env var still supported but deprecated.
OAuth 2.1 endpoints
The remote server uses OAuth 2.1 with PKCE. Clients discover endpoints automatically via RFC 9728 protected resource metadata.
| Endpoint | URL |
|---|---|
| MCP endpoint | https://senzii.com/mcp |
| Resource metadata | https://senzii.com/.well-known/oauth-protected-resource |
| Authorization server | https://senzii.com/.well-known/oauth-authorization-server |
| Dynamic client registration | https://senzii.com/oauth/register |
The WWW-Authenticate header on 401 responses points clients to the protected resource metadata URL, so MCP clients that support RFC 9728 discovery can connect without manual configuration.
Tool reference
All 19 tools are available in both remote and local mode. Tools are scoped to the authenticated organization — the AI never sees or controls the org ID. Write operations are audit-logged.
Staff
| Tool | Description | Admin | Staff | Client |
|---|---|---|---|---|
| list_staff | List all staff members in the org | ✓ | ||
| get_staff | Get one staff member by ID, including certifications and availability | ✓ | ✓ (self) | |
| create_staff | Create a new staff member with optional certifications | ✓ | ||
| delete_staff | Archive a staff member (soft delete). Blocks if confirmed assignments exist | ✓ | ||
| set_staff_availability | Replace a staff member's weekly availability schedule | ✓ | ✓ (self) | |
| add_staff_certification | Add a certification to an existing staff member | ✓ | ||
| send_staff_magic_link | Generate a one-time login link for a staff member | ✓ |
Clients
| Tool | Description | Admin | Staff | Client |
|---|---|---|---|---|
| list_clients | List all clients | ✓ | ||
| create_client | Create a new client company | ✓ | ||
| send_client_magic_link | Generate a one-time login link for a client | ✓ |
Shifts & Assignments
| Tool | Description | Admin | Staff | Client |
|---|---|---|---|---|
| list_shifts | List all shifts, optionally filtered by work site | ✓ | ✓ | |
| delete_shift | Delete a shift (blocks if confirmed assignments exist) | ✓ | ||
| list_assignments | List assignments, optionally filtered by shift | ✓ | ✓ | |
| create_assignment | Assign a staff member to a shift (checks for conflicts) | ✓ | ||
| unassign_assignment | Remove a staff member from a shift | ✓ |
Staffing Requests
| Tool | Description | Admin | Staff | Client |
|---|---|---|---|---|
| list_staffing_requests | List staffing requests, filterable by status | ✓ | ✓ (own) | |
| create_staffing_request | Submit a new staffing request for a client | ✓ | ✓ (own) | |
| convert_staffing_request | Convert an accepted request into a scheduled shift | ✓ | ||
| cancel_staffing_request | Cancel a request (also deletes any linked shift) | ✓ | ✓ (own) |
Work Sites
| Tool | Description | Admin | Staff | Client |
|---|---|---|---|---|
| list_work_sites | List all work sites | ✓ | ✓ | ✓ |
| create_work_site | Create a new work site | ✓ |
Certifications
| Tool | Description | Admin | Staff | Client |
|---|---|---|---|---|
| list_certifications | List all org-level certifications | ✓ | ✓ | ✓ |
| create_certification | Add a certification type to the org (idempotent) | ✓ | ||
| update_certification | Rename a certification type | ✓ | ||
| delete_certification | Remove a certification (also removes from all staff) | ✓ |
Dashboard & Advanced
| Tool | Description | Admin | Staff | Client |
|---|---|---|---|---|
| get_org_metrics | Dashboard metrics — open shifts, pending requests, unassigned staff | ✓ | ||
| run_sql | Execute read-only SELECT queries (admin only). INSERT, UPDATE, DELETE, DROP, ALTER, CREATE rejected | ✓ |
Security model
Org-scoped by design
The org ID is resolved server-side from the API key or JWT and injected into every database query. The AI never sees or controls it. Cross-org data access is impossible.
Role-based tool visibility
Admin, staff, and client roles see different tools. Staff can only access their own profile and assignments. Clients can only manage their own requests.
Audit-logged writes
Every create, update, delete, assign, and unassign operation logs the org, authenticated user ID, entity type, entity ID, and the resulting state.
OAuth 2.1 + PKCE
Remote mode uses OAuth 2.1 with PKCE. JWT access tokens are signed with HMAC-SHA256 and carry org_id, role, entity_id, and expiration. No tokens shared across orgs.
API keys (local mode)
Local stdio mode uses API keys generated in the dashboard. Keys are shown once at creation, stored hashed in the database, and can be revoked anytime.
Read-only SQL
The run_sql tool only accepts SELECT. All mutation keywords (INSERT, UPDATE, DELETE, DROP, ALTER, CREATE) are rejected before execution. Admin-only access.
MCP spec compatibility
Senzii's MCP server currently implements the 2025-11-25 spec via rmcp v1.8. The 2026-07-28 spec was published on July 28, 2026 with a stateless protocol core, header-based routing, and cacheable list results.
Do the 2026-07-28 changes affect Senzii?
The stateless core is a natural fit — Senzii's tools are already stateless database queries. Each call resolves the org from the auth token and runs independently. No session state is carried between calls.
The changes that would require an upgrade:
- No handshake/sessions — rmcp handles this at the transport layer; tool definitions don't change
- Header-based routing — Mcp-Method and Mcp-Name headers on HTTP requests (transport layer)
- DCR deprecated — Senzii uses dynamic client registration at /oauth/register; will migrate to CIMD when rmcp supports it
- Cacheable list results — ttlMs and cacheScope on tools/list responses (optimization, not breaking)
The 12-month deprecation window means the current server works until at least July 2027. The upgrade path is: wait for rmcp to ship stable 2026-07-28 support, then update the transport layer. Tool definitions, auth, and business logic stay the same.
Example conversation
Once connected, your AI assistant can manage scheduling through natural conversation. Here's what a typical exchange looks like in Claude:
You
What does my schedule look like this week? Any gaps?
Claude → calls get_org_metrics, list_shifts, list_assignments
You have 12 shifts this week across 3 work sites. 3 shifts are unassigned — all on Thursday at the Broad St site. You have 5 available caregivers with the right certifications who haven't been scheduled that day. Want me to assign them?
You
Yes, assign the closest ones.
Claude → calls list_staff, create_assignment ×3
Done. I assigned Maria (0.8 mi away), James (1.2 mi), and Patricia (1.5 mi) to the three Thursday shifts at Broad St. All three are pending your confirmation on the dashboard. Want me to confirm them?
Connect your assistant
Point your MCP client at https://senzii.com/mcp and authenticate. That's it.
Sign in to Senzii →