Server and Transport

The Server and Transport layer handles the lifecycle of the Vault Cortex process, from initial bootstrapping and configuration loading to managing stateful MCP sessions over HTTPS. It utilizes Express for routing and the Model Context Protocol (MCP) SDK's StreamableHTTPServerTransport to bridge standard HTTP requests into the MCP protocol.

Server Bootstrapping

The entry point for the server is src/vault-mcp/server.ts. The startServer function orchestrates the initialization of all internal subsystems before starting the HTTP listener src/vault-mcp/server.ts61-147

Initialization Sequence

1. Config Loading: Loads environment variables and validates required fields like MCP_AUTH_TOKEN, VAULT_PATH, and PUBLIC_URL src/vault-mcp/server.ts62-68
2. Search Indexing: Initializes the SearchIndex with an optional embedder and reranker based on embeddingEnabled and rerankMode from the loaded config src/vault-mcp/server.ts85-90 It then performs an initial full-vault crawl via search.rebuildFromVault src/vault-mcp/server.ts93-94
3. Daily Notes: Reads the vault's .obsidian/daily-notes.json via readDailyNotesConfig to configure date-based note resolution in the search index src/vault-mcp/server.ts97-98
4. Memory Layer: If memoryEnabled is true, it initializes the MemoryStore and bootstraps the About Me/ directory with templates src/vault-mcp/server.ts99-103
5. File Watcher: Starts the chokidar watcher via startFileWatcher to maintain index parity with disk changes, supporting polling for Windows bind-mounts src/vault-mcp/server.ts104-106
6. OAuth Provider: Sets up the createOAuthProvider for JWT-based session authentication src/vault-mcp/server.ts109-113
7. Express Setup: Configures middleware (JSON, Proxy trust) and mounts OAuth and MCP routers src/vault-mcp/server.ts115-141

Graceful Shutdown

To prevent data corruption or interrupted writes during deployment updates, the server implements a SIGTERM handler. The createShutdownHandler uses httpServer.close() to stop accepting new connections while waiting for in-flight requests to finish, with a 10-second forced exit fallback src/vault-mcp/server.ts44-59

Sources: src/vault-mcp/server.ts22-147 src/vault-mcp/vault-operations/daily-notes.ts77-110 src/vault-mcp/config.ts82-181

MCP Transport and Routing

Vault Cortex uses the streamable-http transport pattern. Unlike standard stateless REST APIs, MCP sessions are stateful. The createMcpRouter manages a Map of active StreamableHTTPServerTransport instances keyed by sessionId src/vault-mcp/mcp-core/mcp-router.ts49

Session Lifecycle

1. Initialization: A client sends a POST to /mcp with an initialize request. If no mcp-session-id header is present, the router creates a new McpServer instance and a corresponding StreamableHTTPServerTransport src/vault-mcp/mcp-core/mcp-router.ts68-85
2. Registration: During session creation, the router calls registerTools and registerPrompts, passing a sessionLogger child that includes the sessionId and clientIp in every log entry src/vault-mcp/mcp-core/mcp-router.ts108-127
3. Routing: Subsequent POST requests containing a valid mcp-session-id are routed to the existing transport instance via transport.handleRequest() src/vault-mcp/mcp-core/mcp-router.ts56-65
4. Method Constraints: The server explicitly rejects GET /mcp with a 405 Method Not Allowed because it does not offer a standalone SSE stream, as Vault Cortex never sends server-initiated messages src/vault-mcp/mcp-core/mcp-router.ts177-191
5. Termination: Sessions are removed from the internal map when the transport triggers its onclose callback src/vault-mcp/mcp-core/mcp-router.ts74-81

Request Flow Diagram

This diagram bridges the network request space to the internal code entities that process them.

Sources: src/vault-mcp/mcp-core/mcp-router.ts41-217 src/vault-mcp/server.ts131-138 src/auth.ts17-19

Logger Chain and Context

The logging system in src/logger.ts is designed for high observability in multi-user environments. It uses a JSON-structured format and supports a "child logger" pattern to flow context through the execution stack.

Context Propagation

When a session is established in mcp-router.ts, a sessionLogger is created src/vault-mcp/mcp-core/mcp-router.ts108 This logger is passed into every tool and prompt registration. As a result, every log line generated during a tool's execution automatically includes:

• sessionId: The unique UUID for the MCP session. Because the ID is generated during initialization, the child logger uses a lazy function () => transport.sessionId to resolve the value at emit time src/logger.ts127-140 src/vault-mcp/mcp-core/mcp-router.ts111
• clientIp: The IP of the requester (resolved via app.set("trust proxy", 1) src/vault-mcp/server.ts118).
• source: The file and line number where the log was emitted, captured via V8 stack trace analysis src/logger.ts42-59

Log Sinks and Retention

Logs are emitted to stdout/stderr and optionally to a file sink if LOG_DIR is configured src/logger.ts116-125

• Rotation: The createFileSinkExtension rolls logs into date-stamped files (e.g., vault-mcp-2025-05-20.log) using Luxon for date formatting src/logger.ts90-104
• Pruning: The pruneOldLogFiles function deletes files older than LOG_RETENTION_DAYS (default 30) on startup and rotation src/logger.ts73-86

Logger Entity Association

Sources: src/logger.ts1-204 src/vault-mcp/mcp-core/mcp-router.ts108-127 src/vault-mcp/server.ts22-36 src/vault-mcp/mcp-core/prompts/vault-orientation-prompt.ts146-150