Core Types InstanceContext Configuration context for individual n8n instances in multi-tenant deployments.
interface InstanceContext { n8nApiUrl ?: string ; n8nApiKey ?: string ; n8nApiTimeout ?: number ; n8nApiMaxRetries ?: number ; instanceId ?: string ; sessionId ?: string ; metadata ?: Record < string , any >; }
n8n instance API URL (e.g., https://n8n.example.com). When provided, overrides the N8N_API_URL environment variable.
n8n instance API key. When provided, overrides the N8N_API_KEY environment variable.
Request timeout in milliseconds. Defaults to environment variable or 30000ms.
Maximum retry attempts for failed requests. Defaults to 3.
Custom identifier for the n8n instance. Used for logging and session management.
Session-specific identifier. May differ from MCP session ID in proxy configurations.
Extensible metadata field for custom application data. Can store user IDs, tenant info, etc.
Basic Usage
With Metadata
Timeout & Retries
import { InstanceContext } from 'n8n-mcp' ; const context : InstanceContext = { n8nApiUrl: 'https://n8n.example.com' , n8nApiKey: 'n8n_api_xxxxx' , instanceId: 'tenant-123' };
SessionState Serializable session state for persistence across container restarts.
interface SessionState { sessionId : string ; metadata : { createdAt : string ; lastAccess : string ; }; context : { n8nApiUrl : string ; n8nApiKey : string ; instanceId ?: string ; sessionId ?: string ; metadata ?: Record < string , any >; }; }
Unique session identifier (UUID v4 or custom format)
Session timing information ISO 8601 timestamp when session was created
ISO 8601 timestamp of last session activity
n8n instance configuration n8n instance API key (plaintext - encrypt before storage!)
Security : SessionState contains plaintext API keys. Always encrypt before persisting to disk. See Session Management for best practices.Export Example
Type Guards
const sessions : SessionState [] = engine . exportSessionState (); // Example output [ { sessionId: "550e8400-e29b-41d4-a716-446655440000" , metadata: { createdAt: "2024-01-15T10:30:00.000Z" , lastAccess: "2024-01-15T10:45:00.000Z" }, context: { n8nApiUrl: "https://tenant1.n8n.cloud" , n8nApiKey: "n8n_api_tenant1_xxxxx" , instanceId: "tenant-123" , metadata: { userId: "user-456" } } } ]
Engine Types EngineOptions Configuration options for N8NMCPEngine.
interface EngineOptions { sessionTimeout ?: number ; logLevel ?: 'error' | 'warn' | 'info' | 'debug' ; }
Session timeout in minutes. Inactive sessions are expired after this period.
logLevel
'error' | 'warn' | 'info' | 'debug'
default: "info"
Logging verbosity level
EngineHealth Health status returned by healthCheck().
interface EngineHealth { status : 'healthy' | 'unhealthy' ; uptime : number ; sessionActive : boolean ; memoryUsage : { used : number ; total : number ; unit : string ; }; version : string ; }
Whether any sessions are active
Memory usage statistics in MB
Validation Functions validateInstanceContext() Validate and sanitize an InstanceContext object.
function validateInstanceContext ( context : InstanceContext ) : { valid : boolean ; errors ?: string []; }
Context object to validate
Returns an object with:
valid: true if context is valid, false otherwiseerrors: Array of validation error messages (if invalid)
Valid Context
Invalid Context
Middleware Example
import { validateInstanceContext } from 'n8n-mcp' ; const context = { n8nApiUrl: 'https://n8n.example.com' , n8nApiKey: 'valid_api_key_here' , instanceId: 'tenant-123' }; const result = validateInstanceContext ( context ); console . log ( result ); // { valid: true }
isInstanceContext() Type guard to check if an object is a valid InstanceContext.
function isInstanceContext ( obj : any ) : obj is InstanceContext
Type Guard Usage
Runtime Validation
import { isInstanceContext } from 'n8n-mcp' ; function processContext ( obj : unknown ) { if ( isInstanceContext ( obj )) { // TypeScript knows obj is InstanceContext here console . log ( `Instance: ${ obj . instanceId } ` ); console . log ( `URL: ${ obj . n8nApiUrl } ` ); } else { throw new Error ( 'Invalid context object' ); } }
MCP SDK Re-exports For convenience, n8n-mcp re-exports commonly used types from the MCP SDK:
import { Tool , CallToolResult , ListToolsResult } from 'n8n-mcp' ;
These are equivalent to importing from @modelcontextprotocol/sdk/types.js.
Utility Classes ConsoleManager Utility for managing console output during HTTP request handling.
import { ConsoleManager } from 'n8n-mcp' ; const consoleManager = new ConsoleManager (); // Silence console during operation await consoleManager . wrapOperation ( async () => { // Console output is suppressed here console . log ( 'This will not appear' ); });
ConsoleManager is primarily used internally by the HTTP server to prevent console output from interfering with MCP protocol streams. Most library users won’t need to use it directly.
UI Types Types for n8n-MCP UI app configurations:
import { UIAppConfig , UIMetadata , UI_APP_CONFIGS } from 'n8n-mcp' ;
Configuration for UI apps like Flowise and Dify
Metadata about UI app configurations
UI_APP_CONFIGS
Record<string, UIAppConfig>
Registry of pre-configured UI app settings