systemprompt-mcp-server

Website | Documentation

Sponsored by systemprompt.io

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.

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
• Quick Start
• Architecture
• OAuth Implementation
• Tool Reference
• Advanced Features
• Using as a Template
• Development
• Code Structure
• Contributing
• Related Projects

✨ 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

1. Create a Reddit app at reddit.com/prefs/apps

   • Choose "script" type
   • Set redirect URI: http://localhost:3000/oauth/reddit/callback

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

1. In your MCP client, connect to http://localhost:3000
2. The OAuth flow will start automatically
3. Authorize the app in your browser
4. 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

1. Create Reddit App: reddit.com/prefs/apps

   • Choose "script" type
   • Set redirect URI: http://localhost:3000/oauth/reddit/callback

2. 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     │  │
│  └─────────────┘  └─────────────┘  └────────────────┘  │
└───────────────────────────────────────────────────────