Systemprompt

You will run a production-ready MCP server that demonstrates OAuth 2.1, sampling, elicitation, structured data validation, and real-time notifications using Reddit as the example. This server lets you connect an MCP client, authorize with Reddit, and perform tool-driven interactions with AI-assisted features in a scalable, multi-user setup.

How to use

Connect your MCP client to the server URL (for local testing, use http://localhost:3000). Begin the OAuth 2.1 flow to authorize the Reddit integration, then use the available tools to search Reddit content, fetch posts and comments, and manage notifications. During long-running operations, you will receive real-time progress updates. All inputs are validated against JSON schemas to ensure structured data handling.

How to install

Prerequisites: Node.js 18+, npm or yarn, and a Reddit account to create an app for OAuth.

Simplest installation (Docker with npx) lets you run without a local install. Follow these steps to get started.

# Step 1: Create Reddit App & Initial Config
# - Go to reddit.com/prefs/apps and create a script-type app
# - Set redirect URI: http://localhost:3000/oauth/reddit/callback

# Step 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 3: Run the server 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

After the container starts, open your MCP client and connect to http://localhost:3000 to begin the OAuth flow and use Reddit tools.

Additional sections

Configuration and security are integral to the server. You will provide Reddit app credentials, define a JWT secret, and adjust server ports as needed. The server supports multi-user sessions with automatic cleanup and PKCE-secured OAuth 2.1 flows.

Environment variables you may configure include: REDDIT_CLIENT_ID, REDDIT_CLIENT_SECRET, JWT_SECRET, PORT, OAUTH_ISSUER, REDIRECT_URL, REDDIT_USER_AGENT, REDDIT_USERNAME, LOG_LEVEL. These values are used to initialize Reddit access, sign tokens, and control logging. Define them in a .env file when running locally or pass them to your container in Docker.

If you want to run the server locally without Docker, install dependencies, build, and start the server using the provided commands.

# Install dependencies
npm install

# 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

# Docker build and run example
npm run docker

OAuth Implementation and security notes

The server implements the complete MCP OAuth 2.1 flow with PKCE, JWT tokens, and per-session Reddit credentials. This ensures secure authorization, token handling, and isolation between user sessions.

Key security features include PKCE to prevent authorization code interception, JWT-based credential storage, session isolation for each user, and automatic cleanup of inactive sessions.

Tools reference and example usage

The server exposes a family of MCP tools for Reddit interactions, including content discovery, user interactions, and subreddit information. Each tool validates inputs and returns structured data.

Development and testing

You can test with the MCP Inspector to verify OAuth, tools, prompts, sampling, and notifications. Build the server, then launch the inspector connected to your local server to exercise all MCP features.

To run tests that require Reddit interactions, complete the OAuth flow once, then store tokens for persistent testing in a .env file.

Notes on deployment

The server is designed for containerized deployment with Docker and supports multi-user sessions, secure JWT-based authentication, and real-time notifications. Adjust the port and environment variables as needed for your hosting environment.

Available tools

search_reddit

Search Reddit with filters and return results for analysis and content discovery.

get_post

Fetch a specific Reddit post along with its comments for analysis.

get_channel

Retrieve posts from a subreddit with sorting options.

get_notifications

Fetch user notifications and messages.

get_comment

Retrieve a specific Reddit comment, with optional thread context.

elicitation_example

Demonstrates dynamic user input gathering through elicitation.

sampling_example

Demonstrates AI-assisted content generation and evaluation.

structured_data_example

Shows how structured data is handled and validated.

validation_example

Illustrates input validation with predefined schemas.

mcp_logging

Log server events and messages through the MCP channel.