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_test_..." \
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

When a tenant should advertise OAuth, assert the configured authorization server:

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

If authorization_servers is empty, the tenant is still in API-key preview mode. That is acceptable for developer preview, but not for connector-directory submission.

When HOLLYHR_MCP_EXPECT_OAUTH=1, the smoke also fetches:

Code
https://{workspace}.hollyhr.com/.well-known/oauth-authorization-server

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

For WorkOS/AuthKit-backed tenants, also verify DCR and resource routing:

Code
HOLLYHR_OAUTH_ISSUER_URL="https://<authkit-domain>" \
HOLLYHR_WORKOS_CONNECT_RESOURCE="https://{workspace}.hollyhr.com/api/mcp" \
pnpm mcp:workos:smoke

This smoke does not complete an interactive user login. It proves the WorkOS authorization-server metadata, public-client DCR, PKCE S256 support, that the default identity scopes are accepted, and that the configured MCP resource does not return invalid_target. HollyHR data authorization is enforced after token verification by loading the selected backing API-key actor profile and filtering it to MCP-safe scopes.

For provider diagnostics if WorkOS later supports custom data scopes, operators may set HOLLYHR_WORKOS_CONNECT_ALLOW_CUSTOM_SCOPES=1 and override HOLLYHR_WORKOS_CONNECT_SCOPES. Do not use custom-scope mode as the normal WorkOS setup path unless the authorization server advertises those scopes.

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.