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

Author: bhosmer-ant

README.md

@@ -53,18 +53,24 @@ For detailed instructions, see [Installation](#installation).
 This repository demonstrates a production-ready MCP deployment pattern with separate authorization and resource servers:
 
 ```
-auth-server/             # OAuth 2.0 authorization server
+auth-server/             # OAuth 2.0 authorization server (demo only - replace in production)
   └── src/               # Authorization endpoints and token management
 
-mcp-server/              # MCP resource server
+mcp-server/              # MCP resource server (customize tools/resources/prompts)
   └── src/               # MCP protocol implementation with external auth
 
 scripts/                 # Testing and deployment scripts
 docs/                    # Architecture and API documentation
 examples/                # Example code and usage patterns
 ```
 
-The architecture separates authentication concerns from MCP functionality, allowing you to integrate with existing OAuth providers (Auth0, Okta, etc.) or deploy your own authorization server.
+The architecture separates authentication concerns from MCP functionality, allowing you to integrate with commercial OAuth providers (Auth0, Okta, etc.).
+
+## Customizing for Your Use Case
+
+This is a reference implementation with demo tools, resources, and prompts. To adapt it for production:
+- **Replace MCP features:** See [Customization Guide](docs/customization-guide.md) for replacing demo functionality with your own
+- **Integrate OAuth provider:** See [OAuth Architecture Patterns](docs/oauth-architecture-patterns.md) for production authentication setup
 
 ## Usage Examples
 
@@ -174,7 +180,7 @@ sequenceDiagram
     Client->>User: 9. Results
 ```
 
-The auth server is separate so you can easily replace it with Auth0, Okta, or any OAuth provider. See [docs/oauth-patterns.md](docs/oauth-patterns.md) for alternative architectures.
+The auth server is separate so you can easily replace it with Auth0, Okta, or any OAuth provider. See [docs/oauth-architecture-patterns.md](docs/oauth-architecture-patterns.md) for integration guidance.
 
 ## Table of Contents
 
@@ -320,7 +326,7 @@ This architecture pattern:
 - **Scales independently**: Auth and MCP servers can scale based on their load
 - **Follows standards**: Uses OAuth 2.0 and token introspection (RFC 7662)
 
-For alternative patterns like embedded OAuth, see [docs/oauth-patterns.md](docs/oauth-patterns.md).
+For alternative patterns like embedded OAuth, see [docs/oauth-architecture-patterns.md](docs/oauth-architecture-patterns.md).
 
 ### OAuth Flow
 
@@ -361,9 +367,10 @@ The `/mock-upstream-idp` endpoints simulate what a real identity provider (Googl
 ├── scripts/                     # Testing and deployment
 │   └── test-e2e.sh              # End-to-end OAuth + MCP verification
 ├── docs/
+│   ├── customization-guide.md   # How to adapt this for your use case
 │   ├── endpoints.md             # API endpoint reference
 │   ├── oauth-flow.md            # OAuth flow documentation
-│   ├── oauth-patterns.md        # Alternative OAuth patterns
+│   ├── oauth-architecture-patterns.md  # OAuth integration guidance
 │   └── session-ownership.md     # Session management details
 ├── examples/                    # Example code and usage patterns
 │   ├── client.js                # Node.js client example

auth-server/README.md

@@ -119,5 +119,5 @@ This server stores in Redis:
 
 - [Main README](../README.md) - Complete project documentation
 - [MCP Server README](../mcp-server/README.md) - How MCP server uses these tokens
-- [OAuth Patterns](../docs/oauth-patterns.md) - OAuth architecture patterns
+- [OAuth Architecture Patterns](../docs/oauth-architecture-patterns.md) - OAuth integration options
 - [OAuth Flow](../docs/oauth-flow.md) - Detailed OAuth flow analysis

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).

mcp-server/README.md

@@ -130,7 +130,8 @@ To use a commercial OAuth provider instead of the demo auth server, see [OAuth A
 ## Related Documentation
 
 - [Main README](../README.md) - Complete project documentation
+- [Customization Guide](../docs/customization-guide.md) - How to adapt this for your use case
 - [Auth Server README](../auth-server/README.md) - The demo OAuth provider
-- [OAuth Patterns](../docs/oauth-patterns.md) - OAuth architecture patterns
+- [OAuth Architecture Patterns](../docs/oauth-architecture-patterns.md) - OAuth integration options
 - [OAuth Flow](../docs/oauth-flow.md) - Detailed OAuth flow analysis
 - [Session Ownership](../docs/session-ownership.md) - Session management details