Copy page

Recipes

Safe MCP leave booking

Use this recipe when an AI client should help prepare a leave request without silently changing HR data. Governed MCP writes are included on Standard and higher plans without a HollyHR approval step. commit_api_write still requires an explicit System Admin grant of mcp:write and time_off:write, the production HOLLYHR_MCP_WRITE_MODE=enabled safety switch, and a host that supports MCP form elicitation.

If any gate is missing, use the flow as a read-only planning assistant and ask a human to book the leave in HollyHR or through the REST API.

What it uses

• whoami
• search_people
• list_reference
• list_time_off
• prepare_api_write
• commit_api_write, only after the write gates above are satisfied

The underlying REST operation is createTimeOff on POST /time-off.

Scopes

Start read-only:

Code
organisation:read people:read reference:read time_off:read

For a Standard or higher tenant that needs this workflow, explicitly add:

Code
time_off:write mcp:write

Do not add people:personal:read, payroll, document, or webhook-management scopes for this workflow.

Prompt

Code
Use HollyHR to prepare a pending time-off request for Pat Example for 2026-07-01
to 2026-07-03.

Rules:
- Use whoami first.
- Find the person with search_people; do not ask for a tenant id.
- Read time-off reference data and existing overlapping requests.
- Do not expose or infer health, sickness, notes, or private reasons.
- If writes are unavailable, stop after showing the exact proposed request.
- If writes are available, call prepare_api_write only after showing the user the
  person, category, dates, and half-day flags.
- Call commit_api_write only after the MCP host displays the approval form and
  the user approves it.

Preparation payload

prepare_api_write should freeze the createTimeOff request body:

Code
{
  "operation_id": "createTimeOff",
  "args": {
    "body": {
      "person_id": "7k3m9q2vx6rt",
      "category_id": "toc_...",
      "start_date": "2026-07-01",
      "end_date": "2026-07-03",
      "is_from_half_day": false,
      "is_to_half_day": false
    }
  }
}

The server signs the frozen payload, captures the idempotency key, and returns a short-lived confirmation token. The model cannot change the person, dates, category, half-day flags, ETag, or idempotency key between preparation and commit.

Safety checks

• Confirm the person from work identity fields, not home or personal details.
• Check existing list_time_off results for the requested date window.
• Use the public category id returned by reference data.
• Keep free-text reasons out of booking requests. Booking create/update does not accept notes, approval comments, rejection reasons or health details. A decline may include the bounded private response_note; never put health or medical details in it.
• Approval and decline use the separate approveTimeOff and declineTimeOff operation IDs. Prepare them only after reading the current request and showing the user the person, dates, category and proposed decision. Preparation freezes the current ETag; commit still requires the host's per-action human confirmation. Never use the decision operations for sickness records.

Failure modes

If prepare_api_write reports write mode disabled, missing mcp:write, or missing time_off:write, show the proposed request and stop. A System Admin can review plan eligibility and grant only the scopes the workflow needs.

If commit_api_write reports that the host cannot fulfil input_required approval, switch the client to 2026-07-28 or use a human-run REST/in-app flow. Stateless legacy clients can prepare but cannot commit. Do not ask the model to "just do it" through call_api_operation; generic MCP calls are read-only.