AI and MCP

AI connectors

HollyHR exposes a hosted Streamable HTTP MCP endpoint:

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

This universal endpoint uses scoped HollyHR API keys and API-key-backed OAuth resource-server mode. The authenticated principal—not the hostname—selects the workspace. Per-workspace endpoints remain available for server-side integrations at https://{workspace}.hollyhr.com/api/mcp. Production WorkOS/AuthKit OAuth has been proven against the synthetic Sandbox tenant. Anthropic directory preparation and OpenAI provider review are in progress. Claude, OpenAI Responses and Codex compatibility have been proven against the fixed synthetic Sandbox reviewer path. 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/WorkOS is ready for the Sandbox reviewer tenant.
The initial directory connector is read-only. Governed writes remain disabled and are not included in its scopes, tools or reviewer prompts.

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

Anthropic: the custom Claude connector and read-only Sandbox 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.0.0 was submitted on 1 August 2026 and is in provider review; it is not yet approved or publicly listed.

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

Claude.ai

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 WorkOS/AuthKit OAuth from the protected-resource metadata. The fixed reviewer login binds the resulting principal to the synthetic Sandbox workspace. The current directory candidate exposes only read tools; Claude cannot request a workspace identifier or discover write operations.

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. For developer 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 the production WorkOS/AuthKit authorization server. The fixed provider-review login then binds the session to the synthetic Sandbox 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 developer testing and controlled design-partner trials. The ChatGPT directory candidate instead uses the universal OAuth path, fixed synthetic reviewer login and read-only backing actor; arbitrary API-key headers are not its gallery 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. For HollyHR, leave static headers out only for tenants whose WorkOS/AuthKit OAuth metadata is configured and whose protected-resource metadata advertises a usable authorization server.

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.

When WorkOS/AuthKit-backed OAuth is enabled, clients can also discover the authorization server through:

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

HollyHR operators configure WorkOS/AuthKit using the internal runbook at docs/runbooks/workos-authkit-mcp-oauth.md. The sandbox reviewer tenant is configured; tenants without OAuth values intentionally return an empty authorization_servers list.

References

Last modified on August 21, 2026

HollyHR MCP Reviewer demo guide