Skip to content

Commit 22c7f74

Browse files
bhosmer-antbhosmer-ant
authored
Merge pull request #16 from modelcontextprotocol/basil/more_docs_changes
resequence README.md
2 parents 45ffd17 + 927634d commit 22c7f74

File tree

1 file changed

+107
-107
lines changed

1 file changed

+107
-107
lines changed

‎README.md‎

Lines changed: 107 additions & 107 deletions
Original file line numberDiff line numberDiff line change
@@ -18,19 +18,19 @@ The [Model Context Protocol](https://modelcontextprotocol.io) is an open standar
1818
- [Quick Start](#quick-start)
1919
- [Installation](#installation)
2020
- [Testing](#testing)
21-
- [Repository Structure](#repository-structure)
21+
- [Common Issues & Solutions](#common-issues--solutions)
2222
- [Understanding the System](#understanding-the-system)
2323
- [Features](#features)
24+
- [Repository Structure](#repository-structure)
2425
- [Authentication & Authorization](#authentication--authorization)
2526
- [Configuration](#configuration)
2627
- [Customizing for Your Use Case](#customizing-for-your-use-case)
2728
- [Development & Operations](#development--operations)
2829
- [Development](#development)
29-
- [Common Issues & Solutions](#common-issues--solutions)
30-
- [Technical Details](#technical-details)
3130
- [Monitoring & Debugging](#monitoring--debugging)
3231
- [Reference](#reference)
3332
- [API Reference](#api-reference)
33+
- [Technical Details](#technical-details)
3434
- [Security](#security)
3535
- [External Resources](#external-resources)
3636
- [Contributing](#contributing)
@@ -151,23 +151,65 @@ The `examples/` directory contains runnable code demonstrating OAuth and MCP int
151151

152152
See [examples/README.md](examples/README.md) for detailed usage.
153153

154-
## Repository Structure
154+
## Common Issues & Solutions
155155

156-
This repository demonstrates a production-ready MCP deployment pattern with separate authorization and resource servers:
156+
### "Token validation failed"
157+
- **Cause**: Token expired or servers not communicating
158+
- **Solution**:
159+
- Ensure both servers are running (`npm run dev`)
160+
- Check that Redis is running (`docker compose ps`)
161+
- Verify the token hasn't expired (tokens last 7 days)
157162

158-
```
159-
auth-server/ # OAuth 2.0 authorization server (demo only - replace in production)
160-
└── src/ # Authorization endpoints and token management
163+
### "Cannot connect to MCP server" or "Connection Error - Check if your MCP server is running"
164+
- **Cause**: Incorrect URL format or servers not running
165+
- **Solution**:
166+
- Use the full URL with http:// prefix: `http://localhost:3232/mcp`
167+
- Ensure **both** auth and MCP servers are running (`npm run dev`)
161168

162-
mcp-server/ # MCP resource server (customize tools/resources/prompts)
163-
└── src/ # MCP protocol implementation with external auth
169+
### "Wrong endpoint for SSE transport" or SSE connection fails to `/mcp`
170+
- **Cause**: Using SSE transport with Streamable HTTP endpoint
171+
- **Solution**:
172+
- For **SSE transport** (legacy): Use `http://localhost:3232/sse`
173+
- For **Streamable HTTP** (recommended): Use `http://localhost:3232/mcp`
174+
- In MCP Inspector: Match transport type with the correct endpoint
164175

165-
scripts/ # Testing and deployment scripts
166-
docs/ # Architecture and API documentation
167-
examples/ # Example code and usage patterns
168-
```
176+
### "Cannot connect to Docker daemon"
177+
- **Cause**: Docker/OrbStack not running
178+
- **Solution**:
179+
- macOS with OrbStack: `orbctl start` (verify with `orbctl status`)
180+
- Windows/Linux/macOS with Docker Desktop: Start Docker Desktop application
169181

170-
The architecture separates authentication concerns from MCP functionality, allowing you to integrate with commercial OAuth providers (Auth0, Okta, etc.).
182+
### "Redis connection refused"
183+
- **Cause**: Redis container not running
184+
- **Solution**:
185+
- Check Redis is running: `docker compose ps`
186+
- If not running: `docker compose up -d`
187+
- Ensure Docker/OrbStack is started first
188+
189+
### "Port already in use"
190+
- **Cause**: Another process using port 3001 or 3232
191+
- **Solution**:
192+
- Check for existing processes: `lsof -i :3232` or `lsof -i :3001`
193+
- Kill existing processes or change PORT in .env files
194+
195+
### "Authentication service unavailable" (HTTP 503)
196+
- **Cause**: Auth server is not running or not reachable
197+
- **What happens**: MCP server runs in degraded mode
198+
- Splash page accessible with warning banner
199+
- Health endpoint shows degraded status: `curl http://localhost:3232/health`
200+
- Protected MCP endpoints return 503 with helpful error message
201+
- **Solution**:
202+
- Start the auth server: `npm run dev` (starts both servers)
203+
- Or start manually: `cd auth-server && npm run dev`
204+
- Restart the MCP server to retry connection
205+
206+
### "Authentication flow fails"
207+
- **Cause**: Misconfiguration or servers not communicating
208+
- **Solution**:
209+
- Check server logs for error messages
210+
- Ensure Redis is running: `docker compose ps`
211+
- Verify .env configuration in both server directories
212+
- Check that both servers are running
171213

172214
---
173215

@@ -199,6 +241,24 @@ The architecture separates authentication concerns from MCP functionality, allow
199241
- **Security Headers**: CSP, HSTS, X-Frame-Options, and more
200242
- **Bearer Token Auth**: Middleware for protected endpoints
201243

244+
## Repository Structure
245+
246+
This repository demonstrates a production-ready MCP deployment pattern with separate authorization and resource servers:
247+
248+
```
249+
auth-server/ # OAuth 2.0 authorization server (demo only - replace in production)
250+
└── src/ # Authorization endpoints and token management
251+
252+
mcp-server/ # MCP resource server (customize tools/resources/prompts)
253+
└── src/ # MCP protocol implementation with external auth
254+
255+
scripts/ # Testing and deployment scripts
256+
docs/ # Architecture and API documentation
257+
examples/ # Example code and usage patterns
258+
```
259+
260+
The architecture separates authentication concerns from MCP functionality, allowing you to integrate with commercial OAuth providers (Auth0, Okta, etc.).
261+
202262
## Authentication & Authorization
203263

204264
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:
315375
- Validates token introspection between servers
316376
- Tests session management and ownership
317377

318-
## Common Issues & Solutions
378+
## Monitoring & Debugging
319379

320-
### "Token validation failed"
321-
- **Cause**: Token expired or servers not communicating
322-
- **Solution**:
323-
- Ensure both servers are running (`npm run dev`)
324-
- Check that Redis is running (`docker compose ps`)
325-
- Verify the token hasn't expired (tokens last 7 days)
380+
### Logging
381+
Structured JSON logging with sanitized outputs:
382+
- HTTP request/response logging
383+
- Authentication events
384+
- Session lifecycle events
385+
- Redis operations
386+
- Error tracking
326387

327-
### "Cannot connect to MCP server" or "Connection Error - Check if your MCP server is running"
328-
- **Cause**: Incorrect URL format or servers not running
329-
- **Solution**:
330-
- Use the full URL with http:// prefix: `http://localhost:3232/mcp`
331-
- Ensure **both** auth and MCP servers are running (`npm run dev`)
388+
### Redis Monitoring
389+
```bash
390+
# Monitor session ownership
391+
redis-cli KEYS "session:*:owner"
332392

333-
### "Wrong endpoint for SSE transport" or SSE connection fails to `/mcp`
334-
- **Cause**: Using SSE transport with Streamable HTTP endpoint
335-
- **Solution**:
336-
- For **SSE transport** (legacy): Use `http://localhost:3232/sse`
337-
- For **Streamable HTTP** (recommended): Use `http://localhost:3232/mcp`
338-
- In MCP Inspector: Match transport type with the correct endpoint
339-
340-
### "Cannot connect to Docker daemon"
341-
- **Cause**: Docker/OrbStack not running
342-
- **Solution**:
343-
- macOS with OrbStack: `orbctl start` (verify with `orbctl status`)
344-
- Windows/Linux/macOS with Docker Desktop: Start Docker Desktop application
393+
# Watch real-time operations
394+
redis-cli MONITOR | grep "session:"
345395

346-
### "Redis connection refused"
347-
- **Cause**: Redis container not running
348-
- **Solution**:
349-
- Check Redis is running: `docker compose ps`
350-
- If not running: `docker compose up -d`
351-
- Ensure Docker/OrbStack is started first
396+
# Check active sessions
397+
redis-cli PUBSUB CHANNELS "mcp:shttp:toserver:*"
352398

353-
### "Port already in use"
354-
- **Cause**: Another process using port 3001 or 3232
355-
- **Solution**:
356-
- Check for existing processes: `lsof -i :3232` or `lsof -i :3001`
357-
- Kill existing processes or change PORT in .env files
399+
# Debug specific session
400+
redis-cli GET "session:{sessionId}:owner"
401+
```
358402

359-
### "Authentication service unavailable" (HTTP 503)
360-
- **Cause**: Auth server is not running or not reachable
361-
- **What happens**: MCP server runs in degraded mode
362-
- Splash page accessible with warning banner
363-
- Health endpoint shows degraded status: `curl http://localhost:3232/health`
364-
- Protected MCP endpoints return 503 with helpful error message
365-
- **Solution**:
366-
- Start the auth server: `npm run dev` (starts both servers)
367-
- Or start manually: `cd auth-server && npm run dev`
368-
- Restart the MCP server to retry connection
403+
### Debug Tools
404+
- MCP Inspector for interactive debugging
405+
- Comprehensive test suite
406+
- Hot-reload development mode
407+
- Source maps for debugging
408+
- Redis monitoring commands
369409

370-
### "Authentication flow fails"
371-
- **Cause**: Misconfiguration or servers not communicating
372-
- **Solution**:
373-
- Check server logs for error messages
374-
- Ensure Redis is running: `docker compose ps`
375-
- Verify .env configuration in both server directories
376-
- Check that both servers are running
410+
---
411+
412+
# Reference
413+
414+
## API Reference
415+
416+
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).
377417

378418
## Technical Details
379419

@@ -430,46 +470,6 @@ Backwards-compatible [transport](https://modelcontextprotocol.io/specification/2
430470
- Redis-backed message routing
431471
- Real-time event delivery
432472

433-
## Monitoring & Debugging
434-
435-
### Logging
436-
Structured JSON logging with sanitized outputs:
437-
- HTTP request/response logging
438-
- Authentication events
439-
- Session lifecycle events
440-
- Redis operations
441-
- Error tracking
442-
443-
### Redis Monitoring
444-
```bash
445-
# Monitor session ownership
446-
redis-cli KEYS "session:*:owner"
447-
448-
# Watch real-time operations
449-
redis-cli MONITOR | grep "session:"
450-
451-
# Check active sessions
452-
redis-cli PUBSUB CHANNELS "mcp:shttp:toserver:*"
453-
454-
# Debug specific session
455-
redis-cli GET "session:{sessionId}:owner"
456-
```
457-
458-
### Debug Tools
459-
- MCP Inspector for interactive debugging
460-
- Comprehensive test suite
461-
- Hot-reload development mode
462-
- Source maps for debugging
463-
- Redis monitoring commands
464-
465-
---
466-
467-
# Reference
468-
469-
## API Reference
470-
471-
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).
472-
473473
## Security
474474

475475
### Implemented Security Measures

0 commit comments

Comments
 (0)