modelcontextprotocol/example-remote-server
Watch
1
0
Fork
You've already forked example-remote-server
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add customization guide and fix broken doc references

Browse source 
- 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
This commit is contained in:
Basil Hosmer 2025-10-07 17:08:10 -04:00
commit 695f9f68ae
No known key found for this signature in database
4 changed files with 133 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

19
README.md
View file

@ -53,10 +53,10 @@ 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
@ -64,7 +64,13 @@ 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

2
auth-server/README.md
View file

@ -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

117
docs/customization-guide.md Normal file
View file

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

3
mcp-server/README.md
View file

@ -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