# MCP smoke test

Use this recipe after creating a disposable tenant API key.

## Run the smoke

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

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

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

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

```text
Use HollyHR whoami and summarize the available scopes.
```

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