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 production
From Source - For development or custom builds
Docker Compose - Complete stack with Redis

Docker Installation

Pull Pre-built Image

Coming Soon

Pre-built Docker images will be available on Docker Hub or GitLab Container Registry.

bash

# Once available
docker pull registry.example.com/mcp-servers/seed:latest

Build from Dockerfile

bash

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

# Build image
docker build -t seed:latest .

# Run container
docker run -d \
  --name seed \
  -p 3000:3000 \
  -e AUTH_REQUIRED=true \
  -e OIDC_ISSUER=https://auth.example.com/application/o/my-app/ \
  -e OIDC_AUDIENCE=my-client-id \
  -e OAUTH_TOKEN_URL=https://auth.example.com/application/o/token/ \
  -e OAUTH_AUTHORIZATION_URL=https://auth.example.com/application/o/authorize/ \
  -e REDIS_URL=redis://redis:6379 \
  seed:latest

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)

Docker Compose

The easiest way to run Seed with all dependencies.

Create docker-compose.yml

yaml

version: '3.8'

services:
  redis:
    image: redis:7-alpine
    container_name: seed-redis
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data
    command: redis-server --appendonly yes
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 3

  seed:
    image: seed:latest  # or build: .
    container_name: seed
    ports:
      - "3000:3000"
    environment:
      # Server
      PORT: 3000
      BASE_URL: https://seed.example.com

      # Authentication
      AUTH_REQUIRED: "true"

      # OIDC Configuration
      OIDC_ISSUER: https://auth.example.com/application/o/my-app/
      OIDC_AUDIENCE: my-client-id

      # OAuth Endpoints
      OAUTH_TOKEN_URL: https://auth.example.com/application/o/token/
      OAUTH_AUTHORIZATION_URL: https://auth.example.com/application/o/authorize/

      # Redis
      REDIS_URL: redis://redis:6379

      # DCR Configuration
      DCR_CLIENT_TTL: 2592000  # 30 days
      DCR_RATE_LIMIT_MAX: 10
      DCR_RATE_LIMIT_WINDOW_MS: 3600000  # 1 hour

    depends_on:
      redis:
        condition: service_healthy
    restart: unless-stopped

volumes:
  redis-data:
    driver: local

Start Services

bash

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f seed

# Stop services
docker-compose down

# Stop and remove volumes
docker-compose down -v

Verify Installation

bash

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

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

From Source

Install and run Seed from source code.

1. Clone Repository

bash

# 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

bash

npm install

This installs:

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

3. Configure Environment

bash

# Copy example configuration
cp .env.example .env

# Edit configuration
vim .env

See Configuration for detailed setup.

4. Build

bash

# Compile TypeScript to JavaScript
npm run build

Output: dist/ directory

5. Run

Production mode:

bash

npm start

Development mode (with hot reload):

bash

npm run dev

Verify:

bash

curl http://localhost:3000/health

Redis Setup

Seed requires Redis for session storage and dynamic client registration.

Local Redis

macOS (Homebrew):

bash

brew install redis
brew services start redis

Ubuntu/Debian:

bash

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

Verify:

bash

redis-cli ping
# Should return: PONG

Docker Redis

bash

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:

bash

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

Redis URL formats:

bash

# 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

System Requirements

Minimum Requirements

CPU: 1 core
RAM: 512MB
Disk: 100MB (application + logs)
Network: 1 Mbps

Recommended Requirements

CPU: 2 cores
RAM: 1GB
Disk: 1GB (with Redis persistence)
Network: 10 Mbps

Scaling

For high-traffic deployments:

Multiple instances: Load balance behind nginx/HAProxy
Redis cluster: Use Redis Cluster or Sentinel
Horizontal scaling: Stateless design allows easy scaling

Production Deployment

Using Docker

Build optimized image:

bash

docker build \
  --build-arg VERSION=$(node -p "require('./package.json').version") \
  -t seed:$(node -p "require('./package.json').version") \
  .

Run with docker:

bash

docker run -d \
  --name seed-prod \
  --restart unless-stopped \
  -p 3000:3000 \
  -e NODE_ENV=production \
  --env-file .env.production \
  seed:0.1.3

