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 or MCP surface.

Provider isolation

OpenAI and Anthropic use separate fixed reviewer credentials and separate provider_reviewer principals. They may use the same synthetic Provider Review organisation, but one provider's credential or principal must never be reused to repair or qualify the other.

The public connector URL is https://app.hollyhr.com/api/mcp. The fixed fictional workspace is https://provider-review.hollyhr.com and is excluded from scheduled Sandbox resets. No customer API key or magic display name is a prerequisite for connecting.

Prepare one provider

Preparation synchronises only the selected provider's fixed login configuration on exact current main. It does not create, rotate or revoke an API key or programmatic principal.

Code
gh workflow run mcp-reviewer-readiness.yml \
  --ref main \
  -f operation=prepare \
  -f reviewer_provider=anthropic \
  -f release_sha=<exact-current-main-sha> \
  -f access_profile=confirmed-time-off-writes \
  -f access_confirmation=grant-confirmed-time-off-writes

Use openai instead of anthropic only when preparing the OpenAI reviewer. Release that exact SHA before qualification. Never run preparation merely to refresh evidence for an already configured provider.

Qualify exact production

Qualification reuses the selected provider's active stable principal and credentials. It performs no database mutation, credential rotation or membership change.

Code
gh workflow run mcp-reviewer-readiness.yml \
  --ref main \
  -f operation=qualify \
  -f reviewer_provider=anthropic \
  -f release_sha=<exact-production-current-sha> \
  -f access_profile=confirmed-time-off-writes \
  -f access_confirmation=grant-confirmed-time-off-writes

The protected workflow proves the canonical Better Auth issuer, resource-bound OAuth, DCR or CIMD, PKCE S256, browser consent, token exchange, both supported MCP protocol eras, tool discovery and a reversible governed write when the confirmed-write profile is selected. It publishes a content-free receipt bound to the exact production SHA.

The accepted profiles are:

Code
read-only + confirm-read-only-reviewer
confirmed-time-off-writes + grant-confirmed-time-off-writes

Do not describe a provider as write-capable unless its exact production qualification used the confirmed-write profile and passed.

Reviewer sign-in

The provider starts the normal OAuth connection from its client or directory. After HollyHR verifies the signed authorization request, /signin offers Use reviewer credentials. The reviewer then supplies the fixed provider email and high-entropy access code entered privately in that provider's portal.

Do not send a reviewer directly to a bare /mcp-reviewer-login URL. It requires the signed OAuth continuation and deliberately fails without it. The login has no MFA, inbox loop or automatic expiry. Its host, identity and Provider Review workspace are server-bound and cannot be selected in the request. Never commit the credential or paste it into model prompts.

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 or 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.

Prove time to first call

Run the smoke from the generated environment 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 authentication, /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 release rule

ChatGPT and Claude directory submissions require the Better Auth production path to be live and qualified for their own isolated reviewer principal. A local, staging, historical WorkOS or other provider's result is insufficient.

Pause submission if any of these are true:

• protected-resource metadata names an issuer other than https://app.hollyhr.com/api/auth;
• a genuinely empty eligible organisation cannot connect without a pre-created API key;
• initial consent requests more than the minimal read envelope;
• operation-specific write scope elevation fails;
• the selected provider lacks an exact-production qualification receipt;
• listing copy and live tool discovery describe different write postures.

Every write commit still needs the exact effective scopes, an active eligible principal, a signed frozen preparation and explicit approval from a modern host. Legacy clients that cannot provide approval fail closed.

Starter prompts

Code
Open the HollyHR Provider Review workspace and list the MCP tools and API operations available to this connection.

Code
Find the Provider Review People team and summarise each person's name, role and department using only returned fields.

Code
Show upcoming time off in Provider Review using HollyHR's generic absence labels.

Code
Prepare approval or decline of one pending standard time-off request. Confirm that HollyHR freezes the payload and asks for explicit host approval before commit; do not commit outside the synthetic Provider Review workspace.