# n8n-mcp Multi-Tenant InstanceContext Configuration: Complete Implementation Guide

> Master n8n-mcp multi-tenant InstanceContext configuration. Learn how to serve isolated n8n instances, inject endpoints, credentials, and metadata for full control.

- Repository: [Romuald Członkowski/n8n-mcp](https://github.com/czlonkowski/n8n-mcp)
- Tags: deep-dive
- Published: 2026-03-24

---

**The n8n-mcp multi-tenant InstanceContext configuration allows a single MCP process to serve multiple isolated n8n instances by validating and injecting per-tenant API endpoints, credentials, and metadata into every tool handler.**

The `czlonkowski/n8n-mcp` repository implements a sophisticated multi-tenant architecture through the **InstanceContext** interface. This configuration system enables a single Model Context Protocol (MCP) server to manage independent n8n instances for different tenants while maintaining strict isolation of credentials and API endpoints. Understanding n8n-mcp multi-tenant InstanceContext configuration is essential for deploying scalable, multi-user workflow automation platforms.

## Core Components of Multi-Tenant InstanceContext Configuration

### The InstanceContext Interface Definition

Located in [`src/types/instance-context.ts`](https://github.com/czlonkowski/n8n-mcp/blob/main/src/types/instance-context.ts) (lines 9-16), the `InstanceContext` interface defines the contract for per-tenant configuration:

```typescript
interface InstanceContext {
  n8nApiUrl?: string;
  n8nApiKey?: string;
  n8nApiTimeout?: number;
  n8nApiMaxRetries?: number;
  instanceId?: string;
  sessionId?: string;
  metadata?: Record<string, any>;
}

```

### Runtime Validation and Type Guards

The system enforces data integrity through `isInstanceContext` (type guard) and `validateInstanceContext` (detailed error reporting) in [`src/types/instance-context.ts`](https://github.com/czlonkowski/n8n-mcp/blob/main/src/types/instance-context.ts) (lines 30-97 and 98-124). These functions validate URL formats and API key structure before the server accepts the configuration.

## Server Integration and Tenant Isolation

### Constructor Injection Pattern

The `N8NDocumentationMCPServer` class accepts an optional `InstanceContext` parameter in its constructor ([`src/mcp/server.ts`](https://github.com/czlonkowski/n8n-mcp/blob/main/src/mcp/server.ts), lines 61-63). The server stores this as `this.instanceContext` and propagates it to every n8n-related handler, overriding any environment-based defaults.

### Tool-Level Configuration Detection

Before processing requests, the server checks for tenant-specific configuration using:

```typescript
const hasInstanceConfig = !!(this.instanceContext?.n8nApiUrl && this.instanceContext?.n8nApiKey);

```

This validation in [`src/mcp/server.ts`](https://github.com/czlonkowski/n8n-mcp/blob/main/src/mcp/server.ts) (lines 608-610) determines whether to route API calls through the tenant's endpoint or fall back to global settings.

## HTTP Session Management for Multi-Tenancy

### Per-Session Context Storage

The HTTP single-session manager creates isolated environments for each tenant. When `createSession` receives an `instanceContext` from the client, it stores the context in `sessionContexts` and embeds it into the underlying `N8NDocumentationMCPServer` instance ([`src/http-server-single-session.ts`](https://github.com/czlonkowski/n8n-mcp/blob/main/src/http-server-single-session.ts), lines 359-371 and 546-562).

### Multi-Tenant Mode Strategy

The server supports two operation modes: **"shared"** and **"instance"**. When the strategy is set to `instance` and an `instanceContext.instanceId` is provided, the engine generates a unique session key formatted as `instance-<instanceId>-<hash>` ([`src/http-server-single-session.ts`](https://github.com/czlonkowski/n8n-mcp/blob/main/src/http-server-single-session.ts), lines 652-660). This ensures complete request isolation between tenants.

## Session Persistence and State Restoration

### Serializing Tenant Configuration

The [`session-state.ts`](https://github.com/czlonkowski/n8n-mcp/blob/main/session-state.ts) file ([`src/types/session-state.ts`](https://github.com/czlonkowski/n8n-mcp/blob/main/src/types/session-state.ts)) handles serialization of `InstanceContext` objects. This persistence layer enables tenant configurations to survive process restarts, maintaining session continuity across server redeployments.

## Implementation Examples

### Creating and Validating InstanceContext

```typescript
import { InstanceContext, validateInstanceContext } from '@/types/instance-context';

const tenantContext: InstanceContext = {
  n8nApiUrl: 'https://tenant-01.n8n.example.com',
  n8nApiKey: 's3cr3t-k3y-for-tenant-01',
  n8nApiTimeout: 15000,
  n8nApiMaxRetries: 3,
  instanceId: 'tenant-01',
  sessionId: 'session-a1b2c3',
  metadata: { region: 'eu-west' },
};

const { valid, errors } = validateInstanceContext(tenantContext);
if (!valid) {
  throw new Error(`Invalid InstanceContext: ${errors?.join('; ')}`);
}

```

### Starting Server with Tenant Context

```typescript
import { N8NDocumentationMCPServer } from '@/mcp/server';
import { EarlyErrorLogger } from '@/utils/logger';

const earlyLogger = new EarlyErrorLogger();
const server = new N8NDocumentationMCPServer(tenantContext, earlyLogger);

// Routes all n8n API calls through tenant-specific endpoint
await server.listen(4000);

```

### HTTP Single-Session API Usage

```typescript
import { N8NDocumentationMCPHttpServer } from '@/http-server-single-session';

const httpServer = new N8NDocumentationMCPHttpServer({
  // global configuration
});

httpServer.createSession({
  instanceContext: tenantContext, // injected per-session
});

```

### Accessing Context in Tool Handlers

```typescript
export async function handleGetWorkflow(args: any, ctx?: InstanceContext) {
  const apiUrl = ctx?.n8nApiUrl ?? process.env.N8N_API_URL;
  const apiKey = ctx?.n8nApiKey ?? process.env.N8N_API_KEY;

  return await fetch(`${apiUrl}/workflow/${args.id}`, {
    headers: { 'Authorization': `Bearer ${apiKey}` },
  });
}

```

## Summary

- The **InstanceContext** interface in [`src/types/instance-context.ts`](https://github.com/czlonkowski/n8n-mcp/blob/main/src/types/instance-context.ts) defines per-tenant configuration including API endpoints, credentials, and metadata.
- **Runtime validation** via `validateInstanceContext` ensures tenant data meets URL and key format requirements before processing.
- The `N8NDocumentationMCPServer` constructor accepts and stores tenant context in `this.instanceContext`, overriding environment variables.
- **HTTP session management** creates isolated tenant sessions using unique keys formatted as `instance-<instanceId>-<hash>`.
- **Session persistence** through [`session-state.ts`](https://github.com/czlonkowski/n8n-mcp/blob/main/session-state.ts) enables configuration restoration across process restarts.

## Frequently Asked Questions

### What fields are required in an n8n-mcp InstanceContext object?

While all fields are technically optional, a functional multi-tenant configuration requires `n8nApiUrl` and `n8nApiKey` for API authentication. The `instanceId` field is necessary for session isolation when using the HTTP single-session server. Additional fields like `n8nApiTimeout` and `metadata` provide extended customization but are not mandatory for basic operation.

### How does n8n-mcp validate InstanceContext configurations?

The system employs `isInstanceContext` as a runtime type guard and `validateInstanceContext` for detailed schema validation, both defined in [`src/types/instance-context.ts`](https://github.com/czlonkowski/n8n-mcp/blob/main/src/types/instance-context.ts). These functions check URL format validity, API key presence, and data type consistency, returning structured error messages if validation fails.

### Can multiple tenants share the same n8n-mcp process?

Yes. The architecture supports multiple isolated tenants through the "instance" strategy mode. Each tenant receives a dedicated session with unique configuration stored in `sessionContexts`. The server creates tenant-scoped session keys and routes API calls through tenant-specific endpoints, enabling secure multi-tenancy on a single binary.

### How is tenant configuration preserved across server restarts?

The [`src/types/session-state.ts`](https://github.com/czlonkowski/n8n-mcp/blob/main/src/types/session-state.ts) module serializes `InstanceContext` objects into persistent storage. When the server restarts, it re-hydrates these configurations, restoring tenant sessions with their original API endpoints, credentials, and metadata intact.