Using systemd

Create /etc/systemd/system/seed.service:

ini

[Unit]
Description=Seed MCP Server
After=network.target redis.service

[Service]
Type=simple
User=seed
WorkingDirectory=/opt/seed
Environment=NODE_ENV=production
EnvironmentFile=/opt/seed/.env
ExecStart=/usr/bin/node /opt/seed/dist/index.js
Restart=always
RestartSec=10

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/seed/logs

[Install]
WantedBy=multi-user.target

Start service:

bash

sudo systemctl daemon-reload
sudo systemctl enable seed
sudo systemctl start seed
sudo systemctl status seed

Behind Nginx

Example nginx configuration:

nginx

upstream seed {
    server 127.0.0.1:3000;
    # Add more servers for load balancing
    # server 127.0.0.1:3001;
}

server {
    listen 80;
    server_name seed.example.com;

    # Redirect to HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name seed.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    # Security headers
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    add_header X-Frame-Options "DENY" always;
    add_header X-Content-Type-Options "nosniff" always;

    location / {
        proxy_pass http://seed;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Timeouts
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }

    # Health check endpoint (bypass auth)
    location /health {
        proxy_pass http://seed;
        access_log off;
    }
}

Upgrading

From Source

bash

# 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

bash

# Pull new image
docker pull seed:latest

# Stop and remove old container
docker stop seed
docker rm seed

# Start new container
docker run -d --name seed <...same args as before...> seed:latest

Docker Compose

bash

# Pull new images
docker-compose pull

# Restart services
docker-compose up -d

Verification

After installation, verify Seed is working:

1. Health check:

bash

curl http://localhost:3000/health

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

2. Discovery endpoints:

bash

# 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:

bash

# Docker
docker logs seed

# systemd
sudo journalctl -u seed -f

# Direct run
# Check console output

Troubleshooting

Port Already in Use

bash

# Error: EADDRINUSE :::3000

# Find process
lsof -i :3000

# Kill process
kill -9 <PID>

# Or change port
PORT=3001 npm start

Redis Connection Failed

bash

# Error: connect ECONNREFUSED 127.0.0.1:6379

# Check Redis is running
redis-cli ping

# Check connection URL
echo $REDIS_URL

# Start Redis
# macOS: brew services start redis
# Linux: sudo systemctl start redis
# Docker: docker start redis

Permission Denied

bash

# 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

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

Installation ​

Prerequisites ​

Installation Methods ​

Docker Installation ​

Pull Pre-built Image ​

Build from Dockerfile ​

Docker Image Details ​

Docker Compose ​

Create docker-compose.yml ​

Start Services ​

Verify Installation ​

From Source ​

1. Clone Repository ​

2. Install Dependencies ​

3. Configure Environment ​

4. Build ​

5. Run ​

Redis Setup ​

Local Redis ​

Docker Redis ​

Redis Configuration ​

System Requirements ​

Minimum Requirements ​

Recommended Requirements ​

Scaling ​

Production Deployment ​

Using Docker ​

Using systemd ​

Behind Nginx ​

Upgrading ​

From Source ​

Docker ​

Docker Compose ​

Verification ​

Troubleshooting ​

Port Already in Use ​

Redis Connection Failed ​

Permission Denied ​

Next Steps ​

Related Documentation ​

Installation

Prerequisites

Installation Methods

Docker Installation

Pull Pre-built Image

Build from Dockerfile

Docker Image Details

Docker Compose

Create docker-compose.yml

Start Services

Verify Installation

From Source

1. Clone Repository

2. Install Dependencies

3. Configure Environment

4. Build

5. Run

Redis Setup

Local Redis

Docker Redis

Redis Configuration

System Requirements

Minimum Requirements

Recommended Requirements

Scaling

Production Deployment

Using Docker

Using systemd

Behind Nginx

Upgrading

From Source

Docker

Docker Compose

Verification

Troubleshooting

Port Already in Use

Redis Connection Failed

Permission Denied

Next Steps

Related Documentation