AI connectors
Every AI assistant connects to the same hosted MCP endpoint:
Code
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.
- 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. - Select Connect. Claude opens HollyHR sign-in.
- Sign in, choose your organisation if asked, and approve the read access.
- 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:
Code
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:
Code
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.
- In ChatGPT, open Plugins, select + and choose Add custom MCP server.
- Name it HollyHR and enter
https://app.hollyhr.com/api/mcp. - Choose OAuth for authentication and create the connection. ChatGPT opens HollyHR sign-in; approve the read access.
- 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
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
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
For high-trust flows, allow only the read tools you need:
Code
Other MCP clients
Use Streamable HTTP with these headers:
Code
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
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
| Question | Tool |
|---|---|
| What can this connection do? | whoami |
| Find someone | search_people |
| Everything about one person | get_person_context |
| Who is off, or what is waiting for approval | list_time_off |
| Labels and valid values | list_reference |
| Org units, working patterns, holidays | list_api_operations, then call_api_operation |
| Make a change | prepare_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