# HollyHR

HollyHR is a UK SME HR system of record with a hosted MCP endpoint and a scoped public API.

## Status

- Current access mode: scoped bearer API keys and HollyHR OAuth 2.1 access tokens.
- OAuth authorization server: available through HollyHR's Better Auth deployment.
- MCP transport: Streamable HTTP over `POST https://app.hollyhr.com/api/mcp`.
- Preferred MCP protocol version: `2026-07-28`.
- Supported MCP protocol versions: `2026-07-28`, `2025-11-25`.
- Governed MCP writes: enabled for actors carrying `mcp:write` plus the operation scope.

## Discovery

- Protected Resource Metadata: https://app.hollyhr.com/.well-known/oauth-protected-resource/api/mcp
- Authorization Server Metadata: https://app.hollyhr.com/.well-known/oauth-authorization-server/api/auth
- MCP endpoint: https://app.hollyhr.com/api/mcp
- Developer docs: https://developers.hollyhr.com/mcp
- AI connector guide: https://developers.hollyhr.com/ai-connectors

## Agent registration

OAuth clients start with the protected-resource metadata above. HollyHR handles sign-in, organisation selection, one consent for everything the person may allow (every read their role permits, and writes for a System Admin on a plan with changes) and standards-native scope elevation, without requiring a pre-created API key.

Agents should use the protected-resource and authorization-server metadata as the machine-readable source of truth. This document is the prose companion for human and agent readers.

## MCP scopes

- `organisation:read`
- `people:read`
- `people:write`
- `reference:read`
- `org_units:read`
- `employers:read`
- `working_patterns:read`
- `time_off:read`
- `time_off:write`
- `time_off:balance:write`
- `documents:read`
- `mcp:write`

## Data and write safety

- Tenant identity comes from the credential, never from tool input.
- MCP read outputs use positive projections and redact sensitive HR fields.
- MCP writes require `mcp:write`, ordinary write scopes, server-side write mode, frozen payloads, ETags/idempotency where applicable, host form elicitation, and a human reason for lifecycle writes.
- Absence categories and document filenames are bucketed or redacted in MCP output.

## Contact

For integration help, use https://developers.hollyhr.com/support.
