chmonitor

Use Clerk when you want browser-based sign-in with user accounts. The browser authenticates via a Clerk __session cookie, verified networklessly on each /api/v1/* call. The MCP server additionally accepts Clerk OAuth bearer tokens.

How it works

  • Browser clients sign in through Clerk’s hosted UI.
  • The __session cookie is sent automatically same-origin and verified on the server using the Clerk secret key — no network call per request.
  • The publishable key must be present at build time so the client-side gate enables Clerk UI (sign-in button, user menu). The secret key is read at runtime.

Configuration

## Server-side (runtime)
CHM_AUTH_PROVIDER=clerk
CLERK_SECRET_KEY=sk_live_...

## Client-side (build-time inlined — TanStack app)
VITE_AUTH_PROVIDER=clerk
VITE_CLERK_PUBLISHABLE_KEY=pk_live_...

Legacy Next.js app: use NEXT_PUBLIC_AUTH_PROVIDER and NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY instead of the VITE_* equivalents.

Setup steps

  1. Create a Clerk application at clerk.com.
  2. Copy the Publishable key (pk_live_...) and Secret key (sk_live_...) from the Clerk dashboard.
  3. Set the build-time env vars before building the client: 
    VITE_AUTH_PROVIDER=clerk
VITE_CLERK_PUBLISHABLE_KEY=pk_live_...
  4. Set the runtime env vars on the server (or as Worker secrets): 
    CHM_AUTH_PROVIDER=clerk
wrangler secret put CLERK_SECRET_KEY   # paste sk_live_...
  5. Rebuild and redeploy. The sign-in button appears in the header.

Clerk OAuth for MCP

The MCP server at /api/mcp also accepts Clerk OAuth bearer tokens. Clerk acts as the authorization server (login, consent, dynamic client registration); chmonitor is the resource server and verifies tokens via Clerk’s REST introspection. This lets MCP clients use an OAuth flow instead of a chm_ API key. It uses the same CLERK_SECRET_KEY — no extra configuration needed.

See MCP Server for connection details.

Gating features to authenticated users

By default, features remain public even with Clerk enabled. To require sign-in for a feature:

CHM_FEATURE_AGENT_ACCESS=authenticated

See Feature Permissions for all feature ids and options.