HollyHR Developer Docs
  • Developer platform
  • GitHub
  • Sign in
  • Manage API keys
  • Start Here
  • Core API
  • AI and MCP
  • API Reference
  • Integrations
  • Recipes
  • Resources
HollyHR MCPAI connectorsReviewer demo guideAI safety and privacy
AI and MCP

AI connectors

Every AI assistant connects to the same hosted MCP endpoint:

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

There are two ways to sign in:

  • OAuth (recommended for people). The assistant opens HollyHR sign-in. You choose the organisation, then approve once: the page lists everything the assistant asked for that you can allow. That is every read your role permits and, only if it asked for them, changes, which need a System Admin on Standard or above. Anything else is held back with a one-line reason.
  • A scoped API key (for scripts and servers). A System Admin creates one under Settings > Developers > API keys and sends it as Authorization: Bearer hhr_live_.... Start with read scopes only: organisation:read people:read reference:read time_off:read.

The connection decides the organisation. No assistant can pick another one, and none should ask you for a tenant or workspace ID.

Your workspace's own address, https://{workspace}.hollyhr.com/api/mcp (or your verified custom domain), works in place of app.hollyhr.com with either method. With OAuth it always connects that workspace, so you are not asked to choose one.

Who confirms a change. Before any change, HollyHR freezes exactly what will happen and the assistant must show it to you and ask before committing it. That question is asked by your assistant, not by HollyHR: HollyHR cannot prove a person clicked approve. Only connect assistants you trust, and read the change before you agree. See AI safety and privacy.

Claude.ai

HollyHR is listed in Claude's connector directory.

  1. In Claude's connector settings, find HollyHR in the directory. Or add a custom connector with https://app.hollyhr.com/api/mcp. Your Claude plan and organisation settings must allow connectors.
  2. Select Connect. Claude opens HollyHR sign-in.
  3. Sign in, choose your organisation if asked, and approve the read access.
  4. In a chat, try: "Use HollyHR whoami, then tell me who is off next week."

The same steps are in our help centre: Connect HollyHR to Claude.

Claude Code

Add the server, then sign in from inside Claude Code:

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

Run /mcp in Claude Code, select hollyhr and choose Authenticate. Your browser opens HollyHR sign-in; approve the read access and return to Claude Code.

For a script or CI job, use a scoped API key instead of OAuth:

TerminalCode
claude mcp add --transport http hollyhr https://app.hollyhr.com/api/mcp \ --header "Authorization: Bearer $HOLLYHR_API_TOKEN"

First prompt: "Use HollyHR whoami, then list the HollyHR tools you can use."

ChatGPT and OpenAI

ChatGPT

Custom MCP servers are available on ChatGPT Business, Enterprise and Edu (Pro can connect for reads only). Your workspace admin may need to allow them first.

  1. In ChatGPT, open Plugins, select + and choose Add custom MCP server.
  2. Name it HollyHR and enter https://app.hollyhr.com/api/mcp.
  3. Choose OAuth for authentication and create the connection. ChatGPT opens HollyHR sign-in; approve the read access.
  4. Install it, then type @HollyHR in a chat to use it.

OpenAI renames these menus often. If yours differ, follow OpenAI's Connecting custom MCP servers in ChatGPT.

OpenAI API

From your own backend, pass https://app.hollyhr.com/api/mcp as the remote MCP server_url and send a scoped HollyHR API key (or an OAuth access token your application obtained) as the authorization. Keep the credential on your server, never in prompts or browser code.

Cursor

Add HollyHR to .cursor/mcp.json in your project (or ~/.cursor/mcp.json for every project). Cursor needs HollyHR's public OAuth client ID, because its automatic client registration uses a callback HollyHR's sign-in does not accept. The ID is public and has no secret; it is the one the HollyHR Cursor plugin uses. Ask for the reads below: one approval gives Cursor every read your role allows.

Code
{ "mcpServers": { "hollyhr": { "type": "http", "url": "https://app.hollyhr.com/api/mcp", "auth": { "CLIENT_ID": "SqegLqGcSRdPiiQGMMEYNsFzRJKeLjnW", "scopes": [ "organisation:read", "people:read", "reference:read", "org_units:read", "employers:read", "working_patterns:read", "time_off:read", "documents:read", "offline_access" ] } } } }

Open Cursor Settings > MCP. HollyHR shows that it needs authentication; select it and Cursor opens HollyHR sign-in. If you later want Cursor to make changes, HollyHR answers with a request for the extra write scopes, and only a System Admin on Standard or above can approve them.

To use an API key instead, add a header and keep the key in your environment, never in a committed file:

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

Review Cursor's tool approval prompts before allowing write tools.

Claude API

The Messages API's MCP connector can call HollyHR directly. Use https://app.hollyhr.com/api/mcp as the server URL, add the current Anthropic MCP connector beta header, and pass a scoped API key or an OAuth access token your application obtained as the authorization token:

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

For high-trust flows, allow only the read tools you need:

Code
whoami search_people get_person get_person_context list_time_off list_reference

Other 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

Protocol 2026-07-28 is preferred; stateless 2025-11-25 clients also work and stay read-only. GET /api/mcp returns 405, because HollyHR does not offer a server-to-client event stream.

Clients that support MCP OAuth discover sign-in from:

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

A request without a credential gets a 401 whose WWW-Authenticate header points there. A rejected or expired token gets 401 with error="invalid_token": refresh it or sign in again. auth.md summarises the same details in plain text for people and agents.

Which tool to use

QuestionTool
What can this connection do?whoami
Find someonesearch_people
Everything about one personget_person_context
Who is off, or what is waiting for approvallist_time_off
Labels and valid valueslist_reference
Org units, working patterns, holidayslist_api_operations, then call_api_operation
Make a changeprepare_api_write, then commit_api_write after you have said yes

How this relates to the API and Ask Holly

MCP runs on the same public API services as the REST API, with its own stricter output filtering, masking and daily row limits. An API scope never grants MCP access by itself.

Ask Holly, the assistant inside HollyHR, uses your own signed-in session rather than an integration credential, so an MCP or API grant never becomes an in-app permission, or the other way round.

Directory reviewers: see the Reviewer demo guide.

References

  • Claude Code MCP
  • Claude API MCP connector
  • Connecting custom MCP servers in ChatGPT
  • OpenAI: building MCP servers for ChatGPT and API integrations
  • Cursor MCP
  • MCP 2026-07-28 specification
Last modified on November 21, 2026
HollyHR MCPReviewer demo guide
On this page
  • Claude.ai
  • Claude Code
  • ChatGPT and OpenAI
    • ChatGPT
    • OpenAI API
  • Cursor
  • Claude API
  • Other MCP clients
  • Which tool to use
  • How this relates to the API and Ask Holly
  • References
JSON
JSON