Configuration

Learn how to configure Seed for your OIDC provider and customize its behavior.

Configuration Overview

Seed is configured entirely through environment variables, either in a .env file or passed directly to the container/process.

Configuration file: .env

bash

cp .env.example .env
vim .env

Required Configuration

Minimum Configuration (No Auth)

For testing or development:

bash

PORT=3000
AUTH_REQUIRED=false

Development Only

Never deploy to production with AUTH_REQUIRED=false. This disables all authentication!

Full Production Configuration

For production with OIDC authentication:

bash

# Server
PORT=3000
BASE_URL=https://seed.example.com

# Authentication
AUTH_REQUIRED=true

# OIDC Provider
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://localhost:6379

Environment Variables Reference

Server Configuration

Variable	Required	Default	Description
`PORT`	No	`3000`	HTTP server port
`BASE_URL`	No	``	Base URL for WWW-Authenticate header
`NODE_ENV`	No	`development`	Environment mode (`development`, `production`)

Example:

bash

PORT=8080
BASE_URL=https://seed.mycompany.com
NODE_ENV=production

Authentication Configuration

Variable	Required	Default	Description
`AUTH_REQUIRED`	No	`true`	Enable/disable authentication

Example:

bash

# Production: Enable authentication
AUTH_REQUIRED=true

# Development: Disable authentication
AUTH_REQUIRED=false

OIDC Configuration

Variable	Required	Default	Description
`OIDC_ISSUER`	Yes*	``	OIDC issuer URL (used for JWT validation and JWKS discovery)
`OIDC_AUDIENCE`	Yes*	``	Expected audience claim in JWT (client ID)
`OIDC_JWKS_URL`	No	Auto-discovered	Explicit JWKS URL (overrides discovery)

* Required when AUTH_REQUIRED=true

Example:

bash

OIDC_ISSUER=https://authentik.company.com/application/o/seed/
OIDC_AUDIENCE=seed-client-abc123

OAuth Endpoints

Variable	Required	Default	Description
`OAUTH_TOKEN_URL`	Yes*	``	Token endpoint for code exchange
`OAUTH_AUTHORIZATION_URL`	Yes*	``	Authorization endpoint for user login

* Required when AUTH_REQUIRED=true

Example:

bash

OAUTH_TOKEN_URL=https://authentik.company.com/application/o/token/
OAUTH_AUTHORIZATION_URL=https://authentik.company.com/application/o/authorize/

Redis Configuration

Variable	Required	Default	Description
`REDIS_URL`	No	`redis://redis:6379`	Redis connection URL

Example:

bash

# Local
REDIS_URL=redis://localhost:6379

# With password
REDIS_URL=redis://:mypassword@localhost:6379

# Remote with TLS
REDIS_URL=rediss://user:pass@redis.example.com:6380

# Custom database
REDIS_URL=redis://localhost:6379/2

Dynamic Client Registration (DCR)

Variable	Required	Default	Description
`DCR_CLIENT_TTL`	No	`2592000`	Client TTL in seconds (30 days)
`DCR_RATE_LIMIT_MAX`	No	`10`	Max registrations per window
`DCR_RATE_LIMIT_WINDOW_MS`	No	`3600000`	Rate limit window (1 hour)

Example:

bash

DCR_CLIENT_TTL=604800          # 7 days
DCR_RATE_LIMIT_MAX=5           # 5 registrations
DCR_RATE_LIMIT_WINDOW_MS=1800000  # 30 minutes

CORS Configuration

Variable	Required	Default	Description
`CORS_EXTRA_ORIGINS`	No	``	Additional CORS origins (comma-separated)

Default origins: localhost, claude.ai, *.anthropic.com

Example:

bash

CORS_EXTRA_ORIGINS=https://app.company.com,https://dev.company.com

OIDC Provider Examples

Authentik

Authentik is an open-source identity provider.

1. Create OAuth2/OpenID Provider in Authentik:

Name: Seed MCP Server
Client type: Confidential
Redirect URIs: Add client callback URLs

2. Get configuration values:

Issuer: https://authentik.company.com/application/o/seed/
Token URL: https://authentik.company.com/application/o/token/
Authorization URL: https://authentik.company.com/application/o/authorize/
Client ID: Copy from provider settings

3. Configure Seed:

bash

