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. HollyHR's MCP writes are default-off in production: commit_api_write requires mcp:write, time_off:write, the tenant HOLLYHR_MCP_WRITE_MODE=enabled gate, 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 deliberately enabled

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 controlled write tenant only, 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": "person_...",
      "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 the request. The beta API does not accept notes, approval comments, rejection reasons, or health details.
• Do not approve or reject requests through MCP. The beta write surface creates or updates pending requests only.

Failure modes

If prepare_api_write reports write mode disabled, missing mcp:write, or missing time_off:write, that is expected for normal production tenants. Show the proposed request and stop.

If commit_api_write reports that the host does not support form elicitation, switch to a human-run REST or in-app flow. Do not ask the model to "just do it" through call_api_operation; generic MCP calls are read-only.