Developer Guide

Welcome to the Seed MCP Server developer documentation. This guide is for developers who want to install, configure, deploy, or extend Seed.

For Users

If you're looking to connect Claude Desktop or Claude Code to an existing Seed server, see the Connecting Guide instead.

What is Seed?

Seed is an MCP (Model Context Protocol) server with enterprise-grade OIDC/OAuth 2.0 authentication. It provides:

• Authentication Infrastructure - JWT validation, JWKS caching, OAuth 2.1 with PKCE
• MCP Protocol Implementation - Complete server-side MCP support
• Extensible Framework - Add custom tools, prompts, and resources
• Production Ready - Session management, Redis storage, rate limiting

Developer Documentation Sections

Getting Started

Installation, configuration, and first deployment:

• Prerequisites - Node.js, Redis, OIDC provider requirements
• Installation - Docker, Docker Compose, or from source
• Configuration - Environment variables and OIDC setup
• Quick Start - Run Seed for the first time
• First Steps - Complete OAuth flow and make MCP requests

Start here if: You're setting up Seed for the first time

Deploying

Production deployment strategies:

• Deployment Overview - Options and recommendations
• Deploy with OIDC - Production setup with authentication
• Deploy without OIDC - Development/internal deployments

Start here if: You're deploying to production or staging

Architecture

Deep dives into Seed's design and implementation:

• Authentication Flow - How JWT validation works
• OAuth 2.1 Implementation - Authorization code flow with PKCE
• MCP Server Design - Transport management and session handling
• Session Management - Redis-backed session storage
• Configuration System - Environment variable management

Start here if: You want to understand how Seed works internally

API Reference

Complete HTTP API documentation:

• Authentication Endpoints - JWT validation
• OAuth Endpoints - Authorization, token, and registration
• MCP Endpoints - JSON-RPC protocol over HTTP
• Health & Discovery - Monitoring and metadata

Start here if: You're building clients or integrations

Development

Contributing to Seed:

• Development Setup - Local environment configuration
• Testing Guide - Running and writing tests
• Code Quality - Linting, type checking, and standards
• Adding MCP Tools - Create custom tools
• Contributing - How to contribute code

Start here if: You're contributing to Seed or building extensions

Quick Links

Common Tasks

Installing Seed:

# Using Docker Compose (recommended)
docker-compose up -d

See Installation for details.

Configuring OIDC:

cp .env.example .env
# Edit .env with your OIDC provider settings

See Configuration for all options.

Running Tests:

npm test
npm run test:coverage

See Testing Guide for more.

Adding a Tool:

1. Create file in src/mcp/tools/your-tool.ts
2. Register in src/mcp/tools/index.ts
3. Document in /wiki/tools/your-tool.md

See Adding MCP Tools for details.

Prerequisites

Before you begin development:

• Node.js >= 24.0.0 - Seed requires Node.js version 24 or higher
• Redis - For session storage and client registration
• OIDC Provider - Any compliant IdP (Authentik, Okta, Auth0, Keycloak, etc.)
• Git - For version control

Optional but recommended:

• Docker - For containerized deployment
• docker-compose - For orchestrating services
• TypeScript knowledge - Seed is written in TypeScript

Architecture at a Glance

┌─────────────┐
│   Claude    │
│   Client    │
└──────┬──────┘
       │ MCP/HTTP
       ▼
┌─────────────────────────────────────┐
│         Seed MCP Server             │
│                                     │
│  ┌─────────────┐  ┌──────────────┐ │
│  │ Auth        │  │ MCP Protocol │ │
│  │ Middleware  │──│ Handler      │ │
│  └─────────────┘  └──────────────┘ │
│                                     │
│  ┌─────────────┐  ┌──────────────┐ │
│  │ Tools       │  │ Prompts      │ │
│  └─────────────┘  └──────────────┘ │
│                                     │
│  ┌─────────────┐  ┌──────────────┐ │
│  │ Resources   │  │ Sessions     │ │
│  └─────────────┘  └──────────────┘ │
└────────┬────────────────────┬──────┘
         │                    │
         ▼                    ▼
    ┌─────────┐          ┌────────┐
    │  OIDC   │          │ Redis  │
    │Provider │          │        │
    └─────────┘          └────────┘

See Architecture for detailed documentation.

Technology Stack

• Runtime: Node.js 24+
• Language: TypeScript 5.x
• Framework: Express.js
• MCP SDK: @modelcontextprotocol/sdk
• Authentication: jsonwebtoken, jwks-rsa
• Storage: Redis (ioredis)
• Testing: Vitest, supertest
• Code Quality: ESLint, Prettier, TypeScript strict mode

Production Operations

Running Seed in production:

• Security Hardening - HTTPS, authentication, rate limiting, firewalls
• Redis Configuration - Production setup, clustering, monitoring
• Logging & Debugging - Structured logging, error tracking, debug mode
• Monitoring - Metrics, alerting, health checks
• Performance Tuning - Optimization strategies and scaling
• Backup & Recovery - Data protection and disaster recovery

Start here if: You're operating Seed in production

Future Enhancements

Potential future improvements and additions:

• Session IP Binding - Prevent session hijacking
• Role-Based Access Control - Fine-grained tool permissions
• Audit Logging - Compliance-ready audit trails
• Distributed Tracing - OpenTelemetry integration

Start here if: You want to see planned features or contribute enhancements

Project Report Cards

Regular comprehensive assessments of code quality, security, and best practices:

• Overview - Assessment methodology and generation guide
• January 5, 2026 - Initial assessment (Grade: A-, 90/100)

Start here if: You want to review project health and quality metrics

Community & Support

• GitLab: mcp-servers/seed
• Issues: Report bugs or request features
• Troubleshooting: Common issues and solutions
• FAQ: Frequently asked questions
• License: MIT

Contributing

We welcome contributions! See Contributing Guide for:

• Code of conduct
• Development workflow
• Pull request process
• Coding standards

Next Steps

New to Seed? Follow this path:

1. Installation - Get Seed installed
2. Configuration - Configure environment
3. Quick Start - Run Seed locally
4. First Steps - Make first MCP request
5. Architecture - Understand the design

Ready to extend Seed?

1. Development Setup - Configure dev environment
2. Adding Tools - Create custom tools
3. Testing - Write and run tests
4. Contributing - Submit your changes