AI and MCP

AI connectors

HollyHR exposes a hosted Streamable HTTP MCP endpoint:

Code
https://{workspace}.hollyhr.com/api/mcp

Today this endpoint is a developer-preview MCP server using scoped HollyHR API keys and API-key-backed OAuth resource-server mode. Production WorkOS/AuthKit OAuth has been proven against the synthetic sandbox tenant, but HollyHR is not yet publicly launched or submitted to consumer connector galleries. 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 technically ready for the sandbox reviewer tenant; public connector-gallery submission waits for launch timing, host-specific review assets, and compliance approval.
MCP writes are default-off until DPIA/DPO approval, mcp:write, the underlying data-write scope, server write mode, and host form elicitation are all present.

Agent-readable discovery is also available at:

Code
https://{workspace}.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.

Claude Code

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

Code
claude mcp add --transport http hollyhr https://{workspace}.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 remain disabled unless the key has mcp:write, the tenant write-mode gate is enabled, and the host supports MCP form elicitation.

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 synthetic sandbox reviewer tenant. Its protected-resource metadata advertises the production WorkOS/AuthKit authorization server, and the interactive OAuth proof has passed. Enable developer mode, create a connector from ChatGPT settings, and use the concrete reviewer MCP endpoint as the connector URL:

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

HollyHR's current bearer/API-key preview is suitable for server-side developer testing and controlled design-partner trials. Do not treat arbitrary API-key headers as the final ChatGPT connector-gallery auth path. ChatGPT app distribution should wait until public launch timing, host-specific review assets, and compliance approval are complete.

For OpenAI review, prepare both a concrete reviewer endpoint and a template endpoint:

Code
https://sandbox.hollyhr.com/api/mcp
https://{workspace}.hollyhr.com/api/mcp

The reviewer tenant must use synthetic data, have any required reviewer login path prepared ahead of time, and include TTFC evidence from HOLLYHR_TTFC_OUTPUT_PATH.

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.

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_test_...
MCP-Protocol-Version: 2025-11-25

GET /api/mcp returns 405 Method Not Allowed because HollyHR does not offer a server-to-client SSE stream on the first hosted surface. Clients should use POST /api/mcp for JSON-RPC MCP messages.

Protected-resource metadata is available at:

Code
https://{workspace}.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://{workspace}.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 June 23, 2026

HollyHR MCP Reviewer demo guide