AI and MCP

AI connectors

HollyHR exposes a hosted Streamable HTTP MCP endpoint:

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

This universal endpoint accepts scoped HollyHR API keys and delegated OAuth 2.1 tokens issued by HollyHR through Better Auth. The authenticated principal, not the hostname or a tool argument, selects the workspace. Per-workspace endpoints remain available for server-side integrations at https://{workspace}.hollyhr.com/api/mcp. The official MCP Registry entry is active. Do not hand a production API key to an untrusted host.

Use the current preview as a tenant-scoped developer integration:

API-key bearer auth is available today.
OAuth uses HollyHR's canonical https://app.hollyhr.com/api/auth issuer with read-first consent and granular step-up scopes.
Reads are available on every plan. Standard and higher plans include governed writes when a System Admin explicitly selects mcp:write and every underlying write scope; the global production switch and host confirmation still apply.

Agent-readable discovery is also available at:

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

The auth.md document is a human-and-agent readable companion to the protected resource metadata. The PRM remains the machine-readable source of truth.

Directory Status

Official MCP Registry: io.github.hollyhr/hollyhr version 1.0.0 is an active public entry for the universal endpoint.
Anthropic: the custom Claude connector and read-only synthetic-tenant query are proven. Public directory submission requires an Anthropic Team or Enterprise organisation Owner; the directory form has not yet been submitted.
OpenAI: business and production-domain verification are complete. Version 1.1.0, including the separate prepare and confirmed-commit write tools, was submitted on 27 August 2026 and is in provider review. It is not yet approved or publicly listed. The rejected 1.0.0 submission is historical.

Treat custom-connector testing, submission, provider review, approval and public listing as separate states.

Claude.ai

For customer setup, see Connect HollyHR to Claude.

Use the universal URL when adding HollyHR as a custom connector or when testing the directory candidate:

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

Claude discovers HollyHR OAuth from the protected-resource metadata. A normal customer signs in, selects an organisation where needed and approves the exact read-first scopes. The fixed Anthropic reviewer login binds only Anthropic's isolated principal to the synthetic provider-review workspace. Write-capable connections require Standard or higher, explicit System Admin scopes and a confirmation-capable host. Claude cannot request a workspace identifier.

Claude Code

Claude Code supports remote HTTP MCP servers. Add HollyHR with:

Code
claude mcp add --transport http hollyhr https://app.hollyhr.com/api/mcp

Use a scoped API key when the host prompts for credentials, or configure the host's supported bearer-header mechanism if it provides one. Start with a read-only key:

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

First prompt:

Code
Use HollyHR whoami, then tell me which MCP tools are available.

Then try:

Code
Show a read-only summary of people in the Engineering department.

Writes are visible only when the key has mcp:write, the operation scope and the global write-mode gate is enabled. A modern 2026-07-28 host must support input_required approval. Stateless 2025 clients remain read-only.

Claude API

Claude's MCP connector lets the Messages API connect directly to remote MCP servers. Use the HollyHR endpoint as the remote server URL and include the current Anthropic MCP connector beta header:

Code
anthropic-beta: mcp-client-2025-11-20

Configure HollyHR as a URL MCP server from your server-side application. Keep the bearer token in integration configuration, not in model prompts or browser code. During Public Preview this can be a scoped HollyHR API key. For OAuth-backed connectors, your application must complete the OAuth flow and pass the resulting access token as the MCP authorization token.

Use a toolset allowlist for high-trust flows first:

Code
whoami
search_people
get_person
get_person_context
list_time_off
list_reference

ChatGPT and OpenAI

OpenAI supports remote MCP servers in ChatGPT apps/connectors and API tool flows, but the auth expectations differ by surface.

For server-side OpenAI API usage, use OpenAI's remote MCP tool support from your own backend and pass the HollyHR MCP server_url. Your backend owns the HollyHR credential and can pass an API-key bearer token or OAuth access token according to your tenant's configured auth mode. Never put HollyHR credentials in prompts, browser code, or user-editable connector metadata.

For ChatGPT app/connector developer testing, use the universal endpoint. Its protected-resource metadata advertises HollyHR's first-party Better Auth authorization server. The fixed OpenAI reviewer login binds only OpenAI's isolated principal to the synthetic provider-review workspace without accepting a tenant from the request:

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

HollyHR's bearer/API-key mode remains suitable for server-side integrations. The ChatGPT directory candidate uses the universal OAuth path, fixed synthetic reviewer login and a bounded provider principal. Its read-first grant can step up to time_off:write and mcp:write; arbitrary API-key headers are not its directory auth contract.

For OpenAI review, submit the universal endpoint rather than a tenant URL template. The reviewer tenant uses synthetic data, a fixed no-MFA reviewer login prepared ahead of time, and current content-free TTFC evidence.

Directory reviewers also need enough app metadata to verify the connector without extra correspondence: privacy URL, support contact, screenshots or recorded prompts where requested, status page URL, and test prompts/responses. Use Reviewer demo guide to generate the tenant evidence and Sandbox and TTFC to produce the smoke output.

Relationship To The API And Holly

The REST API and MCP reuse the same generated operation metadata and public API services. MCP adds its own positive projections, masking, row budgets and provider-facing tool contracts; an API scope or domain-capability mapping never grants MCP authority by itself.

Ask Holly is the first-party in-app agent and uses the signed-in member's session principal rather than an organisation integration credential. Stable domain-capability identifiers and selected domain services are shared across all three surfaces, but their principals and output projections remain deliberately separate. This prevents an API or MCP integration grant from silently becoming an in-app employee permission, or vice versa.

Cursor

Cursor supports MCP servers through project or global mcp.json files. For a project-local setup, create .cursor/mcp.json in the project that should use HollyHR:


Code
{
  "mcpServers": {
    "hollyhr": {
      "url": "https://{workspace}.hollyhr.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:HOLLYHR_MCP_TOKEN}"
      }
    }
  }
}

Then export a scoped read-only token in your shell or secrets manager:

Code
export HOLLYHR_MCP_TOKEN="hhr_live_..."

Start with:

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

Cursor can also use OAuth for remote MCP servers. Leave static headers out and let Cursor discover HollyHR's canonical authorization server from the protected-resource metadata when the client supports remote MCP OAuth.

Useful first prompt:

Code
Confirm which HollyHR workspace is connected and list the available tools. Then
show a read-only summary of people in the Engineering department.

Keep the token out of committed mcp.json files. Use environment-variable interpolation for API keys and review Cursor's tool approval UI before allowing write-capable tools.

Generic MCP clients

Use Streamable HTTP with these headers:

Code
Accept: application/json, text/event-stream
Content-Type: application/json
Authorization: Bearer hhr_live_...
MCP-Protocol-Version: 2026-07-28

GET /api/mcp returns 405 Method Not Allowed because HollyHR does not offer a server-to-client SSE stream on the hosted surface. Protocol 2026-07-28 is preferred. HollyHR also accepts stateless 2025-11-25 initialize clients at the same POST /api/mcp endpoint. The compatibility path uses the same tools and governed data boundary; it is not a second API.

Protected-resource metadata is available at:

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

Unauthenticated MCP requests return a WWW-Authenticate header with that metadata URL.

Clients discover the authorization server through:

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

The operator contract is in docs/runbooks/better-auth-mcp-oauth.md. OpenAI and Anthropic have separate reviewer credentials and stable principals. An empty authorization_servers list is a deployment defect after the Better Auth cutover.

References

Last modified on October 6, 2026

HollyHR MCP Reviewer demo guide