Overview
TimeLeaf runs a real MCP (Model Context Protocol) server, so an MCP-compatible AI client — Claude, for example — can connect over OAuth 2.1 and query your workforce data directly. It's for managers and admins who want their AI client to answer scheduling, coverage, and leave questions instantly, and optionally propose shift and overtime actions on their behalf.
Read tools work as soon as a user connects and grants the relevant scope — no extra setup. The write tools (drafting shift assignments, sending takeover offers, opening overtime, approving requests, messaging the team) additionally require the tenant's mcp_writes feature to be turned on; a tenant that never turns it on gets a read-only MCP server, full stop.
Connecting a client
An MCP-compatible client discovers TimeLeaf's server at /api/mcp. Since TimeLeaf supports dynamic client registration, there's no manual "create an app" step first — the client registers itself on first connection. The user is then redirected to TimeLeaf's own login, followed by a consent screen where they pick exactly which scopes to grant the client. Nothing is granted beyond what's checked on that screen.
Scopes
Four scopes gate what a connection can do, on top of the standard openid/profile/email/offline_access identity scopes:
roster:read— "See who is scheduled, on call, or checked in"people:read— "See a person's contract details, hours, leave, and time-bank balance"schedule:write— "Assign shifts and offer them for takeover, and open overtime opportunities (each request needs your approval before it happens)"people:write— "Approve or deny leave requests, and send messages to your team (each request needs your approval before it happens)"
The two write scopes are only offered on the consent screen while the tenant's mcp_writes feature is on. If it's off, a client can still request them, but the consent screen won't offer or grant them.
What it can read
Eight tools, available under roster:read and people:read:
roster_for_date— who is scheduled to work between two dates, and which shift-role requirements are met or short.coverage_gaps— role coverage shortfalls (required vs. filled) between two dates.on_call_now— who is on call right now, and the next handoff, on schedules the caller can see.where_is_everyone— live job-site check-in status for the caller's direct reports on a given date.absences_and_conflicts— approved leave and active company blackouts for the caller's direct reports, overlapping a date range.person_snapshot— a person's contract fields, roles, hours this period, and time-bank balance.propose_roster— a deterministic, read-only roster proposal filling the caller's own coverage gaps for a single week. Writes nothing.simulate_absence— what happens if a direct report doesn't show up on a given date: coverage impact and a ranked, min-rest-aware replacement pool. Writes nothing.
What it can do (with your approval)
Five tools, available under schedule:write and people:write, and only when the tenant's mcp_writes feature is on:
draft_shift_assignments— commit specific shift assignments, e.g. some or all of whatpropose_rosterproposed.send_takeover_offer— offer an already-assigned shift for takeover to eligible, qualified employees.open_overtime_offer— create and publish a new overtime opportunity.approve_request— approve or deny an existing leave/time-off request.notify_team— send a plain-text message to a list of specific people.
None of these tools write immediately. Each one creates a pending approval request, and the requesting operator must approve it themselves via a card sent to Slack, Teams, or Google Chat before anything actually happens — the assignment is made, the offer goes out, the request is decided, or the message is sent only after that approval. The approval expires after 15 minutes; after that, the proposed action is dropped and has to be requested again.
Turning it on
Read access needs no extra setup beyond a normal OAuth connection and the roster:read/people:read scopes. The write side (mcp_writes) is a tenant feature flag, off by default — turn it on the same way you'd turn on any other add-on for your workspace: email [email protected] and we'll switch it on.