MCP endpoint
HollyHR exposes a universal Model Context Protocol endpoint:
Code
The endpoint derives the organisation from the authenticated API-key or OAuth
principal; callers cannot select it in a tool argument. Workspace endpoints at
https://{workspace}.hollyhr.com/api/mcp, or your verified custom domain,
accept the same API keys and OAuth (see Workspace URLs).
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.
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
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
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
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
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
Authorization-server metadata is available at the RFC 8414 path-inserted URL:
Code
The server supports dynamic client registration, CIMD, authorization code with PKCE S256, resource indicators, refresh tokens and the canonical HollyHR public API scopes. The unauthenticated challenge names every MCP read, and a client that registers without a scope gets them by default:
Code
One consent grants everything the app asked for that the person may grant
now: every read their role and plan allow and, if the app asked for them,
writes for a System Admin on a plan with changes, each listed on the consent
page. Anything else is held back with a one-line reason, and the token's
scope says what was granted. A later 403 insufficient_scope names every
scope the connection still needs, so asking again keeps what it already has.
A dynamic registration without application_type is treated as a web client,
and web clients must use https redirect URIs on a public host. Desktop and
command-line clients that receive the callback on a loopback address
(http://127.0.0.1, http://[::1] or http://localhost, any port) or on a
private-use scheme must register with "application_type": "native". A
private-use scheme must be a reverse-domain name with no // authority, such
as com.example.app:/oauth/callback (RFC 8252 section 7.1). Otherwise
registration fails with 400 invalid_redirect_uri and an error_description
naming the refused URI. Send the registration as a JSON object with
Content-Type: application/json; a body that is not valid JSON fails with
400 invalid_client_metadata. Client ID Metadata Documents are not affected:
a document that omits application_type is validated as a native client.
Workspace URLs
OAuth also works when a client is given a workspace URL such as
https://acme.hollyhr.com/api/mcp. That host's protected-resource metadata
names the workspace URL as the resource and the same
https://app.hollyhr.com/api/auth issuer. The authorization server accepts
that exact URL as an alias of https://app.hollyhr.com/api/mcp:
- the connection always connects that workspace, with no organisation chooser, and fails if the person signing in is not an active member of it;
- the access token's audience is still
https://app.hollyhr.com/api/mcp; - the workspace URL accepts only that workspace's OAuth tokens, while the universal endpoint accepts a token for any workspace.
Other hosts, such as developers.hollyhr.com or a subdomain no workspace
uses, publish metadata without authorization_servers and accept API keys
only.
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. 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
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_operationsget_api_operationcall_api_operation
It also includes workflow-shaped read tools for common HR work:
whoamisearch_peopleget_personget_person_contextlist_time_offget_time_offlist_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:
- Call
prepare_api_writewith the operation ID, path parameters, query parameters, and body. - Review the frozen payload and confirmation token returned by the server.
- Call
commit_api_writewith 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
Absenceby 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_contextkeep 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
When validating a tenant that should have OAuth enabled, add:
Code
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
It checks the protected-resource and authorization-server metadata, DCR, PKCE S256 and that every MCP read is advertised. 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.