OIDC_ISSUER=https://authentik.company.com/application/o/seed/
OIDC_AUDIENCE=your-client-id
OAUTH_TOKEN_URL=https://authentik.company.com/application/o/token/
OAUTH_AUTHORIZATION_URL=https://authentik.company.com/application/o/authorize/

Keycloak

Keycloak is a popular open-source identity solution.

1. Create Client in Keycloak:

Realm: Select or create realm
Client ID: seed-mcp
Client Protocol: openid-connect
Access Type: confidential
Valid Redirect URIs: Add client callback URLs

2. Get configuration values:

Issuer: https://keycloak.company.com/realms/myrealm
Well-known URL: https://keycloak.company.com/realms/myrealm/.well-known/openid-configuration
Copy token_endpoint and authorization_endpoint

3. Configure Seed:

bash

OIDC_ISSUER=https://keycloak.company.com/realms/myrealm
OIDC_AUDIENCE=seed-mcp
OAUTH_TOKEN_URL=https://keycloak.company.com/realms/myrealm/protocol/openid-connect/token
OAUTH_AUTHORIZATION_URL=https://keycloak.company.com/realms/myrealm/protocol/openid-connect/auth

Auth0

Auth0 is a commercial identity platform.

1. Create Application in Auth0:

Type: Regular Web Application
Name: Seed MCP Server
Add Allowed Callback URLs

2. Get configuration values:

Domain: your-tenant.auth0.com
Client ID: From application settings
Issuer: https://your-tenant.auth0.com/

3. Configure Seed:

bash

OIDC_ISSUER=https://your-tenant.auth0.com/
OIDC_AUDIENCE=your-client-id
OAUTH_TOKEN_URL=https://your-tenant.auth0.com/oauth/token
OAUTH_AUTHORIZATION_URL=https://your-tenant.auth0.com/authorize

Okta

Okta is an enterprise identity provider.

1. Create Application in Okta:

Type: Web Application
Grant types: Authorization Code, Refresh Token
Add Sign-in redirect URIs

2. Get configuration values:

Domain: your-org.okta.com
Authorization Server: default or custom
Issuer: https://your-org.okta.com/oauth2/default

3. Configure Seed:

bash

OIDC_ISSUER=https://your-org.okta.com/oauth2/default
OIDC_AUDIENCE=your-client-id
OAUTH_TOKEN_URL=https://your-org.okta.com/oauth2/default/v1/token
OAUTH_AUTHORIZATION_URL=https://your-org.okta.com/oauth2/default/v1/authorize

Google Identity

Google Identity for Google Cloud.

1. Create OAuth 2.0 Client:

Console: Google Cloud Console → APIs & Services → Credentials
Type: Web application
Add Authorized redirect URIs

2. Get configuration values:

Issuer: https://accounts.google.com
Client ID: From credentials page

3. Configure Seed:

bash

OIDC_ISSUER=https://accounts.google.com
OIDC_AUDIENCE=your-client-id.apps.googleusercontent.com
OAUTH_TOKEN_URL=https://oauth2.googleapis.com/token
OAUTH_AUTHORIZATION_URL=https://accounts.google.com/o/oauth2/v2/auth

Microsoft Entra ID (Azure AD)

Microsoft Entra ID (formerly Azure AD).

1. Register Application:

Portal: Azure Portal → Entra ID → App registrations
Type: Web
Add Redirect URIs

2. Get configuration values:

Tenant ID: From app overview
Client ID: Application (client) ID
Issuer: https://login.microsoftonline.com/{tenant-id}/v2.0

3. Configure Seed:

bash

OIDC_ISSUER=https://login.microsoftonline.com/your-tenant-id/v2.0
OIDC_AUDIENCE=your-client-id
OAUTH_TOKEN_URL=https://login.microsoftonline.com/your-tenant-id/oauth2/v2.0/token
OAUTH_AUTHORIZATION_URL=https://login.microsoftonline.com/your-tenant-id/oauth2/v2.0/authorize

Configuration Validation

Test Configuration

After configuring, test the setup:

1. Start Seed:

bash

npm start

2. Check health:

bash

curl http://localhost:3000/health

3. Test discovery:

bash

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

4. Verify OIDC issuer:

bash

# Should return JWKS
curl $OIDC_ISSUER/.well-known/openid-configuration

Common Issues

Issuer Mismatch:

Error: JWT issuer does not match OIDC_ISSUER

Solution: Ensure OIDC_ISSUER exactly matches the iss claim in tokens.

JWKS Not Found:

Error: Unable to fetch JWKS from issuer

