Quick Start

Get Seed MCP Server up and running in minutes. This guide assumes you've completed Installation and Configuration.

Prerequisites Checklist

Before starting, ensure you have:

[ ] Seed installed (Docker with ./scripts/local or from source)
[ ] .env file configured (or environment variables set)
[ ] OIDC provider configured (if using authentication)

Redis Included

When using ./scripts/local, Redis is automatically included in the Docker stack - no separate Redis installation needed!

Starting Seed

Option 1: Docker (Recommended)

Using the ./scripts/local script, which deploys Seed with Redis using Docker Swarm:

bash

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

# View logs
docker service logs seed-local_seed -f

# Check status
docker service ls
docker service ps seed-local_seed

Option 2: From Source

bash

# Start Redis (if not already running)
redis-cli ping  # Should return PONG

# Start Seed
npm start

# Or with development mode (hot reload)
npm run dev

Verifying Installation

1. Check Health Endpoint

The health endpoint is publicly accessible and doesn't require authentication.

bash

curl http://localhost:3000/health

Expected response:

json

{
  "status": "healthy",
  "version": "0.1.3",
  "uptime": 12.345,
  "timestamp": "2025-12-09T10:30:00.000Z"
}

Status codes:

200 OK - Server is healthy
503 Service Unavailable - Server is starting or unhealthy

2. Check Discovery Endpoints

Seed provides OAuth 2.1 metadata endpoints for client discovery.

OAuth Authorization Server Metadata:

bash

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

Expected response:

json

{
  "issuer": "https://seed.example.com",
  "authorization_endpoint": "https://auth.example.com/application/o/authorize/",
  "token_endpoint": "https://seed.example.com/oauth/token",
  "registration_endpoint": "https://seed.example.com/oauth/register",
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "response_types_supported": ["code"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"]
}

OAuth Protected Resource Metadata:

bash

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

Expected response:

json

{
  "resource": "https://seed.example.com",
  "authorization_servers": ["https://seed.example.com"]
}

3. Check Logs

Verify Seed started without errors:

Docker (using ./scripts/local):

bash

docker service logs seed-local_seed --tail 20

From Source: Check terminal output for startup messages.

Expected log output:

[INFO] Seed MCP Server v0.1.3
[INFO] Environment: production
[INFO] Port: 3000
[INFO] Auth required: true
[INFO] OIDC Issuer: https://auth.example.com/...
[INFO] Redis connected: redis://redis:6379
[INFO] Server listening on http://localhost:3000

Testing Without Authentication

For testing purposes, you can disable authentication to verify basic functionality.

Development Only

Never use AUTH_REQUIRED=false in production!

1. Update configuration:

bash

# In .env file
AUTH_REQUIRED=false

2. Restart Seed

3. Test MCP endpoint:

bash

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "test-client",
        "version": "1.0.0"
      }
    }
  }'

Expected response:

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "serverInfo": {
      "name": "seed",
      "version": "0.1.3"
    },
    "capabilities": {
      "tools": {}
    }
  }
}

Testing With Authentication

1. Get Access Token

You need a valid JWT token from your OIDC provider. The method depends on your provider:

For testing, use your provider's token endpoint:

bash

# Example with password grant (if supported by your IdP)
curl -X POST https://auth.example.com/application/o/token/ \
  -d "grant_type=password" \
  -d "username=your-username" \
  -d "password=your-password" \
  -d "client_id=your-client-id" \
  -d "scope=openid"

Or use your provider's web interface to obtain a token.

2. Test MCP Endpoint with Authentication

bash

# Replace YOUR_ACCESS_TOKEN with actual JWT
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

Expected response:

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "seed_ping",
        "description": "Health check tool - returns server status",
        "inputSchema": {
          "type": "object",
          "properties": {},
          "additionalProperties": false
        }
      }
    ]
  }
}

3. Test MCP Tool

bash

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "seed_ping",
      "arguments": {}
    }
  }'

Expected response:

json

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"status\":\"ok\",\"version\":\"0.1.3\",\"timestamp\":\"2025-12-09T10:30:00.000Z\"}"
      }
    ]
  }
}

Common Startup Issues

Port Already in Use

Error:

Error: listen EADDRINUSE: address already in use :::3000

Solution:

bash

# Find process using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

# Or change the port
PORT=3001 npm start

Redis Connection Failed

Error:

Error: connect ECONNREFUSED 127.0.0.1:6379

Solution:

bash

# Check if Redis is running
redis-cli ping

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

# Verify REDIS_URL environment variable
echo $REDIS_URL

JWKS Fetch Failed

Error:

Error: Unable to fetch JWKS from issuer

Solution:

Verify OIDC_ISSUER is correct:

bash

echo $OIDC_ISSUER

