Installation

This guide covers different methods to install and deploy Seed MCP Server.

Prerequisites

Before installing Seed, ensure you have:

Requirement	Minimum Version	Purpose
Node.js	24.0.0+	Runtime environment
npm	10.0.0+	Package manager
Redis	6.0+	Session and client storage
Docker (optional)	20.0+	Container deployment

Installation Methods

Choose the installation method that best fits your needs:

• Docker - Recommended for local development and testing
• From Source - For development or custom builds

Docker Installation

The easiest way to run Seed locally is using the provided management script.

Using the Local Script

The scripts/local script builds and deploys Seed with Redis using Docker Swarm:

# Clone repository
git clone https://gitlab.byterecursion.com/mcp-servers/seed.git
cd seed

# Deploy locally (builds image and starts stack)
./scripts/local

# Or explicitly:
./scripts/local --local

This will:

1. Build the Docker image with the current version from package.json
2. Deploy a Docker stack named seed-local with:
   • Seed MCP server on port 3000
   • Redis for session storage
   • Internal networking between services

Access the service:

• Service: http://localhost:3000
• Health check: http://localhost:3000/health

Management Commands

Build image only:

./scripts/local --build

Clean up deployment:

./scripts/local --down

This removes:

• The seed-local stack
• Associated volumes (redis-data)
• Associated networks (seed-internal)

Get help:

./scripts/local --help

Docker Image Details

Base image: node:24-alpine

Features:

• Multi-stage build for smaller image size
• Non-root user (seed) for security
• Health check endpoint
• Production-optimized (no dev dependencies)

Image size: ~100-150MB (compressed)

Ports exposed:

• 3000 - HTTP server (configurable via PORT)

Verify Installation

# Check health endpoint
curl http://localhost:3000/health

# Expected response:
# {"status":"healthy","version":"0.1.3",...}

# Check logs
docker service logs seed-local_seed -f

From Source

Install and run Seed from source code.

1. Clone Repository

# Via HTTPS
git clone https://gitlab.byterecursion.com/mcp-servers/seed.git
cd seed

# Or via SSH
git clone git@gitlab.byterecursion.com:mcp-servers/seed.git
cd seed

2. Install Dependencies

npm install

This installs:

• Runtime dependencies (Express, MCP SDK, Redis client, JOSE)
• Development dependencies (TypeScript, Vitest, ESLint)

3. Configure Environment

# Copy example configuration
cp .env.example .env

# Edit configuration
vim .env

See Configuration for detailed setup.

4. Build

# Compile TypeScript to JavaScript
npm run build

Output: dist/ directory

5. Run

Production mode:

npm start

Development mode (with hot reload):

npm run dev

Verify:

curl http://localhost:3000/health

Redis Setup

Seed requires Redis for session storage and dynamic client registration.

Note: If you're using the Docker installation method with ./scripts/local, Redis is automatically included in the Docker stack. The instructions below are only needed for source installations.

Local Redis

macOS (Homebrew):

brew install redis
brew services start redis

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install redis-server
sudo systemctl start redis
sudo systemctl enable redis

Verify:

redis-cli ping
# Should return: PONG

Docker Redis

docker run -d \
  --name redis \
  -p 6379:6379 \
  -v redis-data:/data \
  redis:7-alpine redis-server --appendonly yes

Redis Configuration

Default connection: redis://localhost:6379

Custom configuration:

# In .env file
REDIS_URL=redis://user:password@host:port/db

Redis URL formats:

# Local
redis://localhost:6379

# With password
redis://:password@localhost:6379

# Custom database
redis://localhost:6379/1

# Remote with TLS
rediss://user:password@redis.example.com:6380

Upgrading

From Source

# Pull latest changes
git pull origin master

# Install dependencies
npm install

# Rebuild
npm run build

# Restart service
npm start
# or: sudo systemctl restart seed

Docker (using scripts/local)

# Pull latest changes
git pull origin master

# Remove existing deployment
./scripts/local --down

# Deploy with fresh build
./scripts/local

Verification

After installation, verify Seed is working:

1. Health check:

curl http://localhost:3000/health

Expected: {"status":"healthy","version":"0.1.3",...}

2. Discovery endpoints:

# OAuth server metadata
curl http://localhost:3000/.well-known/oauth-authorization-server | jq

# Protected resource metadata
curl http://localhost:3000/.well-known/oauth-protected-resource | jq

3. Check logs:

# Docker (using scripts/local)
docker service logs seed-local_seed -f

# systemd
sudo journalctl -u seed -f

# Direct run
# Check console output

Troubleshooting

Port Already in Use

# Error: EADDRINUSE :::3000

# Find process
lsof -i :3000

# Kill process
kill -9 <PID>

# Or change port
PORT=3001 npm start

Redis Connection Failed

# Error: connect ECONNREFUSED 127.0.0.1:6379

# For Docker deployment - Redis should be running in the stack
docker service ls | grep redis

# For source installation - check Redis is running
redis-cli ping

# Check connection URL
echo $REDIS_URL

# Start Redis (source installation)
# macOS: brew services start redis
# Linux: sudo systemctl start redis

Permission Denied

# Error: EACCES: permission denied

# Fix permissions
sudo chown -R $(whoami) /opt/seed

# Or run with correct user
sudo -u seed npm start

Next Steps

• Configuration - Configure OIDC and OAuth
• Quick Start - Run Seed for the first time
• First Steps - Make your first request

Related Documentation

• Development Setup - For contributing to Seed
• Architecture Overview - Understanding Seed's design
• Deployment Guide - Production deployment details