Solution:

Verify OIDC_ISSUER is accessible
Check OIDC provider returns valid OpenID configuration
Use OIDC_JWKS_URL to specify explicit JWKS endpoint

Audience Mismatch:

Error: JWT audience does not match OIDC_AUDIENCE

Solution: Ensure OIDC_AUDIENCE matches the aud claim in tokens (usually the client ID).

Security Best Practices

Production Checklist

[ ] AUTH_REQUIRED=true enabled
[ ] Strong Redis password (if exposed)
[ ] HTTPS enabled (via reverse proxy)
[ ] BASE_URL set to public HTTPS URL
[ ] OIDC endpoints use HTTPS
[ ] Redis uses rediss:// for TLS (if remote)
[ ] Rate limiting configured appropriately
[ ] Client TTL set according to security policy

Environment File Security

Protect .env file:

bash

# Set restrictive permissions
chmod 600 .env

# Never commit to git
echo ".env" >> .gitignore

Use secrets management in production:

Docker: Use secrets or env files
Kubernetes: Use Secrets
systemd: Use EnvironmentFile with restricted permissions

CORS Configuration

Limit CORS origins to trusted domains:

bash

# Bad: Allows all origins
# Don't set CORS_EXTRA_ORIGINS to wildcard

# Good: Specific origins
CORS_EXTRA_ORIGINS=https://app.company.com,https://internal.company.com

Advanced Configuration

Multiple Environments

Use different .env files:

bash

# Development
cp .env.example .env.development
# Edit for local development

# Production
cp .env.example .env.production
# Edit for production

# Load specific environment
NODE_ENV=production node dist/index.js

Docker Environment

Pass via environment variables:

bash

docker run -d \
  -e AUTH_REQUIRED=true \
  -e OIDC_ISSUER=https://auth.example.com/... \
  -e OIDC_AUDIENCE=client-id \
  -e OAUTH_TOKEN_URL=https://auth.example.com/token \
  -e OAUTH_AUTHORIZATION_URL=https://auth.example.com/authorize \
  -e REDIS_URL=redis://redis:6379 \
  seed:latest

Or use env file:

bash

docker run -d --env-file .env.production seed:latest

Kubernetes ConfigMap

yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: seed-config
data:
  PORT: "3000"
  AUTH_REQUIRED: "true"
  OIDC_ISSUER: "https://auth.example.com/application/o/seed/"
  REDIS_URL: "redis://redis-service:6379"

Use in deployment:

yaml

envFrom:
  - configMapRef:
      name: seed-config
  - secretRef:
      name: seed-secrets  # For sensitive values

Next Steps

Quick Start - Run Seed with your configuration
First Steps - Test your setup
Architecture: Configuration - Deep dive into configuration system

Authentication Flow - How JWT validation works
OAuth Implementation - OAuth 2.1 flow details
API: Discovery - Discovery endpoint documentation

Configuration ​

Configuration Overview ​

Required Configuration ​

Minimum Configuration (No Auth) ​

Full Production Configuration ​

Environment Variables Reference ​

Server Configuration ​

Authentication Configuration ​

OIDC Configuration ​

OAuth Endpoints ​

Redis Configuration ​

Dynamic Client Registration (DCR) ​

CORS Configuration ​

OIDC Provider Examples ​

Authentik ​

Keycloak ​

Auth0 ​

Okta ​

Google Identity ​

Microsoft Entra ID (Azure AD) ​

Configuration Validation ​

Test Configuration ​

Common Issues ​

Security Best Practices ​

Production Checklist ​

Environment File Security ​

CORS Configuration ​

Advanced Configuration ​

Multiple Environments ​

Docker Environment ​

Kubernetes ConfigMap ​

Next Steps ​

Related Documentation ​

Configuration

Configuration Overview

Required Configuration

Minimum Configuration (No Auth)

Full Production Configuration

Environment Variables Reference

Server Configuration

Authentication Configuration

OIDC Configuration

OAuth Endpoints

Redis Configuration

Dynamic Client Registration (DCR)

CORS Configuration

OIDC Provider Examples

Authentik

Keycloak

Auth0

Okta

Google Identity

Microsoft Entra ID (Azure AD)

Configuration Validation

Test Configuration

Common Issues

Security Best Practices

Production Checklist

Environment File Security

CORS Configuration

Advanced Configuration

Multiple Environments

Docker Environment

Kubernetes ConfigMap

Next Steps

Related Documentation