Update documentation for graceful degradation and /health endpoint

- Add /health endpoint to docs/endpoints.md for MCP server
- Document degraded mode behavior in Common Issues section
- Update OAuth metadata endpoint to mention 503 responses

Author: bhosmer-ant

README.md

@@ -476,6 +476,17 @@ The script:
   - Google/GitHub OAuth
 - The mock IDP creates random user IDs for testing multi-user scenarios
 
+### "Authentication service unavailable" (HTTP 503)
+- **Cause**: Auth server is not running or not reachable
+- **What happens**: MCP server runs in degraded mode
+  - Splash page accessible with warning banner
+  - Health endpoint shows degraded status: `curl http://localhost:3232/health`
+  - Protected MCP endpoints return 503 with helpful error message
+- **Solution**:
+  - Start the auth server: `npm run dev` (starts both servers)
+  - Or start manually: `cd auth-server && npm run dev`
+  - Restart the MCP server to retry connection
+
 ### "Authentication flow fails"
 - **Cause**: Misconfiguration or servers not communicating
 - **Solution**:

docs/endpoints.md

@@ -42,10 +42,10 @@ Local simulation of upstream IDP (would be external in production):
 MCP resource server that implements the Model Context Protocol with delegated authentication.
 
 ### OAuth Metadata (Read-Only)
-Provided by `mcpAuthMetadataRouter`:
 
 - `GET /.well-known/oauth-authorization-server` - Returns metadata pointing to external auth server
   - Tells clients to use auth server at :3001
+  - Returns 503 if auth server is unavailable (degraded mode)
   - Read-only - no token issuance happens here
 
 ### MCP Resource Endpoints
@@ -61,8 +61,13 @@ Provided by `mcpAuthMetadataRouter`:
 
 All MCP endpoints require `Authorization: Bearer <token>` header. Tokens are validated by calling the auth server's `/introspect` endpoint.
 
+### Utility Endpoints
+- `GET /health` - Health check endpoint
+  - Returns status: `healthy` (auth available) or `degraded` (auth unavailable)
+  - Shows operational status of MCP, auth, and Redis services
+
 ### Static Assets
-- `GET /` - Splash page (HTML)
+- `GET /` - Splash page (HTML with degraded mode warning if auth unavailable)
 - `GET /mcp-logo.png` - MCP logo
 - `GET /styles.css` - Stylesheet