Reddit

You can run a complete MCP server that demonstrates OAuth 2.1, sampling, elicitation, structured data validation, and real-time notifications using a Reddit-based example. This server enables you to experiment with full MCP features against Reddit or adapt the setup to other OAuth-based APIs while maintaining a production-grade, multi-user environment.

How to use

Connect your MCP client to the local server you run, and you will embark on an end-to-end MCP experience. You will authenticate with the Reddit flow, establish a session for your user, and interact with a suite of tools that perform content discovery, user interactions, and subreddit information retrieval. During tool execution you can enable sampling for AI-assisted content generation, provide dynamic elicitation prompts to gather user input, and receive real-time progress updates via notifications. All inputs and outputs are validated against structured JSON schemas to prevent invalid data from flowing through the system.

How to install

Prerequisites: make sure you have Docker and node available on your machine. You also need a Reddit app for OAuth credentials and a JWT secret for token signing.

Step 1 Create Reddit App and prepare a local env file

> Create a Reddit app at reddit.com/prefs/apps
> - Type: script
> - Redirect URI: http://localhost:3000/oauth/reddit/callback
>
> Create an environment file named .env with:
```bash
REDDIT_CLIENT_ID=your_reddit_client_id
REDDIT_CLIENT_SECRET=your_reddit_client_secret
JWT_SECRET=any_random_string_here

Step 2 Run the server with Docker

> 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 by connecting to http://localhost:3000 and following the flow to authorize with Reddit. Copy the returned OAuth token after authorization.

Step 4 (Optional) If you need to supply the OAuth token in your environment for persistent testing, stop the container, add the token to your .env, and restart the container.

# Stop the container (Ctrl+C)

# Add the OAuth token to your .env file
echo "OAUTH_ACCESS_TOKEN=your_oauth_token_here" >> .env

# Restart the container
docker run -it --rm \
  -p 3000:3000 \
  --env-file .env \
  --name mcp-reddit \
  node:20-slim \
  npx @systemprompt/systemprompt-mcp-server

How to install (alternative entry points)

Install the MCP server locally for development or testing using the standard package manager workflow.

# Via npm (global install)
npm install -g @systemprompt/systemprompt-mcp-server

# Via npx (no installation required)
npx @systemprompt/systemprompt-mcp-server

# For development, clone and install dependencies
# git clone https://github.com/systempromptio/systemprompt-mcp-server.git
# cd systemprompt-mcp-server
# npm install
# npm run build

Configuration and best practices

Prepare Reddit OAuth credentials and a secret for JWT signing. Create a .env file in your project root with REDDIT_CLIENT_ID, REDDIT_CLIENT_SECRET, and JWT_SECRET. You can adjust server port, logging level, and optional Reddit username if needed. When running in Docker, you can also provide an env file to pass these values.

# Required for Reddit OAuth
REDDIT_CLIENT_ID=your_reddit_client_id
REDDIT_CLIENT_SECRET=your_reddit_client_secret
JWT_SECRET=your_jwt_secret

# Optional
PORT=3000
LOG_LEVEL=debug
REDDIT_USER_AGENT=linux:systemprompt-mcp-reddit:v2.0.0

Security and operational notes

The server supports OAuth 2.1 with PKCE, JWT-based session tokens, and per-user session isolation. Sessions automatically cleanup after inactivity. When testing, ensure you keep your JWT_SECRET secure and do not expose tokens in client applications.

Development and testing tips

For testing MCP features, you can run the server locally and use an MCP inspector or your own client to exercise OAuth, tools, prompts, sampling, and notifications. When you need to pause and inspect, use logging at the desired level and review the request context for debugging.

Troubleshooting

If you encounter OAuth or token issues, re-run the OAuth flow to obtain fresh tokens and ensure your redirect URL is correctly configured in the Reddit app. Check that the environment variables are loaded by the server, and verify that the server is accessible at the expected port.

Available tools

search_reddit

Search Reddit content with filters such as query, subreddit, sort, time, and limit to discover relevant posts.

get_post

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

get_channel

Retrieve a stream of subreddit posts, supporting sorting methods like hot or new.

get_notifications

Fetch user notifications and messages with filtering and pagination.

get_comment

Retrieve a specific Reddit comment, optionally including the full thread.

elicitation_example

Demonstrates user input gathering with types like input, confirm, and choice for dynamic prompts.

sampling_example

Demonstrates AI-assisted content generation with prompts and configuration for sampling.

structured_data_example

Shows how structured data is handled and validated using a schema.

validation_example

Demonstrates input validation with a predefined schema.

mcp_logging

Log server-side messages and events to the client for debugging and monitoring.