# AI connectors

HollyHR exposes a hosted Streamable HTTP MCP endpoint:

```text
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:

```text
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:

```bash
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:

```text
organisation:read people:read reference:read time_off:read
```

First prompt:

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

Then try:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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](/reviewer-demo-handoff) to generate the tenant evidence
and [Sandbox and TTFC](/sandbox) 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:

```json
{
  "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:

```bash
export HOLLYHR_MCP_TOKEN="hhr_live_..."
```

Start with:

```text
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:

```text
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:

```text
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:

```text
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:

```text
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

- [Claude Code MCP](https://docs.anthropic.com/en/docs/claude-code/mcp)
- [Claude API MCP connector](https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector)
- [OpenAI Apps SDK: connect from ChatGPT](https://developers.openai.com/apps-sdk/deploy/connect-chatgpt)
- [OpenAI: building MCP servers for ChatGPT and API integrations](https://developers.openai.com/api/docs/mcp)
- [Cursor MCP](https://cursor.com/docs/mcp)
- [MCP Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports)