Copy page

Recipes

MCP smoke test

Use this recipe after creating a disposable tenant API key.

Run the smoke

Code
HOLLYHR_MCP_URL="https://{workspace}.hollyhr.com/api/mcp" \
HOLLYHR_MCP_TOKEN="hhr_live_..." \
pnpm mcp:smoke

The smoke validates:

• protected-resource metadata at the standards-shaped .well-known URL;
• unauthenticated WWW-Authenticate discovery;
• authenticated GET /api/mcp returning 405 Method Not Allowed;
• MCP SDK initialization;
• tools/list;
• whoami returning structured content;
• prepare_api_write failing safely or returning a frozen preparation payload.

OAuth activation check

Assert the canonical HollyHR authorization server:

Code
HOLLYHR_MCP_EXPECT_OAUTH=1 \
HOLLYHR_MCP_EXPECT_AUTHORIZATION_SERVER="https://app.hollyhr.com/api/auth" \
HOLLYHR_MCP_URL="https://app.hollyhr.com/api/mcp" \
HOLLYHR_MCP_TOKEN="<oauth-access-token-or-api-key>" \
pnpm mcp:smoke

An empty authorization_servers array is a deployment defect after the Better Auth cutover.

When HOLLYHR_MCP_EXPECT_OAUTH=1, the smoke also fetches:

Code
https://app.hollyhr.com/.well-known/oauth-authorization-server/api/auth

and verifies the issuer, JWKS URI, authorization endpoint, and token endpoint metadata expected by OAuth-capable MCP hosts.

Verify DCR, PKCE and the read-first scope contract:

Code
HOLLYHR_MCP_OAUTH_RESOURCE="https://app.hollyhr.com/api/mcp" \
pnpm mcp:oauth:smoke

This content-free smoke verifies the canonical protected-resource metadata, authorization-server metadata, public-client DCR, PKCE S256 and the minimal read-first HollyHR scopes. It stops before interactive login. The protected MCP Reviewer Readiness workflow completes provider-specific sign-in, consent, token exchange, tool calls and the reversible write canary against the exact production SHA.

First prompts

After connecting a real MCP host, use read-only prompts first:

Code
Use HollyHR whoami and summarize the available scopes.

Code
Find people named Maya in HollyHR and return only the structured fields the server provides.

Do not test writes in a customer tenant. MCP write commit requires host form elicitation, mcp:write, the underlying data write scope, and the tenant write-mode gate.