Copy page

AI and MCP

Reviewer demo guide

Use this handoff when a directory reviewer, integration partner, or design partner needs to test HollyHR without touching a real customer tenant.

The reviewer tenant must be synthetic, resettable, and usable without a manual signup loop. Do not ask reviewers to complete MFA, SMS verification, email verification, or customer onboarding before they can test the API/MCP surface.

Create the tenant

Provision a synthetic tenant and write credentials to an ignored env file:

Code
HOLLYHR_DATABASE_TARGET_PROOF="postgresql://..." \
HOLLYHR_ALLOW_DEVELOPER_DEMO_LOGIN_LINKS=1 \
pnpm developer:demo:provision -- \
  --create-api-key \
  --create-login-links \
  --login-personas=hrAdmin,manager,directReport \
  --output-json=./demo-tenant.json \
  --output-env=./demo-tenant.env

For production reviewer credentials, derive the target proof from a fresh Vercel Production env pull instead of local .env. Use the internal docs/runbooks/workos-authkit-mcp-oauth.md runbook for the exact operator command. The current hosted reviewer workspace is https://sandbox.hollyhr.com.

demo-tenant.json is the non-secret reviewer manifest. It includes:

• the concrete API and MCP endpoints;
• the endpoint template for directory forms;
• the seeded scenario name and reset/reseed evidence;
• the reviewer login model and requested personas;
• safe starter prompts for Claude, ChatGPT, and generic MCP hosts;
• commands for TTFC and submission-pack generation.
• the public status page URL for service-health checks during review.

demo-tenant.env is secret. It contains the reveal-once API/MCP token and any single-use reviewer login links. Do not commit it or paste it into model prompts.

Prove time to first call

Run the smoke from the generated env file:

Code
dotenv -e ./demo-tenant.env -- sh -c 'HOLLYHR_TTFC_OUTPUT_PATH=./ttfc-evidence.json pnpm developer:ttfc:smoke'

Attach ttfc-evidence.json to the internal submission bundle. It proves:

• REST auth, /me, people, and metadata;
• MCP protected-resource metadata and unauthenticated challenge discovery;
• authenticated GET /api/mcp returning 405 Method Not Allowed;
• MCP initialize, tools/list, and whoami;
• request IDs and rate-limit headers where returned by the live endpoint.

Generate the submission pack

Build the reviewer and partner pack:

Code
pnpm developer:submission:pack

The generated files are local evidence outputs:

Code
dist/developer-platform/submission-pack.json
dist/developer-platform/submission-pack.md

They are intentionally not committed. The tracked source of truth is docs/api/developer-platform-submission-evidence.json.

Host-specific blockers

Server-side Claude API, Cursor, and generic MCP clients can use the developer-preview bearer-token flow when the token is stored outside prompts and browser code.

ChatGPT app/connector submission and public connector directories require the production OAuth path to be live and proven. Do not submit while the protected resource metadata for the reviewer tenant returns an empty authorization_servers array.

Production MCP writes remain blocked until DPIA/DPO approval, mcp:write, the underlying write scope, HOLLYHR_MCP_WRITE_MODE=enabled, and host form elicitation are all in place.

Starter prompts

Use these examples when a reviewer asks what to try first. They are written as human review tasks rather than secret test commands, and each one exercises a specific safety property of the hosted MCP server.

Code
Open the HollyHR sandbox and list the MCP tools available to this connection.

Code
Find the sandbox People team and summarize each person's name, role, and department using only returned fields.

Code
Show upcoming time off in the sandbox using HollyHR's generic absence labels.

Code
Start a sample leave-request flow and stop at the human approval prompt before committing a write.