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

resequence README.md

Browse source
This commit is contained in:
Basil Hosmer 2025-10-09 14:28:13 -04:00
commit 927634dabd
No known key found for this signature in database
1 changed files with 107 additions and 107 deletions
Download patch file Download diff file Expand all files Collapse all files

212
README.md
View file

@ -18,19 +18,19 @@ The [Model Context Protocol](https://modelcontextprotocol.io) is an open standar
- [Quick Start](#quick-start) - [Quick Start](#quick-start)
- [Installation](#installation) - [Installation](#installation)
- [Testing](#testing) - [Testing](#testing)
- [Repository Structure](#repository-structure) - [Common Issues & Solutions](#common-issues--solutions)
- [Understanding the System](#understanding-the-system) - [Understanding the System](#understanding-the-system)
- [Features](#features) - [Features](#features)
- [Repository Structure](#repository-structure)
- [Authentication & Authorization](#authentication--authorization) - [Authentication & Authorization](#authentication--authorization)
- [Configuration](#configuration) - [Configuration](#configuration)
- [Customizing for Your Use Case](#customizing-for-your-use-case) - [Customizing for Your Use Case](#customizing-for-your-use-case)
- [Development & Operations](#development--operations) - [Development & Operations](#development--operations)
- [Development](#development) - [Development](#development)
- [Common Issues & Solutions](#common-issues--solutions)
- [Technical Details](#technical-details)
- [Monitoring & Debugging](#monitoring--debugging) - [Monitoring & Debugging](#monitoring--debugging)
- [Reference](#reference) - [Reference](#reference)
- [API Reference](#api-reference) - [API Reference](#api-reference)
- [Technical Details](#technical-details)
- [Security](#security) - [Security](#security)
- [External Resources](#external-resources) - [External Resources](#external-resources)
- [Contributing](#contributing) - [Contributing](#contributing)
@ -151,23 +151,65 @@ The `examples/` directory contains runnable code demonstrating OAuth and MCP int
See [examples/README.md](examples/README.md) for detailed usage. See [examples/README.md](examples/README.md) for detailed usage.
## Repository Structure ## Common Issues & Solutions
This repository demonstrates a production-ready MCP deployment pattern with separate authorization and resource servers: ### "Token validation failed"
- **Cause**: Token expired or servers not communicating
- **Solution**:
- Ensure both servers are running (`npm run dev`)
- Check that Redis is running (`docker compose ps`)
- Verify the token hasn't expired (tokens last 7 days)
``` ### "Cannot connect to MCP server" or "Connection Error - Check if your MCP server is running"
auth-server/ # OAuth 2.0 authorization server (demo only - replace in production) - **Cause**: Incorrect URL format or servers not running
└── src/ # Authorization endpoints and token management - **Solution**:
- Use the full URL with http:// prefix: `http://localhost:3232/mcp`
- Ensure **both** auth and MCP servers are running (`npm run dev`)
mcp-server/ # MCP resource server (customize tools/resources/prompts) ### "Wrong endpoint for SSE transport" or SSE connection fails to `/mcp`
└── src/ # MCP protocol implementation with external auth - **Cause**: Using SSE transport with Streamable HTTP endpoint
- **Solution**:
- For **SSE transport** (legacy): Use `http://localhost:3232/sse`
- For **Streamable HTTP** (recommended): Use `http://localhost:3232/mcp`
- In MCP Inspector: Match transport type with the correct endpoint
scripts/ # Testing and deployment scripts ### "Cannot connect to Docker daemon"
docs/ # Architecture and API documentation - **Cause**: Docker/OrbStack not running
examples/ # Example code and usage patterns - **Solution**:
``` - macOS with OrbStack: `orbctl start` (verify with `orbctl status`)
- Windows/Linux/macOS with Docker Desktop: Start Docker Desktop application
The architecture separates authentication concerns from MCP functionality, allowing you to integrate with commercial OAuth providers (Auth0, Okta, etc.). ### "Redis connection refused"
- **Cause**: Redis container not running
- **Solution**:
- Check Redis is running: `docker compose ps`
- If not running: `docker compose up -d`
- Ensure Docker/OrbStack is started first
### "Port already in use"
- **Cause**: Another process using port 3001 or 3232
- **Solution**:
- Check for existing processes: `lsof -i :3232` or `lsof -i :3001`
- Kill existing processes or change PORT in .env files
### "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**:
- Check server logs for error messages
- Ensure Redis is running: `docker compose ps`
- Verify .env configuration in both server directories
- Check that both servers are running
--- ---
@ -199,6 +241,24 @@ The architecture separates authentication concerns from MCP functionality, allow
- **Security Headers**: CSP, HSTS, X-Frame-Options, and more - **Security Headers**: CSP, HSTS, X-Frame-Options, and more
- **Bearer Token Auth**: Middleware for protected endpoints - **Bearer Token Auth**: Middleware for protected endpoints
## Repository Structure
This repository demonstrates a production-ready MCP deployment pattern with separate authorization and resource servers:
```
auth-server/ # OAuth 2.0 authorization server (demo only - replace in production)
└── src/ # Authorization endpoints and token management
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 commercial OAuth providers (Auth0, Okta, etc.).
## Authentication & Authorization ## Authentication & Authorization
Per the [MCP Authorization specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization), this implementation demonstrates a production-ready pattern with separate authorization and resource servers. Per the [MCP Authorization specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization), this implementation demonstrates a production-ready pattern with separate authorization and resource servers.
@ -315,65 +375,45 @@ The script:
- Validates token introspection between servers - Validates token introspection between servers
- Tests session management and ownership - Tests session management and ownership
## Common Issues & Solutions ## Monitoring & Debugging
### "Token validation failed" ### Logging
- **Cause**: Token expired or servers not communicating Structured JSON logging with sanitized outputs:
- **Solution**: - HTTP request/response logging
- Ensure both servers are running (`npm run dev`) - Authentication events
- Check that Redis is running (`docker compose ps`) - Session lifecycle events
- Verify the token hasn't expired (tokens last 7 days) - Redis operations
- Error tracking
### "Cannot connect to MCP server" or "Connection Error - Check if your MCP server is running" ### Redis Monitoring
- **Cause**: Incorrect URL format or servers not running ```bash
- **Solution**: # Monitor session ownership
- Use the full URL with http:// prefix: `http://localhost:3232/mcp` redis-cli KEYS "session:*:owner"
- Ensure **both** auth and MCP servers are running (`npm run dev`)
### "Wrong endpoint for SSE transport" or SSE connection fails to `/mcp` # Watch real-time operations
- **Cause**: Using SSE transport with Streamable HTTP endpoint redis-cli MONITOR | grep "session:"
- **Solution**:
- For **SSE transport** (legacy): Use `http://localhost:3232/sse`
- For **Streamable HTTP** (recommended): Use `http://localhost:3232/mcp`
- In MCP Inspector: Match transport type with the correct endpoint
### "Cannot connect to Docker daemon" # Check active sessions
- **Cause**: Docker/OrbStack not running redis-cli PUBSUB CHANNELS "mcp:shttp:toserver:*"
- **Solution**:
- macOS with OrbStack: `orbctl start` (verify with `orbctl status`)
- Windows/Linux/macOS with Docker Desktop: Start Docker Desktop application
### "Redis connection refused" # Debug specific session
- **Cause**: Redis container not running redis-cli GET "session:{sessionId}:owner"
- **Solution**: ```
- Check Redis is running: `docker compose ps`
- If not running: `docker compose up -d`
- Ensure Docker/OrbStack is started first
### "Port already in use" ### Debug Tools
- **Cause**: Another process using port 3001 or 3232 - MCP Inspector for interactive debugging
- **Solution**: - Comprehensive test suite
- Check for existing processes: `lsof -i :3232` or `lsof -i :3001` - Hot-reload development mode
- Kill existing processes or change PORT in .env files - Source maps for debugging
- Redis monitoring commands
### "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" # Reference
- **Cause**: Misconfiguration or servers not communicating
- **Solution**: ## API Reference
- Check server logs for error messages
- Ensure Redis is running: `docker compose ps` For a complete listing of all endpoints provided by each server, including OAuth authorization endpoints, MCP resource endpoints, and demo identity provider endpoints, see [docs/endpoints.md](docs/endpoints.md).
- Verify .env configuration in both server directories
- Check that both servers are running
## Technical Details ## Technical Details
@ -430,46 +470,6 @@ Backwards-compatible [transport](https://modelcontextprotocol.io/specification/2
- Redis-backed message routing - Redis-backed message routing
- Real-time event delivery - Real-time event delivery
## Monitoring & Debugging
### Logging
Structured JSON logging with sanitized outputs:
- HTTP request/response logging
- Authentication events
- Session lifecycle events
- Redis operations
- Error tracking
### Redis Monitoring
```bash
# Monitor session ownership
redis-cli KEYS "session:*:owner"
# Watch real-time operations
redis-cli MONITOR | grep "session:"
# Check active sessions
redis-cli PUBSUB CHANNELS "mcp:shttp:toserver:*"
# Debug specific session
redis-cli GET "session:{sessionId}:owner"
```
### Debug Tools
- MCP Inspector for interactive debugging
- Comprehensive test suite
- Hot-reload development mode
- Source maps for debugging
- Redis monitoring commands
---
# Reference
## API Reference
For a complete listing of all endpoints provided by each server, including OAuth authorization endpoints, MCP resource endpoints, and demo identity provider endpoints, see [docs/endpoints.md](docs/endpoints.md).
## Security ## Security
### Implemented Security Measures ### Implemented Security Measures