The Game Pensieve — MCP Sidecar

A read-only MCP (Model Context Protocol) server for The Game Pensieve API. It is a sidecar proxy: a separate TypeScript process that exposes MCP tools over Streamable HTTP and fulfills them by calling the existing REST API over HTTP. AI hosts (Claude Desktop, Claude Code, claude.ai connectors) connect to it to answer natural-language questions about a game collection.

The API it proxies lives in a separate repo, the-game-pensieve-api; the references below to the compose files (dockerCompose/compose.unsecured.yaml / dockerCompose/compose.secured.yaml for development, dockerCompose/compose.production.yaml for production), Caddyfile, keycloak/, and the realm import all point into that repo.

OAuth

When enforcing, the sidecar validates the incoming Authorization: Bearer JWT (signature via JWKS — RS256 only, pinned explicitly — plus iss, aud, and the required scopes) with jose, publishes Protected Resource Metadata (RFC 9728) at /.well-known/oauth-protected-resource[/mcp], and challenges missing/invalid tokens with 401 + WWW-Authenticate: Bearer resource_metadata="…". Valid tokens are forwarded to the API, which independently validates them and scopes the request to the token owner (Keycloak sub → owner → RLS). Audience (aud) is validated on both sides — the sidecar and the API — to block confused-deputy replay even though the API is on a private network.

Enforcement is gated by MCP_AUTH_MODE:

In auto mode the startup heartbeat probe is retried (MCP_HEARTBEAT_RETRIES × MCP_HEARTBEAT_RETRY_DELAY_MS) so a sidecar that boots before the backend is ready doesn't latch enforcement off from a single failed probe. If the backend is still unreachable after the retries and OAuth is configured, the sidecar fails closed (enforces) rather than serving /mcp tokenless.

iss is validated against the canonical, host-facing issuer, while keys are fetched from MCP_OAUTH_JWKS_URI — the internal keycloak:8080 URL on the docker-compose network (in prod both are the public https://… URLs). /healthz and the metadata endpoints stay public.

Scope enforcement

A token that verifies is not automatically authorized. After jwtVerify the sidecar requires every scope in MCP_OAUTH_REQUIRED_SCOPES (defaulting to whatever MCP_OAUTH_SCOPES advertises) to be present in the token's space-delimited scope claim. A verified but under-scoped token gets:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope",
  error_description="The access token is missing the required scope(s): pensieve:read",
  scope="pensieve:read", resource_metadata="https://…/.well-known/oauth-protected-resource/mcp"

403 rather than 401, per RFC 6750 §3.1: the credential is genuine, so re-presenting it would fail identically, and a client that reads 401 as "start the OAuth flow" would loop. The scope parameter tells the client what to ask for next; resource_metadata still lets it rediscover the authorization server.

Why this is not redundant with the audience check: Keycloak does not honor the RFC 8707 resource parameter, so the /mcp audience is attached by a mapper on the pensieve:read client scope. In the production realm that scope is deliberately not a realm default, so audience and scope now travel together and are checked together. Set MCP_OAUTH_REQUIRED_SCOPES="" to disable the check — the escape hatch when a connector cannot be granted the scope in Keycloak — which leaves audience as the only gate.

Related MCP server: GPT MCP Service

Tools

All tools are read-only. Filters are { field, operator, operand } objects; call get_available_filters first to learn the valid combinations. An empty/omitted filter list returns everything.

Configuration

Develop

Requires Node 20+. All configuration is via environment variables — see the table above and the annotated .env.example.

npm install
npm run dev        # tsx watch, reads .env-style vars from the environment
npm test           # vitest (hermetic; no backend needed)
npm run typecheck
npm run build && npm start

On startup the server probes GET /v1/heartbeat and logs the backend's secureMode.

For architecture, request flow, testing patterns, and how to add a tool, see documentation/DevDocumentation.md.

Connect a host

Local (tokenless)

Bring up the API in permit-all mode (default local/docker profile) — no auth, the full read surface is open:

API_BASE_URL=http://localhost:8080/v1 PORT=8090 npm start
npm run inspect                                 # MCP Inspector — point it at http://localhost:8090/mcp
# or register with a host (no token needed):
claude mcp add --transport http pensieve http://localhost:8090/mcp

MCP Inspector

MCP Inspector is the official debugging GUI for MCP servers, installed here as a dev dependency (npm run inspect). It connects as a host would — but with you driving instead of a model — which makes it the quickest way to see how the sidecar is put together:

• Tool discovery — the full tool list with names, descriptions, and Zod-derived input schemas, exactly as a host's model sees them.

• Manual calls — invoke any tool from a form and inspect the result, including isError responses (e.g. the 402/403 capability responses surfaced from the backend).

• Raw wire traffic — every JSON-RPC request/response over the Streamable HTTP transport, useful when debugging the handshake or a host integration.

Select transport Streamable HTTP, URL http://localhost:8090/mcp. Against a secured backend it prompts for the OAuth flow.

Secured (OAuth 2.1)

When the backend runs the secured profile the sidecar enforces OAuth. A host discovers the authorization server from the sidecar's protected-resource metadata and runs the standard OAuth flow (DCR + authorization-code + PKCE) against Keycloak; each user only sees their own collection.

• Claude Code — claude mcp add --transport http pensieve https://<MCP_DOMAIN>/mcp (locally, http://localhost:8090/mcp against the secured dev stack). On first use the CLI opens the browser to Keycloak to authorize; unauthenticated calls are challenged with 401 + WWW-Authenticate.

• claude.ai / Claude Desktop connectors — add a Custom Connector with the remote MCP URL https://<MCP_DOMAIN>/mcp. The client reads /.well-known/oauth-protected-resource, registers via DCR, and completes the PKCE login against Keycloak. (For remote hosts, pre-registering a client in Keycloak is more reliable than anonymous DCR — see keycloak/README.md in the API repo.)

• MCP Inspector — point it at the /mcp URL; it will prompt for the OAuth flow.

The backend owner-scopes every tool call: a lapsed/guest caller gets the same 402/403 capability responses (surfaced as MCP isError results) it would from the REST API — MCP reads inherit the exact same authorization as the web app (RLS + the capability matrix), never more.

Docker / Compose

The docker-compose stack lives in the API repo, which consumes this sidecar as a published image (sethcondie/the-game-pensieve-mcp:latest) — the same way it consumes the front end. Build and push from this repo:

docker build -t sethcondie/the-game-pensieve-mcp:latest .
# multiplatform build-and-push commands: documentation/DevDocumentation.md in the API repo

Then, from the API repo:

docker compose -f dockerCompose/compose.unsecured.yaml up -d backend mcp
# MCP endpoint: http://localhost:8090/mcp
# Use -f dockerCompose/compose.secured.yaml instead to develop against a backend that requires tokens; the
# sidecar's auto mode reads the backend heartbeat and starts enforcing OAuth on its own.

To iterate locally without a rebuild each time, run npm run dev on the host against the docker-compose backend (API_BASE_URL=http://localhost:8080/v1 PORT=8090) instead of the mcp service.

In production (dockerCompose/compose.production.yaml in the API repo) the sidecar has no public ports — Caddy fronts it at https://<MCP_DOMAIN>/mcp and terminates TLS. There it runs MCP_AUTH_MODE=required with the public issuer/audience URLs. See that repo's Caddyfile + dockerCompose/.env.production.example.

Transport notes

Streamable HTTP, stateless: each POST /mcp spins up a fresh server and transport. GET/DELETE on /mcp return 405 (no server-initiated streams or sessions). GET /healthz is a liveness probe.