Test issuer accessibility:

bash

curl $OIDC_ISSUER/.well-known/openid-configuration

Check network connectivity:
- Ensure Seed can reach your OIDC provider
- Check firewall rules
- Verify DNS resolution
Use explicit JWKS URL if auto-discovery fails:

bash

# In .env
OIDC_JWKS_URL=https://auth.example.com/application/o/my-app/jwks/

Invalid Token Errors

Error:

json

{
  "error": {
    "code": -32001,
    "message": "Unauthorized",
    "data": {
      "reason": "invalid_token",
      "details": "JWT verification failed"
    }
  }
}

Solutions:

Check token hasn't expired:

bash

# Decode JWT (without verification)
echo "YOUR_TOKEN" | cut -d. -f2 | base64 -d | jq

Verify OIDC_AUDIENCE matches token audience:

bash

# Token 'aud' claim must match OIDC_AUDIENCE
echo $OIDC_AUDIENCE

Verify OIDC_ISSUER matches token issuer:

bash

# Token 'iss' claim must match OIDC_ISSUER
echo $OIDC_ISSUER

Check token is in correct format:

bash

# Should be: Authorization: Bearer <JWT>
# Not: Authorization: <JWT>

Module Import Errors

Error:

Error [ERR_MODULE_NOT_FOUND]: Cannot find module

Solution:

bash

# Rebuild the project
npm run build

# Or reinstall dependencies
rm -rf node_modules package-lock.json
npm install
npm run build

Next Steps

Now that Seed is running, you can:

First Steps - Make your first authenticated request and register a client
Configuration - Fine-tune your configuration
API Reference - Explore available endpoints
Architecture - Understand how Seed works

Quick Reference

Useful Commands

Task	Command
Check health	`curl http://localhost:3000/health`
View logs (Docker)	`docker service logs -f seed-local_seed`
Restart (Docker)	`docker service update --force seed-local_seed`
Stop (Docker)	`docker stack rm seed-local`
Check Redis	`docker exec $(docker ps -qf name=seed-local_redis) redis-cli ping`

Environment Variables Quick Check

bash

# Verify critical environment variables
echo "PORT: $PORT"
echo "AUTH_REQUIRED: $AUTH_REQUIRED"
echo "OIDC_ISSUER: $OIDC_ISSUER"
echo "OIDC_AUDIENCE: $OIDC_AUDIENCE"
echo "REDIS_URL: $REDIS_URL"

Health Check Script

Save as check-seed.sh:

bash

#!/bin/bash

echo "Checking Seed health..."
HEALTH=$(curl -s http://localhost:3000/health)

if echo "$HEALTH" | jq -e '.status == "healthy"' > /dev/null; then
  echo "✓ Seed is healthy"
  echo "$HEALTH" | jq
  exit 0
else
  echo "✗ Seed is not healthy"
  echo "$HEALTH"
  exit 1
fi

Make executable:

bash

chmod +x check-seed.sh
./check-seed.sh

Getting Help

If you encounter issues:

Check the Troubleshooting section above
Review Configuration for setup errors
Check logs for error messages
Verify all prerequisites are met
Consult Architecture: Authentication for auth issues

Installation - Installation methods
Configuration - Configuration reference
First Steps - Guided walkthrough
API: Discovery - Discovery endpoint details

Quick Start ​

Prerequisites Checklist ​

Starting Seed ​

Option 1: Docker (Recommended) ​

Option 2: From Source ​

Verifying Installation ​

1. Check Health Endpoint ​

2. Check Discovery Endpoints ​

3. Check Logs ​

Testing Without Authentication ​

Testing With Authentication ​

1. Get Access Token ​

2. Test MCP Endpoint with Authentication ​

3. Test MCP Tool ​

Common Startup Issues ​

Port Already in Use ​

Redis Connection Failed ​

JWKS Fetch Failed ​

Invalid Token Errors ​

Module Import Errors ​

Next Steps ​

Quick Reference ​

Useful Commands ​

Environment Variables Quick Check ​

Health Check Script ​

Getting Help ​

Related Documentation ​

Quick Start

Prerequisites Checklist

Starting Seed

Option 1: Docker (Recommended)

Option 2: From Source

Verifying Installation

1. Check Health Endpoint

2. Check Discovery Endpoints

3. Check Logs

Testing Without Authentication

Testing With Authentication

1. Get Access Token

2. Test MCP Endpoint with Authentication

3. Test MCP Tool

Common Startup Issues

Port Already in Use

Redis Connection Failed

JWKS Fetch Failed

Invalid Token Errors

Module Import Errors

Next Steps

Quick Reference

Useful Commands

Environment Variables Quick Check

Health Check Script

Getting Help

Related Documentation