Add customization guide and fix broken doc references

- Create docs/customization-guide.md with guidance on replacing demo functionality
- Add customization section to main README
- Fix all references to renamed oauth-architecture-patterns.md
- Update repository structure comments to clarify what to replace vs keep

docs/customization-guide.md

@@ -0,0 +1,117 @@
+# Customization Guide
+
+This reference implementation includes demo functionality to showcase MCP features. Here's how to adapt it for your own use case.
+
+## Overview: What to Customize vs. Keep
+
+**Replace with your own:**
+- MCP tools, resources, and prompts (your business logic)
+- Authentication provider (use commercial OAuth provider)
+
+**Keep as-is (infrastructure):**
+- Redis transport and session management
+- HTTP handlers and routing
+- Security middleware and rate limiting
+- Logging infrastructure
+
+---
+
+## Customizing MCP Functionality
+
+All MCP feature implementations live in **`mcp-server/src/services/mcp.ts`**. This is where you define what your server can do.
+
+### Tools
+
+Replace the 7 demo tools (echo, add, etc.) with your actual tools:
+
+**Location:** `createMcpServer()` function, look for the `CallToolRequestSchema` handler
+
+**What to change:**
+- Tool definitions: name, description, input schema (using Zod)
+- Tool execution logic: what happens when the tool is called
+- Return format: text, images, or embedded resources
+
+**Pattern:** Each tool validates input with a Zod schema and returns content in MCP format.
+
+### Resources
+
+Replace the 100 fake resources with your actual data sources:
+
+**Location:** `createMcpServer()` function, resource-related handlers:
+- `ListResourcesRequestSchema` - List available resources
+- `ReadResourceRequestSchema` - Read specific resources
+- `SubscribeRequestSchema` / `UnsubscribeRequestSchema` - Resource updates
+
+**What to change:**
+- Resource URIs and names
+- Data fetching logic
+- Pagination if needed
+- Update notifications for subscribed resources
+
+**Pattern:** Resources use URIs (e.g., `db://users/123`) and return content as text, JSON, or binary.
+
+### Prompts
+
+Replace the 3 demo prompts with useful prompts for your domain:
+
+**Location:** `createMcpServer()` function, prompt-related handlers:
+- `ListPromptsRequestSchema` - List available prompts
+- `GetPromptRequestSchema` - Return prompt content
+
+**What to change:**
+- Prompt names and descriptions
+- Prompt arguments and validation
+- Prompt content and embedded resources
+
+**Pattern:** Prompts can include dynamic arguments and reference resources.
+
+---
+
+## Customizing Authentication
+
+**Replace the demo auth server** with a commercial OAuth provider (Auth0, Okta, Azure AD, AWS Cognito, Google, GitHub, etc.).
+
+See [OAuth Architecture Patterns](oauth-architecture-patterns.md#using-a-commercial-auth-provider) for detailed integration steps.
+
+**Do not repurpose the demo auth server** - it's designed for development/testing only. Commercial providers offer better security, reliability, and user management.
+
+---
+
+## Configuration
+
+Update environment variables for your deployment:
+
+**MCP Server** (`mcp-server/.env`):
+```bash
+BASE_URI=https://your-mcp-server.com
+PORT=443
+AUTH_SERVER_URL=https://your-tenant.auth0.com
+REDIS_URL=redis://your-redis-server:6379
+```
+
+**Auth Server** (only if using the demo server for development):
+```bash
+AUTH_SERVER_URL=http://localhost:3001
+BASE_URI=https://your-mcp-server.com
+```
+
+---
+
+## Testing Your Customizations
+
+1. **Unit tests:** Add tests for your tools/resources in `mcp-server/src/services/`
+2. **Integration tests:** Test with MCP Inspector or client.js
+3. **Build and lint:** Run `npm run build && npm run lint`
+4. **End-to-end:** Use the examples to verify OAuth and MCP flows
+
+---
+
+## Next Steps
+
+1. Fork/clone this repository
+2. Replace tools, resources, and prompts in `mcp-server/src/services/mcp.ts`
+3. Integrate with your OAuth provider (see OAuth Architecture Patterns doc)
+4. Update environment variables for your deployment
+5. Test thoroughly before deploying
+
+For questions about the MCP protocol itself, see the [MCP specification](https://modelcontextprotocol.io/specification).