systemprompt-mcp-server
Website | Documentation
This MCP server implementation is sponsored by systemprompt.io — creators of the world's first native mobile MCP client for iOS and Android — and provided completely free and open source to the community.
We believe in advancing the MCP ecosystem by providing high-quality, production-ready implementations that developers can learn from, use, and build upon.
If you find this project useful, we'd appreciate:
- ⭐ A star on this repository
- 👍 A like/follow on our social channels
- 🔗 Sharing with your network
Your support helps us continue creating valuable open source tools for the AI community!
🚀 Learn More: For an interactive walkthrough of this implementation with live SDK testing, visit systemprompt.io/mcp-server
A production-ready Model Context Protocol (MCP) server that demonstrates the complete MCP specification including OAuth 2.1, sampling, elicitation, structured data validation, and real-time notifications.
This implementation uses Reddit as a real-world example to demonstrate OAuth 2.1 flow and advanced MCP features, but the architecture is designed to be easily adapted for any API that requires OAuth authentication.
This server works with any MCP-compliant client that supports advanced features like sampling and notifications.
🔍 MCP Inspector Compatible
This server is fully compatible with the MCP Inspector, providing perfect support for:
- ✅ OAuth 2.1 Authentication - Complete flow with PKCE
- ✅ Tools - All Reddit interaction capabilities
- ✅ Prompts - Dynamic content generation prompts
- ✅ Sampling - AI-assisted content with human approval
- ✅ Notifications - Real-time progress updates
Test it yourself: npm run inspector
🌟 Why This Implementation Matters
OAuth 2.1 Demonstration with Reddit
This implementation uses Reddit's API as a real-world example to demonstrate how to build a complete OAuth 2.1 flow in an MCP server. Reddit was chosen because:
- It requires OAuth authentication for most operations
- It provides a rich API for demonstrating various MCP features
- It's a well-documented, publicly accessible API
- It showcases real-world authentication challenges and solutions
Note: While this server uses Reddit, the OAuth implementation and architecture patterns are designed to be easily adapted for any OAuth-based API (GitHub, Google, Slack, etc.).
Key Features Demonstrated
This repository serves as the gold standard for MCP server implementations, showcasing:
- Complete MCP Spec Coverage: Every feature from OAuth to sampling is implemented
- Production Architecture: Multi-user sessions, security, and scalability built-in
- Developer Experience: Clean code structure perfect for learning or forking
- Real-World OAuth Integration: Full OAuth 2.1 flow with PKCE, JWT tokens, and session management
- AI-Native Design: Deep integration with LLMs for content generation and analysis
📚 Table of Contents
✨ Features
Core MCP Implementation
- 🔐 OAuth 2.1 Flow: Complete 8-step implementation with PKCE and JWT
- 🛠️ Tool System: Comprehensive tools for Reddit interaction
- 📚 Resources & Prompts: Dynamic prompt generation and resource management
- 🤖 Sampling: AI-assisted content generation with human oversight
- 💬 Elicitation: Dynamic user input gathering during tool execution
- ✅ Structured Data: JSON Schema validation for all inputs/outputs
- 📡 Notifications: Real-time progress updates and status notifications
- 🔄 Session Management: Multi-user support with automatic cleanup
Reddit Integration Features
- Content Discovery: Search and analyze Reddit content
- User Interactions: View messages, notifications, and manage account
- Subreddit Information: Retrieve subreddit details and posts
- Comment Threads: Navigate and analyze Reddit discussions
Developer Features
- TypeScript: Full type safety with comprehensive interfaces
- Modular Architecture: Clean separation of concerns
- Error Handling: Robust error management with custom error types
- Docker Support: Ready for containerized deployment
- Testing: Example test implementations included
- Documentation: Extensive inline documentation and examples
🚀 Quick Start
🐳 Simplest Installation (Docker with npx)
Run the server instantly with Docker - no installation required:
Step 1: Create Reddit App & Initial Config
- Create a Reddit app at reddit.com/prefs/apps
- Choose "script" type
- Set redirect URI:
http://localhost:3000/oauth/reddit/callback
- Create initial
.env file:
cat > .env << EOF
REDDIT_CLIENT_ID=your_reddit_client_id
REDDIT_CLIENT_SECRET=your_reddit_client_secret
JWT_SECRET=any_random_string_here
EOF
Step 2: Run the Server
# Run with Docker (pulls image automatically)
docker run -it --rm \
-p 3000:3000 \
--env-file .env \
--name mcp-reddit \
node:20-slim \
npx @systemprompt/systemprompt-mcp-server
Step 3: Complete OAuth Authentication
- In your MCP client, connect to
http://localhost:3000 - The OAuth flow will start automatically
- Authorize the app in your browser
- Copy the returned OAuth token
Step 4: Update Environment with Token
# Stop the container (Ctrl+C)
# Add the OAuth token to your .env file
echo "OAUTH_ACCESS_TOKEN=your_oauth_token_here" >> .env
# Restart with the token
docker run -it --rm \
-p 3000:3000 \
--env-file .env \
node:20-slim \
npx @systemprompt/systemprompt-mcp-server
Now you can use all Reddit tools with your authenticated session!
Installation
# Via npm
npm install -g @systemprompt/systemprompt-mcp-server
# Via npx (no installation)
npx @systemprompt/systemprompt-mcp-server
# Clone for development
git clone https://github.com/systempromptio/systemprompt-mcp-server.git
cd systemprompt-mcp-server
npm install
npm run build
Configuration
- Create Reddit App: reddit.com/prefs/apps
- Choose "script" type
- Set redirect URI:
http://localhost:3000/oauth/reddit/callback
- Set Environment Variables:
Create a .env file in the project root:
# Required for Reddit API
REDDIT_CLIENT_ID=your_reddit_client_id
REDDIT_CLIENT_SECRET=your_reddit_client_secret
JWT_SECRET=your_jwt_secret # Secret for JWT signing
# Optional
PORT=3000 # Server port (default: 3000)
OAUTH_ISSUER=http://localhost:3000 # OAuth issuer URL
REDIRECT_URL=http://localhost:3000/oauth/reddit/callback # OAuth redirect
REDDIT_USER_AGENT=linux:systemprompt-mcp-reddit:v2.0.0 # Reddit user agent
REDDIT_USERNAME=your_reddit_username # Your Reddit username (optional)
LOG_LEVEL=debug # Logging level (debug, info, warn, error)
Note: Environment variables are required for both local development and Docker deployment.
Running the Server
# Build the TypeScript code
npm run build
# Run the built server
node build/index.js
# Development with watch mode
npm run watch
# In another terminal:
node build/index.js
# With Docker
npm run docker
🏗️ Architecture
This implementation follows clean architecture principles with clear separation between layers:
┌─────────────────────────────────────────────────────────┐
│ Client Application │
│ (systemprompt.io) │
└────────────────────────┬────────────────────────────────┘
│ MCP Protocol
┌────────────────────────┴────────────────────────────────┐
│ MCP Server Layer │
│ ┌─────────────┐ ┌─────────────┐ ┌────────────────┐ │
│ │ OAuth 2.1 │ │ Session │ │ Notification │ │
│ │ Handler │ │ Manager │ │ Manager │ │
│ └─────────────┘ └─────────────┘ └────────────────┘ │
└────────────────────────┬────────────────────────────────┘
│
┌────────────────────────┴────────────────────────────────┐
│ Handler Layer │
│ ┌─────────────┐ ┌─────────────┐ ┌────────────────┐ │
│ │ Tools │ │ Resources │ │ Sampling │ │
│ │ Handler │ │ Handler │ │ Handler │ │
│ └─────────────┘ └─────────────┘ └────────────────┘ │
└────────────────────────┬────────────────────────────────┘
│
┌────────────────────────┴────────────────────────────────┐
│ Service Layer │
│ ┌─────────────┐ ┌─────────────┐ ┌────────────────┐ │
│ │ Reddit │ │ Auth │ │ Fetch │ │
│ │ Service │ │ Service │ │ Service │ │
│ └─────────────┘ └─────────────┘ └────────────────┘ │
└─────────────────────────────────────────────────────────┘
Key Components
src/server.ts: Main HTTP server setup and Express configurationsrc/server/: Core server infrastructure (MCP, OAuth, auth management)src/handlers/: Request handlers for tools, prompts, resources, and samplingsrc/services/: Business logic and Reddit API integrationsrc/constants/: Tool definitions, server configuration, and schemassrc/types/: TypeScript type definitions and interfaces
🔐 OAuth Implementation
This server implements the complete MCP OAuth 2.1 specification:
OAuth Flow Steps
- Initial 401 Response (src/server/oauth.ts)
WWW-Authenticate: Bearer realm="MCP Reddit Server"
- Resource Metadata (src/server/oauth.ts)
{
"authorization_server": "http://localhost:3000/.well-known/oauth"
}
- Authorization Server Metadata (src/server/oauth.ts)
- Token endpoint configuration
- PKCE support declaration
- Grant types supported
- Authorization Request (src/server/oauth.ts)
- PKCE code challenge
- State parameter for CSRF protection
- Reddit OAuth redirect handling
- Reddit OAuth Callback (src/server/oauth.ts)
- Reddit authorization handling
- Secure state validation
- Token Exchange (src/server/oauth.ts)
- PKCE verification
- JWT token generation
- Reddit credentials embedding
- Authenticated Requests (src/server/middleware.ts)
- JWT validation
- Session management
- Request context injection
Security Features
- PKCE Implementation: Prevents authorization code interception
- JWT Tokens: Secure credential storage and transmission
- Session Isolation: Each user has isolated Reddit credentials
- Automatic Cleanup: Sessions expire after inactivity
Content Discovery Tools
search_reddit
Search across Reddit with filters (src/handlers/tools/search-reddit.ts)
{
"query": "typescript MCP",
"subreddit": "programming", // Optional specific subreddit
"sort": "relevance",
"time": "week",
"limit": 10
}
get_post
Fetch a specific post with comments (src/handlers/tools/get-post.ts)
{
"id": "post_id_here" // Reddit post ID
}
get_channel
Get subreddit posts (src/handlers/tools/get-channel.ts)
{
"subreddit": "programming",
"sort": "hot" // "hot", "new", or "controversial"
}
get_notifications
Fetch user notifications and messages (src/handlers/tools/get-notifications.ts)
{
"filter": "unread", // "all", "unread", "messages", "comments", "mentions"
"limit": 25,
"markRead": false
}
Retrieve a specific comment (src/handlers/tools/get-comment.ts)
{
"id": "comment_id_here",
"includeThread": true // Include full comment thread
}
elicitation_example
Demonstrates user input gathering (src/handlers/tools/elicitation-example.ts)
{
"type": "input", // "input", "confirm", "choice"
"prompt": "Enter your choice",
"options": ["option1", "option2"] // For choice type
}
sampling_example
Demonstrates AI-assisted content generation (src/handlers/tools/sampling-example.ts)
{
"prompt": "Generate a code example",
"maxTokens": 1000,
"temperature": 0.7
}
structured_data_example
Demonstrates structured data handling (src/handlers/tools/structured-data-example.ts)
{
"format": "json", // "json", "table", "markdown"
"data": { "key": "value" }
}
validation_example
Demonstrates input validation (src/handlers/tools/validation-example.ts)
{
"test_string": "example",
"test_number": 42,
"test_enum": "option1"
}
mcp_logging
Request server to log messages (src/handlers/tools/logging.ts)
{
"level": "info", // "debug", "info", "warning", "error"
"message": "Debug message",
"data": { "additional": "context" }
}
🎯 Advanced Features
Sampling (AI-Assisted Content Generation)
The sampling implementation (src/handlers/sampling.ts) follows the complete MCP specification:
// 1. Client requests AI assistance
await client.callTool("sampling_example", {
prompt: "Analyze this subreddit and suggest actions",
maxTokens: 1000,
temperature: 0.7
});
// 2. Server initiates sampling for content generation
const samplingRequest = {
method: "sampling/createMessage",
params: {
messages: [{
role: "user",
content: {
type: "text",
text: "Analyze this subreddit and suggest actions"
}
}],
maxTokens: 1000,
temperature: 0.7,
_meta: {
callback: "suggest_action"
}
}
};
// 3. AI generates content
// 4. Callback processes the response
// 5. Client receives the final result
Example implementation (src/handlers/tools/elicitation-example.ts):
// Call the elicitation example tool
await client.callTool("elicitation_example", {
type: "input",
prompt: "Enter post title",
options: []
});
// The tool demonstrates different elicitation types:
// - "input": Text input from user
// - "confirm": Yes/no confirmation
// - "choice": Multiple choice selection
Progress Notifications
Real-time updates during operations (src/handlers/notifications.ts):
// Send notifications during long-running operations
await sendProgressNotification("Processing request...", sessionId);
await sendSamplingCompleteNotification("Analysis complete", sessionId);
// Notifications are automatically sent to the MCP client
// providing real-time feedback during tool execution
Structured Data Validation
All inputs use Zod schema validation (src/handlers/tool-handlers.ts):
// Example Zod schema for Reddit search
const SearchRedditSchema = z.object({
query: z.string().min(1).max(500).describe("Search query"),
subreddit: z.string().optional().describe("Optional subreddit filter"),
sort: z.enum(["relevance", "hot", "new", "top"]).default("relevance"),
time: z.enum(["hour", "day", "week", "month", "year", "all"]).default("all"),
limit: z.number().int().min(1).max(100).default(25)
});
// Validation is automatic and provides detailed error messages
const args = SearchRedditSchema.parse(request.params.arguments);
🎨 Using as a Template
This codebase is designed to be forked and adapted for other MCP implementations:
Step 1: Fork and Clone
git clone https://github.com/your-username/your-mcp-server.git
cd your-mcp-server
Step 2: Replace Service Layer
Replace Reddit-specific services in src/services/ with your API:
// src/services/your-api/your-service.ts
export class YourAPIService {
async fetchData(params: YourParams): Promise<YourData> {
// Your API integration
}
}
Create tools in src/handlers/tools/:
// src/handlers/tools/your-tool.ts
export const yourTool: ToolDefinition = {
schema: {
name: "your_tool",
description: "What your tool does",
inputSchema: {
type: "object",
properties: {
// Your parameters
}
}
},
handler: async (params, context) => {
// Tool implementation
}
};
Step 4: Update Configuration
Modify src/constants/server/server-config.ts:
export const serverConfig = {
name: "your-mcp-server",
version: "1.0.0",
description: "Your MCP server description"
};
export const serverCapabilities = {
tools: {},
prompts: {},
resources: {},
sampling: {}
};
💻 Development
Prerequisites
- Node.js 18+
- npm or yarn
- Reddit account and app credentials
Development Commands
# Install dependencies
npm install
# Build TypeScript
npm run build
# Watch mode for development
npm run watch
# Run tests (requires OAuth tokens - see below)
npm run test
# Run end-to-end tests
npm run e2e
# Build and run with Docker
npm run docker
Testing
Testing with MCP Inspector
The server is fully compatible with the MCP Inspector, which provides a powerful interface for testing all MCP features:
# Build the server first
npm run build
# Launch the inspector with the built server
npx @modelcontextprotocol/inspector build/index.js
This command will:
- Build the TypeScript project
- Open the MCP Inspector documentation in your browser
- Launch the inspector connected to your local server
Full Feature Compatibility
The Reddit MCP server works perfectly with the MCP Inspector for:
- 🔐 OAuth Authentication: Complete OAuth 2.1 flow with PKCE support
- 🛠️ Tools: All Reddit interaction tools (search, get posts, notifications, etc.)
- 📚 Prompts: Dynamic prompt generation for content creation
- 🤖 Sampling: AI-assisted content generation with human-in-the-loop approval
- 📡 Notifications: Real-time progress updates during operations
- ✅ Structured Data: Full JSON Schema validation for inputs/outputs
The inspector provides:
- Interactive tool testing with parameter validation
- OAuth flow visualization and debugging
- Sampling request/response inspection
- Real-time notification monitoring
- Session management visibility
Setting Up for Testing
Important: To run tests that interact with Reddit, you need to complete the OAuth flow first:
- Start the server and open MCP Inspector:
# Build and start the server
npm run build
node build/index.js
# In another terminal, open the MCP Inspector
npx @modelcontextprotocol/inspector build/index.js
- Complete OAuth Authentication:
- The Inspector will prompt you to authenticate
- Follow the OAuth flow to authorize with Reddit
- After successful authentication, the server stores tokens
- Save OAuth Tokens for Testing:
- Once authenticated via Inspector, copy the generated tokens
- Add them to your
.env file for persistent testing:
# Add these to your .env after completing OAuth
REDDIT_ACCESS_TOKEN=your_access_token
REDDIT_REFRESH_TOKEN=your_refresh_token
Running Tests
# Run all tests (requires OAuth tokens in .env)
npm run test
# Run end-to-end tests
npm run e2e
Testing with Docker
# Build and run with Docker
npm run docker
# Run the server with npx in Docker
docker run --rm -it \
-p 3000:3000 \
-e REDDIT_CLIENT_ID=your_id \
-e REDDIT_CLIENT_SECRET=your_secret \
-e JWT_SECRET=your_jwt_secret \
node:18-alpine \
npx @systemprompt/mcp-server
Manual Testing
# Test OAuth flow manually
curl -X POST http://localhost:3000/mcp/v1/initialize \
-H "Content-Type: application/json" \
-d '{"protocolVersion": "2024-11-05", "capabilities": {}}'
# The response will include auth details if tokens are needed
Docker Development
Quick Start with Docker
# Build and run with docker-compose (recommended)
npm run docker:build-and-run
Manual Docker Commands
# Build image
docker build -t systemprompt-mcp-reddit .
# Run with environment variables
docker run -p 3001:3001 \
-e REDDIT_CLIENT_ID=your_id \
-e REDDIT_CLIENT_SECRET=your_secret \
-e JWT_SECRET=your_jwt_secret \
systemprompt-mcp-reddit
Environment Variables for Docker
Create a .env file in the project root with the following variables:
# Required - Reddit OAuth Application Credentials
REDDIT_CLIENT_ID=your_reddit_client_id
REDDIT_CLIENT_SECRET=your_reddit_client_secret
# Optional - Server Configuration
MCP_PORT=3001 # Port for the MCP server (default: 3001)
JWT_SECRET=your_jwt_secret # Secret for JWT signing (default: auto-generated)
DEBUG=true # Enable debug logging (default: false)
Important: The docker:build-and-run command requires these environment variables to be set either in a .env file or exported in your shell. Without proper Reddit credentials, the OAuth flow will not work.
📁 Code Structure
systemprompt-mcp-reddit/
├── src/
│ ├── index.ts # Main entry point
│ ├── server.ts # HTTP server setup
│ ├── server/ # Server infrastructure
│ │ ├── mcp.ts # MCP protocol handler with session management
│ │ ├── oauth.ts # OAuth 2.1 implementation
│ │ ├── middleware.ts # Express middleware (rate limiting, auth)
│ │ ├── auth-store.ts # Authentication storage
│ │ └── config.ts # Server configuration
│ ├── handlers/ # Request handlers
│ │ ├── tool-handlers.ts # Tool execution and validation
│ │ ├── prompt-handlers.ts # Prompt processing
│ │ ├── resource-handlers.ts # Resource management
│ │ ├── sampling.ts # AI sampling implementation
│ │ ├── notifications.ts # Real-time notifications
│ │ ├── callbacks/ # Sampling callback handlers
│ │ └── tools/ # Individual tool implementations
│ ├── services/ # Business logic
│ │ └── reddit/ # Reddit API integration
│ ├── constants/ # Configuration and definitions
│ │ ├── tools.ts # Tool definitions
│ │ ├── resources.ts # Resource definitions
│ │ ├── sampling/ # Sampling prompt templates
│ │ ├── server/ # Server configuration constants
│ │ └── tool/ # Individual tool constants
│ ├── types/ # TypeScript definitions
│ │ ├── reddit.ts # Reddit-specific types
│ │ ├── config.ts # Configuration types
│ │ ├── sampling.ts # Sampling types
│ │ └── request-context.ts # Request context types
│ └── utils/ # Helper functions
│ ├── logger.ts # Logging utilities
│ ├── reddit-transformers.ts # Reddit data transformers
│ └── validation.ts # Validation utilities
├── scripts/ # Development and testing scripts
├── docker-compose.yml # Docker configuration
├── tsconfig.json # TypeScript configuration
└── package.json # Project configuration
Key Files
🤝 Contributing
We welcome contributions! Please see our Contributing Guide for details.
Development Process
- Fork the repository
- Create a feature branch
- Make your changes with tests
- Submit a pull request
Code Style
- Use TypeScript for all code
- Follow the existing patterns
- Add JSDoc comments for public APIs
- Include tests for new features
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
- Anthropic for the MCP specification
- Reddit for their comprehensive API
- The MCP community for feedback and contributions
Built with ❤️ by the systemprompt.io team
For support, join our Discord or reach out on Twitter