Copy page

AI and MCP

MCP endpoint

HollyHR exposes a universal Model Context Protocol endpoint:

Code
https://app.hollyhr.com/api/mcp

The endpoint derives the organisation from the authenticated API-key or OAuth principal; callers cannot select it in a tool argument. Tenant-origin endpoints at https://{workspace}.hollyhr.com/api/mcp remain available for server-side integrations. Both forms are framing layers over the same public API substrate and use the same public IDs, generated contracts, request logs, rate limits, idempotency and ETags.

The official MCP Registry entry is active, and the same hosted endpoint is discoverable in the Glama connector directory and the Smithery directory. OpenAI connector version 1.1.0 is in provider review with the governed write tools included. Reads are available on every HollyHR plan; Standard and higher plans include write-capable access when a System Admin explicitly grants every required scope.

For client-specific setup, see Claude and ChatGPT. For a repeatable deployment check, see the MCP smoke test.

Agent-readable discovery is available at:

Code
https://app.hollyhr.com/auth.md

That document summarizes the current access mode, PRM URL, MCP endpoint, scope surface, and write-safety posture for human readers and agent tooling.

Authentication

Use a HollyHR public API key as a bearer token:

Code
Authorization: Bearer hhr_live_...

The MCP endpoint derives the organisation from the API key. Do not provide a tenant ID or workspace ID to any tool.

Free workspaces can create read-only credentials. Standard and higher plans can also create write-capable credentials without a separate HollyHR approval, but a System Admin must explicitly grant mcp:write plus the relevant data write scope, for example people:write or time_off:write. Existing credentials do not gain scopes automatically, and a key with REST write scopes but without mcp:write remains read-only.

HollyHR retains HOLLYHR_MCP_WRITE_MODE as an independent production emergency switch. When disabled, the server omits write tools, write prompts and write scopes from discovery rather than merely rejecting their execution.

OAuth protected-resource metadata is available under:

Code
https://app.hollyhr.com/.well-known/oauth-protected-resource/api/mcp

The endpoint returns a WWW-Authenticate challenge on unauthenticated requests with the same resource_metadata URL, so capable MCP clients can discover the protected-resource metadata automatically. The challenge also includes a narrow read-scope hint for the first useful MCP connection:

Code
WWW-Authenticate: Bearer resource_metadata="https://app.hollyhr.com/.well-known/oauth-protected-resource/api/mcp", scope="organisation:read people:read reference:read time_off:read"

The metadata scopes_supported list advertises only scopes used by executable MCP operations with explicit output projections. Excluded public API surfaces such as personal profiles, payroll exports, provider mappings, and webhook management are intentionally not advertised as MCP scopes.

The initial /api/mcp/.well-known/oauth-protected-resource route remains available as a compatibility alias, but it is not the primary discovery path.

HollyHR also operates its own OAuth 2.1 authorization server through Better Auth. It is available to every organisation without a manually created or specially named API key:

Code
https://app.hollyhr.com/api/auth

Authorization-server metadata is available at the RFC 8414 path-inserted URL:

Code
https://app.hollyhr.com/.well-known/oauth-authorization-server/api/auth

The server supports dynamic client registration, CIMD, authorization code with PKCE S256, resource indicators, refresh tokens and the canonical HollyHR public API scopes. New connections request the minimal read-first grant:

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

An OAuth token refers to a stable organisation-bound programmatic principal. Every request intersects the token scopes with the principal's current grant, active membership and permissions, plan entitlement, MCP projection and runtime emergency controls. Rotating a credential does not replace the principal or its audit history. A plan downgrade removes disallowed writes while preserving permitted reads.

When an operation needs a scope that was not granted, HollyHR returns an RFC 6750 insufficient_scope challenge for that exact scope. Capable clients can then perform incremental authorization. Write consent requires an active System Admin and an eligible plan. mcp:write never bypasses the prepare, explicit human confirmation and commit flow.

The official MCP Registry entry io.github.hollyhr/hollyhr is active. Glama publishes that record as a hosted HollyHR connector; HollyHR has claimed its ownership. Connector ownership, health testing and directory publication remain distinct states. Smithery also publishes a HollyHR directory page. Its namespace and public-domain verification are separate from HollyHR's own OAuth qualification. Direct integrations should use the canonical https://app.hollyhr.com/api/mcp endpoint. OpenAI and Anthropic use distinct synthetic reviewer identities and stable provider-review principals. Ingestion, submission, review, approval and public listing remain distinct states.

Transport

The hosted endpoint uses MCP Streamable HTTP:

Code
POST https://app.hollyhr.com/api/mcp
Accept: application/json, text/event-stream
Content-Type: application/json
Authorization: Bearer hhr_live_...
MCP-Protocol-Version: 2026-07-28

The preferred protocol is 2026-07-28. The same endpoint also accepts stateless 2025-11-25 initialize clients through the official SDK's compatibility path. Both eras use one server factory and exactly the same tools, resources, prompts, authentication and data controls.

The server is stateless for Vercel/serverless compatibility. Modern clients use protocol-native per-request envelopes; legacy clients do not need to preserve an MCP-Session-Id. Browser clients must use the same origin or a configured trusted Origin; server-to-server clients normally omit the Origin header. Authenticated legacy GET /api/mcp returns 405 Method Not Allowed because session SSE is not part of the hosted surface.

Tools

The current surface includes contract-aware discovery tools:

• list_api_operations
• get_api_operation
• call_api_operation

It also includes workflow-shaped read tools for common HR work:

• whoami
• search_people
• get_person
• get_person_context
• list_time_off
• get_time_off
• list_reference

call_api_operation executes read operations only. While the independent production write-mode switch is enabled, the server additionally registers prepare_api_write and commit_api_write. OpenAI version 1.1.0 includes those two tools in its current provider-review snapshot.

Stable tools publish output schemas and return MCP structuredContent so clients can validate common results without parsing freeform text.

whoami includes a catalogue_version fingerprint. Treat it as the current server-side MCP tool/catalogue contract version for compatibility checks.

Resources And Prompts

The server exposes read-only MCP resources for the developer guide, OpenAPI reference and HR data-handling policy, plus prompts for planning safe read-only lookups. The safe-write resource and write-review prompt are registered only when write mode is enabled. Resources and prompts contain public guidance only; tenant data is available through scoped tools, not static resources.

Governed Write Safety

Standard and higher plans include governed MCP writes without a separate HollyHR approval. Write discovery still requires the production safety switch, mcp:write, and the operation's underlying write scope.

Writes use a two-step flow:

1. Call prepare_api_write with the operation ID, path parameters, query parameters, and body.
2. Review the frozen payload and confirmation token returned by the server.
3. Call commit_api_write with the confirmation token.

The confirmation token is signed by HollyHR, tied to the API key and organisation, expires quickly, and contains a server-generated idempotency key. For conditional updates, the server captures the current ETag during preparation. The model cannot change the write body, ETag, or idempotency key between preparation and commit.

When writes are enabled, commit_api_write returns a protocol-native input_required approval request before committing. This requires a modern 2026-07-28 host. Stateless 2025 clients can read and prepare a frozen write, but commit fails closed because that era cannot carry durable host approval across per-request exchanges. If the host cannot provide approval, if the response is invalid, or if the user declines, the write fails closed. Approval never replaces the signed frozen token, principal binding, scope checks, ETag or idempotency controls.

Data Handling

MCP output is projected and sanitized before it is returned to clients. Each operation has a positive MCP output projection, so newly added upstream public API fields are omitted from MCP until they are deliberately reviewed and added to that projection:

• bearer tokens, API keys, webhook secrets, and secret-like values are redacted;
• links and document/download URLs are redacted;
• document filenames are redacted and document categories are bucketed;
• payroll, bank, tax/government, compensation, and home-address fields are redacted;
• absence category labels are bucketed to Absence by default, and time-off category IDs are omitted from MCP output to prevent category-label joins;
• time-off balance category names and category IDs are also bucketed/omitted so composite tools such as get_person_context keep the same projection ceiling.

Webhook management operations remain intentionally excluded from the MCP tool surface because their endpoint-management and secret-returning contracts have not been approved for agent execution.

Debugging

Every MCP tool call writes a public API request-log row with a route shaped like mcp:<legacy|modern>:<tool_name> and source set to mcp. This records content-free adoption telemetry without storing arguments or results. Budgeted HR-data reads also record pii_row_count.

HollyHR enforces a rolling daily MCP HR-data row ceiling per organisation. The default is 500 rows per 24 hours unless the tenant environment sets HOLLYHR_MCP_DAILY_PII_ROW_LIMIT. If a tool call would exceed the remaining budget, it fails closed with a rate-limit error before returning the rows.

Public API service calls still return structured errors that MCP tools surface as tool errors rather than protocol errors, so agents can correct missing scopes, validation mistakes, ETag preconditions, and rate-limit issues without losing the session.

Smoke Testing

Use the repository smoke harness with a disposable tenant API key when validating a deployment. It connects once with each supported protocol era:

Code
HOLLYHR_MCP_URL="https://{workspace}.hollyhr.com/api/mcp" \
HOLLYHR_MCP_TOKEN="hhr_live_..." \
pnpm mcp:smoke

When validating a tenant that should have OAuth enabled, add:

Code
HOLLYHR_MCP_EXPECT_OAUTH=1 \
HOLLYHR_MCP_EXPECT_AUTHORIZATION_SERVER="https://auth.example.com" \
HOLLYHR_MCP_URL="https://app.hollyhr.com/api/mcp" \
HOLLYHR_MCP_TOKEN="<oauth-access-token-or-api-key>" \
HOLLYHR_MCP_EXPECT_WRITES=0 \
pnpm mcp:smoke

The smoke covers protected-resource metadata, authorization-server metadata when OAuth is expected, unauthenticated discovery, the authenticated GET/SSE-disabled 405 response, SDK initialization, tools/list, whoami, and safe write preparation. Write commits are tested only when the host supports modern input_required approval and the production write-mode gate is intentionally enabled. Stateless legacy clients fail closed at commit.

For canonical OAuth metadata, DCR and PKCE readiness, run:

Code
HOLLYHR_MCP_OAUTH_RESOURCE="https://app.hollyhr.com/api/mcp" \
pnpm mcp:oauth:smoke

It checks the protected-resource and authorization-server metadata, DCR, PKCE S256 and the default read-first public API scopes. The protected provider-review workflow separately completes real sign-in, consent, token exchange, both MCP protocol eras and a reversible governed write against exact production.

For an API + MCP time-to-first-call check, use pnpm developer:ttfc:smoke from Sandbox and TTFC.