SelfMemory

# SelfMemory MCP Server Configuration # Copy this file to .env and update the values for your environment # ==================================== # Server Selection # ==================================== # Choose which MCP server to run: # - main_unified.py (RECOMMENDED): Supports both OAuth 2.1 AND API key authentication # - main_oauth.py: OAuth 2.1 only # - main.py: API key only (legacy) # ==================================== # Core Configuration # ==================================== # SelfMemory API Configuration # This is where your core SelfMemory server is running # Required for BOTH OAuth and API key validation SELFMEMORY_API_HOST=http://127.0.0.1:8081 # MCP Server Configuration # Host and port where the MCP server will listen for client connections MCP_SERVER_HOST=0.0.0.0 MCP_SERVER_PORT=5055 # ==================================== # Ory Hydra OAuth 2.1 Configuration (REQUIRED) # ==================================== # Hydra Admin URL (Required) # Used by MCP server for token introspection # For local development: http://127.0.0.1:4445 # For production: https://your-hydra-admin.example.com HYDRA_ADMIN_URL=http://127.0.0.1:4445 # Hydra Public URL (Required) # Used for OAuth discovery metadata # For local development: http://127.0.0.1:4444 # For production: https://your-hydra-public.example.com HYDRA_PUBLIC_URL=http://127.0.0.1:4444 # MCP Server URL (Required) # This is YOUR server's URL that clients will connect to # For local development: http://127.0.0.1:5055 # For production: https://your-mcp-server.example.com MCP_SERVER_URL=http://127.0.0.1:5055 # Kratos URLs (Required - needed by server package imports) # For local development KRATOS_PUBLIC_URL=http://127.0.0.1:4433 KRATOS_ADMIN_URL=http://127.0.0.1:4434 # ==================================== # Optional Configuration # ==================================== # Development Mode # Set to true to enable auto-reload on code changes MCP_DEV_MODE=false # Logging Configuration # Set log level: DEBUG, INFO, WARNING, ERROR, CRITICAL LOG_LEVEL=INFO # Development/Production Mode # Set to true for development mode with additional logging DEBUG=false # ==================================== # UNIFIED AUTHENTICATION (main_unified.py) # ==================================== # The unified server supports BOTH authentication methods: # # 1. OAuth 2.1 (Recommended - Modern clients) # - Automatic via OAuth discovery # - Secure with short-lived tokens # - Project selection via consent page # # 2. API Key (Legacy - Backward compatibility) # - Manual with --oauth no flag # - Long-lived credentials # - Simpler for scripts/automation # # BOTH methods work on the SAME endpoint! # ==================================== # OAuth 2.1 Flow (Automatic) # ==================================== # 1. Client discovers OAuth server via /.well-known/oauth-protected-resource # 2. Client registers via dynamic client registration (automatic) # 3. User authorizes via Hydra → Dashboard consent page # 4. Dashboard sends project_id to Hydra in session data # 5. Hydra issues token with ext.project_id claim # 6. Client calls MCP with Bearer token # 7. MCP detects JWT format → validates via HYDRA_ADMIN_URL # 8. MCP extracts project_id from token claims # 9. All memory operations are scoped to that project # ==================================== # API Key Flow (Manual) # ==================================== # 1. User generates API key in dashboard # 2. Client connects with --oauth no flag # 3. Client sends API key as Bearer token # 4. MCP detects non-JWT format → validates via SELFMEMORY_API_HOST # 5. MCP extracts user/project from API key validation # 6. All memory operations are scoped to that project # ==================================== # Client Installation # ==================================== # OAuth 2.1 (Automatic - Recommended): # npx install-mcp http://localhost:5055/mcp --client claude # API Key (Manual - Legacy): # npx install-mcp http://localhost:5055/mcp --client claude \ # --oauth no \ # --header "Authorization: Bearer sk_im_YOUR_API_KEY" # ==================================== # VS Code MCP Configuration Examples # ==================================== # OAuth 2.1 (automatic): # { # "mcpServers": { # "selfmemory": { # "url": "http://localhost:5055/mcp" # } # } # } # API Key (manual): # { # "mcpServers": { # "selfmemory": { # "url": "http://localhost:5055/mcp", # "headers": { # "Authorization": "Bearer sk_im_YOUR_API_KEY" # } # } # } # } # ==================================== # Architecture Notes # ==================================== # main_unified.py implements: # - OAuth 2.0 Protected Resource Metadata (RFC 9728) # - OAuth 2.0 Authorization Server Metadata (RFC 8414) # - Dynamic Client Registration (RFC 7591) # - Automatic authentication detection (JWT vs API key) # # Authentication Flows: # # OAuth 2.1: # - Client → MCP Server (OAuth token validated via Hydra) # - MCP Server → Core Server (OAuth token forwarded) # - Core Server validates token via Hydra # # API Key: # - Client → MCP Server (API key validated via Core Server) # - MCP Server → Core Server (API key forwarded as Bearer token) # - Core Server validates API key and returns user context # # SAME tools work with BOTH authentication methods! # ==================================== # Migration Guide # ==================================== # From main_oauth.py to main_unified.py: # - No changes needed - existing OAuth clients continue working # - Server now also accepts API keys for legacy clients # # From main.py to main_unified.py: # - No changes needed - existing API key clients continue working # - Server now also accepts OAuth for modern clients # # Both auth methods work on the same endpoint! # ==================================== # OpenTelemetry / SigNoz Configuration # ==================================== # Enable OpenTelemetry distributed tracing for performance monitoring # Recommended for production to diagnose bottlenecks and latency issues # Enable/disable OpenTelemetry tracing # Set to true in production for comprehensive performance insights OTEL_ENABLED=false # SigNoz OTLP endpoint (gRPC) # For local SigNoz: http://localhost:4317 # For SigNoz Cloud: https://ingest.{region}.signoz.cloud:443 # Leave empty if OTEL_ENABLED=false OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 # Environment name for telemetry # Used to distinguish between dev/staging/production traces ENVIRONMENT=development # ==================================== # Telemetry Features # ==================================== # The OpenTelemetry implementation automatically captures: # - Full authentication flow timing (OAuth + API key) # - Hydra introspection latency # - Core server API key validation latency # - Middleware dispatch timing # - Protocol version validation # - Request forwarding to MCP handlers # - Tool execution timing # - HTTP client request/response traces (via HTTPX instrumentation) # # Traces include: # - Operation durations (in milliseconds) # - User/Project IDs # - Authentication types # - Scopes granted # - Slow operation warnings (>3s threshold) # - Exception details for failed requests # # View traces in SigNoz to identify: # - Which authentication step is slow (Hydra vs API key validation) # - Network latency between MCP and Core/Hydra servers # - Tool execution bottlenecks # - 307 redirect overhead # - Serialization/deserialization costs