systemprompt-mcp-server

🌟 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

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 configuration
src/server/: Core server infrastructure (MCP, OAuth, auth management)
src/handlers/: Request handlers for tools, prompts, resources, and sampling
src/services/: Business logic and Reddit API integration
src/constants/: Tool definitions, server configuration, and schemas
src/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

🛠️ Tool Reference

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"
}

User Interaction Tools

`get_notifications`

Fetch user notifications and messages (src/handlers/tools/get-notifications.ts)

{
  "filter": "unread",              // "all", "unread", "messages", "comments", "mentions"
  "limit": 25,
  "markRead": false
}

`get_comment`

Retrieve a specific comment (src/handlers/tools/get-comment.ts)

{
  "id": "comment_id_here",
  "includeThread": true            // Include full comment thread
}

Example and Development Tools

`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

Elicitation (Dynamic Input Gathering)

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

Step 3: Define New Tools

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

src/index.ts: Application entry point
src/server.ts: HTTP server setup and Express configuration
src/server/mcp.ts: MCP protocol implementation with session management
src/server/oauth.ts: Complete OAuth 2.1 flow
src/handlers/tool-handlers.ts: Tool execution with Zod validation
src/handlers/sampling.ts: AI sampling implementation
src/services/reddit/reddit-service.ts: Reddit API integration

🤝 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

🔗 Related Projects

Interactive Implementation Guide: Live testing and tutorial
MCP Specification: Official MCP documentation
systemprompt.io Documentation: Platform documentation

📄 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