┌─────────────────────────────────────────────────────────────────┐
│                    MCP Architecture Overview                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   ┌──────────────┐         JSON-RPC 2.0          ┌──────────────┐│
│   │   MCP Client │  ◄──────────────────────────► │   MCP Server  ││
│   │  (ChatGPT,   │     (stdio, HTTP/SSE)        │  (Your APIs,  ││
│   │   Cursor,    │                               │  Database,   ││
│   │   n8n,       │                               │  Files, etc.)││
│   │   OpenClaw)  │                               │              ││
│   └──────────────┘                               └──────────────┘│
│          │                                               │       │
│          │           Capabilities Exchange               │       │
│          │  ───────────────────────────────────────────►   │       │
│          │  ◄───────────────────────────────────────────   │       │
│          │                                               │       │
│          │           Tool Calls / Resource Requests    │       │
│          │  ───────────────────────────────────────────►   │       │
│          │  ◄───────────────────────────────────────────   │       │
│          │                                               │       │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│              MCP Enterprise Authorization Flow                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  Step 1: Client Discovery                                         │
│  ─────────────────────                                           │
│  Client requests server capabilities                           │
│                                                                  │
│  GET /.well-known/mcp                                           │
│  Response includes:                                             │
│    - Available capabilities                                     │
│    - Authentication requirements                                │
│    - Authorization endpoints                                      │
│                                                                  │
│  Step 2: Authentication                                           │
│  ────────────────────                                           │
│  Client authenticates using configured method:                  │
│                                                                  │
│  Methods supported:                                             │
│    - OAuth 2.0 (Authorization Code + PKCE)                      │
│    - OAuth 2.0 (Client Credentials)                             │
│    - mTLS (Mutual TLS)                                          │
│    - JWT Bearer Tokens                                          │
│    - API Key (with rotation support)                            │
│                                                                  │
│  Step 3: Token Exchange                                           │
│  ────────────────────                                           │
│  Authenticated client receives MCP access token:                  │
│                                                                  │
│  {                                                              │
│    "access_token": "mcp_at_...",                                │
│    "token_type": "Bearer",                                      │
│    "expires_in": 3600,                                          │
│    "scope": "tools:read tools:execute resources:read",        │
│    "server_metadata": {                                         │
│      "instance_id": "srv_abc123",                             │
│      "region": "us-west-2",                                     │
│      "capabilities": [...]                                      │
│    }                                                            │
│  }                                                              │
│                                                                  │
│  Step 4: Authorized Requests                                      │
│  ────────────────────────                                       │
│  Client includes token in all requests:                         │
│                                                                  │
│  Authorization: Bearer mcp_at_...                               │
│  X-MCP-Client-Version: 2026-07-28                               │
│                                                                  │
│  Server validates token, checks scopes, processes request       │
│                                                                  │
│  Step 5: Token Refresh                                            │
│  ────────────────────                                           │
│  Tokens automatically refresh before expiry                     │
│  Refresh tokens enable long-lived sessions                      │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

tools:read          - List available tools
tools:execute       - Invoke tools
resources:read      - Access resources
resources:write     - Modify resources
prompts:read        - Access server prompts
sampling:request    - Request client-side sampling
admin:configure     - Server configuration (admin only)

// Client-side session state
const mcpSession = {
  // Server connection info (can be any instance)
  serverEndpoint: "https://mcp-api.company.com/v1",
  
  // Authentication
  accessToken: "mcp_at_...",
  tokenExpiry: 1719234567000,
  
  // Conversation context (client-managed)
  context: {
    conversationId: "conv_xyz789",
    toolResults: [...],      // Previous tool call results
    resourceCache: {...},    // Cached resource data
    preferences: {...}       // User preferences
  },
  
  // Capability cache
  serverCapabilities: {...}
};

// Each request includes context
const request = {
  jsonrpc: "2.0",
  id: 123,
  method: "tools/call",
  params: {
    name: "search_database",
    arguments: {...},
    // Session context passed with each request
    context: mcpSession.context
  }
};

// Good tool definition
{
  name: "search_customer_database",
  description: "Search for customers in the CRM database. Use this when the user asks about specific customers, accounts, or contact information. Returns customer records with name, email, phone, and account status.",
  inputSchema: {
    type: "object",
    properties: {
      query: {
        type: "string",
        description: "Search query string. Can be partial name, email, or phone number."
      },
      limit: {
        type: "integer",
        description: "Maximum number of results to return (1-100)",
        default: 10,
        minimum: 1,
        maximum: 100
      }
    },
    required: ["query"]
  }
}

// Basic usage - just the essentials
{
  name: "send_email",
  description: "Send an email to a recipient",
  inputSchema: {
    type: "object",
    properties: {
      to: { type: "string", format: "email" },
      subject: { type: "string" },
      body: { type: "string" }
    },
    required: ["to", "subject", "body"]
  }
}

// Advanced usage - additional options for sophisticated clients
{
  name: "send_email_advanced",
  description: "Send an email with advanced options including attachments, CC/BCC, scheduling, and tracking",
  inputSchema: {
    // Extended schema with all options
  }
}

interface ToolResponse<T> {
  // Success indicator
  success: boolean;
  
  // Result data (when successful)
  data?: T;
  
  // Error details (when failed)
  error?: {
    code: string;
    message: string;
    details?: unknown;
  };
  
  // Metadata
  meta: {
    executionTime: number;
    requestId: string;
    cached: boolean;
  };
}

# Standard resource URI patterns
database://table/records/{id}
file://documents/contracts/{filename}
api://service/endpoint/resource
config://settings/environment

// Resource definition
{
  uri: "database://customers/active",
  name: "Active Customers",
  description: "List of currently active customers",
  mimeType: "application/json",
  size: 15420,
  
  // Capabilities
  capabilities: {
    // Support for subscriptions (live updates)
    subscribe: true,
    
    // Pagination support
    pagination: {
      supported: true,
      defaultLimit: 100,
      maxLimit: 1000
    },
    
    // Search/filter support
    filtering: {
      supported: true,
      operators: ["eq", "neq", "gt", "lt", "contains", "startsWith"]
    },
    
    // Sorting support
    sorting: {
      supported: true,
      defaultField: "createdAt",
      defaultDirection: "desc"
    }
  }
}

// Client subscribes to resource updates
const subscription = await client.subscribeResource({
  uri: "database://orders/pending",
  
  // Optional: filter subscription
  filter: {
    region: "europe",
    priority: "high"
  },
  
  // Handler for updates
  onUpdate: (update) => {
    console.log(`New order: ${update.data.orderId}`);
  },
  
  onError: (error) => {
    console.error(`Subscription error: ${error.message}`);
  }
});

// Unsubscribe when done
await subscription.unsubscribe();

interface SamplingRequest {
  // Messages for the AI (similar to chat completions API)
  messages: Array<{
    role: "user" | "assistant" | "system";
    content: string;
  }>;
  
  // Model preferences
  modelPreferences?: {
    hints?: string[];           // Model hints (e.g., ["claude-3-opus", "gpt-4"])
    priority?: "speed" | "quality";  // Optimization preference
  };
  
  // Completion parameters
  maxTokens?: number;
  temperature?: number;
  
  // Metadata for client context
  metadata: {
    requestId: string;
    purpose: string;
    clientInfo: {
      name: string;
      version: string;
    };
  };
}

// Server requests sampling from client
async function processDocument(document: Document) {
  // Server does initial processing
  const extractedData = await extractData(document);
  
  // Request AI assistance for summary
  const samplingResult = await client.requestSampling({
    messages: [
      {
        role: "system",
        content: "You are a document analysis assistant. Summarize the key points."
      },
      {
        role: "user",
        content: `Document data: ${JSON.stringify(extractedData)}`
      }
    ],
    maxTokens: 500,
    metadata: {
      requestId: generateId(),
      purpose: "document_summary",
      clientInfo: { name: "mcp-server", version: "1.0.0" }
    }
  });
  
  // Combine server processing with AI summary
  return {
    data: extractedData,
    summary: samplingResult.content
  };
}

my-mcp-server/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # MCP server setup
│   ├── auth/
│   │   ├── oauth.ts          # OAuth implementation
│   │   ├── jwt.ts            # JWT validation
│   │   └── scopes.ts         # Scope checking
│   ├── tools/
│   │   ├── index.ts          # Tool registration
│   │   ├── customer-search.ts
│   │   ├── order-management.ts
│   │   └── email-sender.ts
│   ├── resources/
│   │   ├── index.ts          # Resource registration
│   │   ├── customer-data.ts
│   │   └── order-stream.ts
│   ├── handlers/
│   │   ├── tools.ts          # Tool request handlers
│   │   ├── resources.ts      # Resource request handlers
│   │   └── sampling.ts       # Sampling request handlers
│   └── utils/
│       ├── validation.ts
│       ├── errors.ts
│       └── logging.ts
├── tests/
│   ├── unit/
│   └── integration/
├── config/
│   ├── development.yaml
│   └── production.yaml
├── Dockerfile
├── package.json
└── tsconfig.json

// src/server.ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListResourcesRequestSchema,
  ListToolsRequestSchema,
  ReadResourceRequestSchema,
  ErrorCode,
  McpError
} from "@modelcontextprotocol/sdk/types.js";

import { authenticateRequest } from "./auth/jwt.js";
import { checkScope } from "./auth/scopes.js";
import { toolHandlers } from "./handlers/tools.js";
import { resourceHandlers } from "./handlers/resources.js";

class MCPServer {
  private server: Server;

  constructor() {
    this.server = new Server(
      {
        name: "enterprise-mcp-server",
        version: "1.0.0"
      },
      {
        capabilities: {
          tools: {},
          resources: {
            subscribe: true
          },
          sampling: {}
        }
      }
    );

    this.setupHandlers();
    this.setupErrorHandling();
  }

  private setupHandlers() {
    // List available tools
    this.server.setRequestHandler(ListToolsRequestSchema, async (request) => {
      // Authenticate and authorize
      const auth = await authenticateRequest(request);
      checkScope(auth, "tools:read");
      
      return {
        tools: [
          {
            name: "search_customers",
            description: "Search customer database",
            inputSchema: {
              type: "object",
              properties: {
                query: { type: "string" },
                limit: { type: "number", default: 10 }
              },
              required: ["query"]
            }
          },
          {
            name: "create_order",
            description: "Create a new order",
            inputSchema: {
              type: "object",
              properties: {
                customerId: { type: "string" },
                items: { type: "array" },
                shippingAddress: { type: "object" }
              },
              required: ["customerId", "items"]
            }
          }
        ]
      };
    });

    // Execute tool calls
    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
      const auth = await authenticateRequest(request);
      checkScope(auth, "tools:execute");
      
      const handler = toolHandlers[request.params.name];
      if (!handler) {
        throw new McpError(
          ErrorCode.MethodNotFound,
          `Tool not found: ${request.params.name}`
        );
      }
      
      return await handler(request.params.arguments, auth);
    });

    // List available resources
    this.server.setRequestHandler(ListResourcesRequestSchema, async (request) => {
      const auth = await authenticateRequest(request);
      checkScope(auth, "resources:read");
      
      return {
        resources: [
          {
            uri: "database://customers/active",
            name: "Active Customers",
            mimeType: "application/json"
          },
          {
            uri: "database://orders/pending",
            name: "Pending Orders",
            mimeType: "application/json"
          }
        ]
      };
    });

    // Read resource content
    this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
      const auth = await authenticateRequest(request);
      checkScope(auth, "resources:read");
      
      const handler = resourceHandlers[request.params.uri];
      if (!handler) {
        throw new McpError(
          ErrorCode.InvalidRequest,
          `Resource not found: ${request.params.uri}`
        );
      }
      
      return await handler(request.params.uri, auth);
    });
  }

  private setupErrorHandling() {
    this.server.onerror = (error) => {
      console.error("[MCP Error]", error);
    };

    process.on("SIGINT", async () => {
      await this.server.close();
      process.exit(0);
    });
  }

  async run() {
    const transport = new StdioServerTransport();
    await this.server.connect(transport);
    console.error("MCP server running on stdio");
  }
}

const server = new MCPServer();
server.run().catch(console.error);

// src/handlers/tools.ts
import { z } from "zod";

// Input validation schemas
const SearchCustomersSchema = z.object({
  query: z.string().min(1),
  limit: z.number().min(1).max(100).default(10)
});

const CreateOrderSchema = z.object({
  customerId: z.string(),
  items: z.array(z.object({
    sku: z.string(),
    quantity: z.number().min(1),
    price: z.number().positive()
  })).min(1),
  shippingAddress: z.object({
    street: z.string(),
    city: z.string(),
    country: z.string()
  }).optional()
});

// Tool implementations
export const toolHandlers: Record<string, Function> = {
  async search_customers(args: unknown, auth: AuthContext) {
    // Validate input
    const validated = SearchCustomersSchema.parse(args);
    
    // Check additional permissions
    if (!auth.permissions.includes("customer:read")) {
      throw new McpError(
        ErrorCode.InvalidRequest,
        "Insufficient permissions to search customers"
      );
    }
    
    // Execute search
    const customers = await db.customers.search({
      query: validated.query,
      limit: validated.limit,
      tenantId: auth.tenantId  // Multi-tenant isolation
    });
    
    // Return structured response
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            success: true,
            data: customers,
            meta: {
              count: customers.length,
              query: validated.query
            }
          }, null, 2)
        }
      ]
    };
  },

  async create_order(args: unknown, auth: AuthContext) {
    const validated = CreateOrderSchema.parse(args);
    
    // Verify customer belongs to tenant
    const customer = await db.customers.findById(validated.customerId);
    if (customer.tenantId !== auth.tenantId) {
      throw new McpError(
        ErrorCode.InvalidRequest,
        "Customer not found"
      );
    }
    
    // Create order with audit trail
    const order = await db.orders.create({
      ...validated,
      tenantId: auth.tenantId,
      createdBy: auth.userId,
      createdAt: new Date()
    });
    
    // Return success response
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({
            success: true,
            data: {
              orderId: order.id,
              status: "created",
              total: order.items.reduce((sum, item) => sum + item.price * item.quantity, 0)
            },
            meta: {
              executionTime: Date.now() - startTime
            }
          }, null, 2)
        }
      ]
    };
  }
};

# Dockerfile
FROM node:20-alpine

WORKDIR /app

# Install dependencies
COPY package*.json ./
RUN npm ci --only=production

# Copy source
COPY dist/ ./dist/

# Non-root user for security
USER node

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD node -e "console.log('healthcheck')" || exit 1

# Expose port for HTTP transport
EXPOSE 3000

# Run server
CMD ["node", "dist/index.js"]

# docker-compose.yml
version: "3.8"

services:
  mcp-server:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - JWT_SECRET=${JWT_SECRET}
      - DATABASE_URL=${DATABASE_URL}
      - REDIS_URL=${REDIS_URL}
    depends_on:
      - redis
      - db
    restart: unless-stopped
    deploy:
      replicas: 3
      resources:
        limits:
          cpus: '1'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    volumes:
      - redis-data:/data

  db:
    image: postgres:16-alpine
    environment:
      - POSTGRES_USER=mcp
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=mcp_data
    volumes:
      - postgres-data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  redis-data:
  postgres-data:

# MCP node is included in n8n 2.0+
# For self-hosted, ensure you're running:
npx n8n --version  # Should be 2.0.0 or higher

{
  "nodes": [
    {
      "parameters": {
        "operation": "listTools",
        "server": {
          "transport": "stdio",
          "command": "node",
          "args": ["/path/to/server.js"]
        }
      },
      "name": "MCP Server",
      "type": "n8n-nodes-base.mcp",
      "typeVersion": 1,
      "position": [250, 300]
    }
  ]
}

┌─────────────────────────────────────────────────────────────────┐
│         n8n Workflow: MCP-Powered Customer Support              │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌───────────────┐                                              │
│  │ Webhook       │  Customer message received                │
│  │ (Chat Input)  │                                             │
│  └───────┬───────┘                                              │
│          │                                                       │
│          ▼                                                       │
│  ┌───────────────┐     ┌─────────────────┐                    │
│  │ AI Agent      │────▶│ MCP Tool: Search  │                    │
│  │ (Claude/GPT)  │     │ Customer Database │                    │
│  │               │◄───│                   │                    │
│  └───────┬───────┘     └─────────────────┘                    │
│          │                                                       │
│          ▼                                                       │
│  ┌───────────────┐     ┌─────────────────┐                    │
│  │ AI Agent      │────▶│ MCP Tool: Check │                    │
│  │ (Analysis)    │     │ Order Status    │                    │
│  │               │◄───│                 │                    │
│  └───────┬───────┘     └─────────────────┘                    │
│          │                                                       │
│          ▼                                                       │
│  ┌───────────────┐     ┌─────────────────┐                    │
│  │ AI Agent      │────▶│ MCP Tool: Create  │                    │
│  │ (Response)    │     │ Support Ticket  │                    │
│  │               │◄───│ (if needed)     │                    │
│  └───────┬───────┘     └─────────────────┘                    │
│          │                                                       │
│          ▼                                                       │
│  ┌───────────────┐                                              │
│  │ Send Response │  Return to customer                         │
│  │ (Discord/     │                                             │
│  │  Slack/Email) │                                             │
│  └───────────────┘                                              │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

// Node: MCP Tool - Search Customer Database
{
  "parameters": {
    "operation": "callTool",
    "tool": "search_customers",
    "arguments": {
      "query": "={{ $json.customerQuery }}",
      "limit": 5
    },
    "server": {
      "transport": "http",
      "url": "https://mcp-api.company.com",
      "auth": {
        "type": "oauth2",
        "oauth2": {
          "grantType": "clientCredentials",
          "clientId": "={{ $env.MCP_CLIENT_ID }}",
          "clientSecret": "={{ $env.MCP_CLIENT_SECRET }}",
          "tokenEndpoint": "https://auth.company.com/oauth/token"
        }
      }
    }
  }
}

// Node: MCP Tool - Create Support Ticket
{
  "parameters": {
    "operation": "callTool",
    "tool": "create_ticket",
    "arguments": {
      "customerId": "={{ $json.customerId }}",
      "subject": "={{ $json.issueSubject }}",
      "description": "={{ $json.issueDescription }}",
      "priority": "={{ $json.priority || 'normal' }}"
    },
    "server": {
      "transport": "stdio",
      "command": "node",
      "args": ["/app/mcp/servers/zendesk-server.js"]
    }
  }
}

// Function node to determine which tools to call
const intent = $json.intent;
const entities = $json.entities;

const toolCalls = [];

if (intent === "order_inquiry") {
  toolCalls.push({
    tool: "get_order_status",
    args: { orderId: entities.orderId }
  });
}

if (intent === "refund_request") {
  toolCalls.push(
    { tool: "get_order_status", args: { orderId: entities.orderId } },
    { tool: "check_refund_eligibility", args: { orderId: entities.orderId } }
  );
}

if (intent === "product_question") {
  toolCalls.push({
    tool: "search_products",
    args: { query: entities.productName }
  });
}

return toolCalls.map(call => ({
  json: call
}));

// Split node for parallel execution
const requests = $json.toolCalls;

return requests.map((req, index) => ({
  json: {
    ...req,
    _parallelIndex: index
  },
  pairedItem: { item: 0 }
}));

// Then use MCP nodes in parallel branches
// Aggregate results with Merge node

// Error handling sub-workflow
async function handleMCPError(error, context) {
  const errorCode = error.code;
  
  switch(errorCode) {
    case "RATE_LIMIT":
      // Exponential backoff
      const delay = Math.pow(2, context.retryCount) * 1000;
      await sleep(delay);
      return { action: "retry", delay };
      
    case "AUTH_EXPIRED":
      // Refresh token and retry
      await refreshAccessToken();
      return { action: "retry", delay: 0 };
      
    case "TOOL_NOT_FOUND":
      // Fall back to alternative tool
      return { 
        action: "fallback", 
        alternativeTool: findAlternativeTool(context.tool) 
      };
      
    case "VALIDATION_ERROR":
      // Fix input and retry
      const fixedArgs = await fixInputWithAI(error, context.args);
      return { action: "retry", fixedArgs };
      
    default:
      return { action: "escalate", error };
  }
}

// Before fetching resource, check cache
const cacheKey = `mcp-resource-${resourceUri}`;
const cached = await $getWorkflowStaticData("global").get(cacheKey);

if (cached && Date.now() - cached.timestamp < 300000) { // 5 min cache
  return { json: cached.data };
}

// Fetch from MCP server
const resource = await fetchMCPResource(resourceUri);

// Store in cache
await $getWorkflowStaticData("global").set(cacheKey, {
  data: resource,
  timestamp: Date.now()
});

return { json: resource };

// Credentials configuration
{
  "name": "MCP Enterprise Server",
  "type": "mcpOAuth2Api",
  "data": {
    "grantType": "clientCredentials",
    "clientId": "mcp-client-123",
    "clientSecret": "...",
    "tokenEndpoint": "https://auth.company.com/oauth/token",
    "scope": "tools:execute resources:read"
  }
}

# docker-compose.n8n.yml
version: "3.8"

services:
  n8n:
    image: n8nio/n8n:2.0
    restart: always
    ports:
      - "5678:5678"
    environment:
      - N8N_BASIC_AUTH_ACTIVE=true
      - N8N_BASIC_AUTH_USER=${N8N_USER}
      - N8N_BASIC_AUTH_PASSWORD=${N8N_PASSWORD}
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
      - WEBHOOK_URL=https://n8n.company.com/
      - MCP_CLIENT_ID=${MCP_CLIENT_ID}
      - MCP_CLIENT_SECRET=${MCP_CLIENT_SECRET}
      - MCP_SERVER_URL=${MCP_SERVER_URL}
    volumes:
      - ~/.n8n:/home/node/.n8n
      - /app/mcp/servers:/app/mcp/servers:ro
    networks:
      - n8n-network

networks:
  n8n-network:
    external: true

┌─────────────────────────────────────────────────────────────────┐
│              OpenClaw MCP Integration Architecture              │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   ┌──────────────────────────────────────────────────────┐     │
│   │                    OpenClaw Core                      │     │
│   │  ┌──────────────┐  ┌──────────────┐  ┌───────────┐ │     │
│   │  │   Session    │  │ Skill Engine │  │  Memory   │ │     │
│   │  │   Manager    │  │              │  │   Store   │ │     │
│   │  └──────┬───────┘  └───────┬──────┘  └─────┬─────┘ │     │
│   └─────────┼────────────────┼───────────────┼────────┘     │
│             │                │               │                 │
│             └────────────────┴───────────────┘                 │
│                          │                                      │
│   ┌──────────────────────▼────────────────────────┐             │
│   │              MCP Integration Layer           │             │
│   │  ┌────────────┐ ┌────────────┐ ┌───────────┐  │             │
│   │  │   Client   │ │ Discovery  │ │  Auth     │  │             │
│   │  │   Pool     │ │  Service   │ │ Manager   │  │             │
│   │  └─────┬──────┘ └─────┬──────┘ └─────┬─────┘  │             │
│   └────────┼──────────────┼──────────────┼────────┘             │
│            │              │              │                      │
│   ┌────────▼──────────────▼──────────────▼────────┐             │
│   │              External MCP Servers             │             │
│   │  ┌────────┐ ┌────────┐ ┌────────┐ ┌───────┐ │             │
│   │  │Database│ │ Zendesk│ │ Slack  │ │Custom │ │             │
│   │  │ Server │ │ Server │ │ Server │ │Server │ │             │
│   │  └────────┘ └────────┘ └────────┘ └───────┘ │             │
│   └───────────────────────────────────────────────┘             │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

# config/mcp-servers.yaml
mcp:
  servers:
    # Enterprise Database Server
    - name: company-db
      transport: http
      url: https://mcp-db.company.com
      auth:
        type: oauth2
        clientId: ${MCP_DB_CLIENT_ID}
        clientSecret: ${MCP_DB_CLIENT_SECRET}
        tokenEndpoint: https://auth.company.com/oauth/token
        scopes:
          - tools:execute
          - resources:read
      # Connection pool settings
      pool:
        minConnections: 2
        maxConnections: 10
        maxRequestsPerConnection: 100
      # Health check
      healthCheck:
        interval: 30s
        timeout: 5s
        path: /health

    # Zendesk Integration
    - name: zendesk-mcp
      transport: stdio
      command: node
      args:
        - /app/mcp/servers/zendesk-server.js
        - --config
        - /app/config/zendesk.json
      env:
        ZENDESK_SUBDOMAIN: ${ZENDESK_SUBDOMAIN}
        ZENDESK_API_TOKEN: ${ZENDESK_API_TOKEN}

    # Slack Integration
    - name: slack-mcp
      transport: http
      url: http://slack-mcp:3000
      auth:
        type: apiKey
        header: X-API-Key
        key: ${SLACK_MCP_API_KEY}

  # Global MCP settings
  settings:
    # Default timeout for tool calls
    defaultTimeout: 30s
    # Maximum concurrent tool calls
    maxConcurrentCalls: 50
    # Retry configuration
    retry:
      maxRetries: 3
      backoffType: exponential
      initialDelay: 1s
      maxDelay: 30s
    # Circuit breaker
    circuitBreaker:
      failureThreshold: 5
      recoveryTimeout: 60s

// skills/customer-support/SKILL.md
# Customer Support Skill

## Description
Handle customer inquiries using integrated MCP servers for database access, ticket management, and notifications.

## MCP Servers Used
- company-db (search_customers, get_order_status)
- zendesk-mcp (create_ticket, update_ticket)
- slack-mcp (send_notification)

## Configuration
```yaml
mcp:
  tools:
    search_customers:
      server: company-db
      requiredScopes: ["tools:execute"]
    create_ticket:
      server: zendesk-mcp
      requiredScopes: ["tools:execute"]
    send_notification:
      server: slack-mcp

async function execute(message, context) {
  // Step 1: Understand the customer's need
  const intent = await analyzeIntent(message.content);
  
  // Step 2: Gather information from MCP servers
  let customerData = null;
  let orderData = null;
  
  if (intent.customerIdentifier) {
    // Call MCP tool to search customers
    customerData = await context.mcp.callTool("company-db", "search_customers", {
      query: intent.customerIdentifier,
      limit: 1
    });
    
    if (customerData.success && customerData.data.length > 0) {
      customerData = customerData.data[0];
      
      // Get recent orders
      if (intent.orderRelated) {
        orderData = await context.mcp.callTool("company-db", "get_recent_orders", {
          customerId: customerData.id,
          limit: 5
        });
      }
    }
  }
  
  // Step 3: Generate response with context
  const response = await context.llm.generate({
    messages: [
      {
        role: "system",
        content: `You are a helpful customer support agent. Use the customer data to personalize your response.`
      },
      {
        role: "user",
        content: message.content
      }
    ],
    context: {
      customer: customerData,
      orders: orderData?.data || []
    }
  });
  
  // Step 4: Handle follow-up actions
  if (intent.requiresTicket) {
    const ticket = await context.mcp.callTool("zendesk-mcp", "create_ticket", {
      customerId: customerData?.id,
      subject: intent.ticketSubject,
      description: response.content,
      priority: intent.priority || "normal"
    });
    
    // Notify support team
    await context.mcp.callTool("slack-mcp", "send_notification", {
      channel: "#support-alerts",
      message: `New ticket created: ${ticket.data.ticketId} - ${intent.ticketSubject}`
    });
    
    return {
      content: response.content,
      actions: [
        { type: "ticket_created", ticketId: ticket.data.ticketId }
      ]
    };
  }
  
  return { content: response.content };
}

// Subscribe to real-time resource updates
async function setupResourceSubscriptions(context) {
  // Subscribe to order updates
  const orderSubscription = await context.mcp.subscribeResource(
    "company-db",
    "database://orders/pending",
    {
      onUpdate: (update) => {
        // Handle real-time order updates
        context.memory.set(`order:${update.data.orderId}`, update.data);
        
        // Trigger notifications for high-priority orders
        if (update.data.priority === "high") {
          context.emit("high_priority_order", update.data);
        }
      },
      onError: (error) => {
        context.logger.error("Resource subscription error:", error);
      }
    }
  );
  
  // Store subscription for cleanup
  context.subscriptions = context.subscriptions || [];
  context.subscriptions.push(orderSubscription);
}

// Cleanup on session end
async function cleanup(context) {
  if (context.subscriptions) {
    for (const sub of context.subscriptions) {
      await sub.unsubscribe();
    }
  }
}

// OpenClaw automatically pools MCP connections
// Configure in config/mcp-servers.yaml
pool:
  minConnections: 2      # Always maintain warm connections
  maxConnections: 10   # Scale up under load
  maxRequestsPerConnection: 100  # Rotate before limits

// Automatic circuit breaking for failing MCP servers
const result = await context.mcp.callTool("company-db", "search_customers", args, {
  // Circuit breaker automatically opens if server fails repeatedly
  circuitBreaker: {
    enabled: true,
    failureThreshold: 5,
    recoveryTimeout: 60000
  },
  // Fallback when circuit is open
  fallback: async () => {
    return { success: false, error: "Service temporarily unavailable" };
  }
});

// All MCP calls are automatically traced
const result = await context.mcp.callTool("company-db", "search_customers", args, {
  // Trace ID flows through entire call chain
  traceId: context.traceId,
  // Track latency
  onStart: () => context.metrics.startTimer("mcp_call"),
  onComplete: (duration) => context.metrics.record("mcp_call", duration)
});

# With your identity provider (Auth0, Okta, Keycloak, etc.)
# Create a new OAuth 2.0 application
curl -X POST https://auth.company.com/api/v2/clients \
  -H "Authorization: Bearer ${MANAGEMENT_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MCP Enterprise Server",
    "app_type": "non_interactive",
    "grant_types": ["client_credentials"],
    "allowed_scopes": [
      "tools:read",
      "tools:execute",
      "resources:read",
      "resources:write",
      "prompts:read"
    ]
  }'

// src/auth/oauth.ts
import { Issuer, Client } from "openid-client";

let oauthClient: Client;

export async function initializeOAuth() {
  const issuer = await Issuer.discover(
    process.env.OAUTH_ISSUER_URL!
  );
  
  oauthClient = new issuer.Client({
    client_id: process.env.OAUTH_CLIENT_ID!,
    client_secret: process.env.OAUTH_CLIENT_SECRET!,
    token_endpoint_auth_method: "client_secret_post"
  });
}

export async function validateToken(token: string): Promise<AuthContext> {
  try {
    // Introspect token with OAuth provider
    const introspection = await oauthClient.introspect(token);
    
    if (!introspection.active) {
      throw new Error("Token is not active");
    }
    
    // Extract scopes and claims
    const scopes = (introspection.scope as string).split(" ");
    
    return {
      userId: introspection.sub as string,
      tenantId: introspection.tenant_id as string,
      scopes,
      permissions: introspection.permissions as string[],
      expiresAt: introspection.exp as number
    };
  } catch (error) {
    throw new McpError(
      ErrorCode.InvalidRequest,
      "Invalid or expired token"
    );
  }
}

// src/auth/scopes.ts
export function checkScope(auth: AuthContext, requiredScope: string): void {
  if (!auth.scopes.includes(requiredScope)) {
    throw new McpError(
      ErrorCode.InvalidRequest,
      `Insufficient scope. Required: ${requiredScope}`,
      { required: requiredScope, granted: auth.scopes }
    );
  }
}

export function checkAnyScope(auth: AuthContext, requiredScopes: string[]): void {
  const hasAny = requiredScopes.some(s => auth.scopes.includes(s));
  if (!hasAny) {
    throw new McpError(
      ErrorCode.InvalidRequest,
      `Insufficient scope. Requires one of: ${requiredScopes.join(", ")}`
    );
  }
}

// Middleware for route-level scope checking
export function requireScope(scope: string) {
  return async (request: any, next: Function) => {
    const auth = await authenticateRequest(request);
    checkScope(auth, scope);
    return next();
  };
}

// Client-side token management
class MCPTokenManager {
  private tokens: Map<string, TokenInfo> = new Map();
  
  async getValidToken(serverName: string): Promise<string> {
    const token = this.tokens.get(serverName);
    
    // Check if token exists and is not expired
    if (token && Date.now() < token.expiresAt - 60000) { // 1 min buffer
      return token.accessToken;
    }
    
    // Token expired or doesn't exist - refresh
    return this.refreshToken(serverName);
  }
  
  private async refreshToken(serverName: string): Promise<string> {
    const server = this.getServerConfig(serverName);
    
    const response = await fetch(server.auth.tokenEndpoint, {
      method: "POST",
      headers: {
        "Content-Type": "application/x-www-form-urlencoded"
      },
      body: new URLSearchParams({
        grant_type: "client_credentials",
        client_id: server.auth.clientId,
        client_secret: server.auth.clientSecret,
        scope: server.auth.scopes.join(" ")
      })
    });
    
    if (!response.ok) {
      throw new Error(`Token refresh failed: ${response.statusText}`);
    }
    
    const data = await response.json();
    
    this.tokens.set(serverName, {
      accessToken: data.access_token,
      expiresAt: Date.now() + (data.expires_in * 1000),
      scope: data.scope
    });
    
    return data.access_token;
  }
}

// Server-side mTLS configuration
import https from "https";
import fs from "fs";

const server = https.createServer({
  key: fs.readFileSync("server-key.pem"),
  cert: fs.readFileSync("server-cert.pem"),
  ca: fs.readFileSync("ca-cert.pem"),  // Client CA
  requestCert: true,
  rejectUnauthorized: true
}, (req, res) => {
  // Client certificate is available in req.socket.getPeerCertificate()
  const cert = (req.socket as any).getPeerCertificate();
  
  // Extract identity from certificate
  const clientId = cert.subject.CN;
  const tenantId = cert.subject.OU;
  
  // Continue with authenticated request
  handleRequest(req, res, { clientId, tenantId });
});

// Client-side mTLS configuration
import { Client } from "@modelcontextprotocol/sdk/client/index.js";

const client = new Client(
  { name: "mcp-client", version: "1.0.0" },
  {
    capabilities: { tools: {} }
  }
);

// Configure mTLS transport
const transport = new HttpSseTransport({
  url: "https://mcp-server.company.com",
  tls: {
    key: fs.readFileSync("client-key.pem"),
    cert: fs.readFileSync("client-cert.pem"),
    ca: fs.readFileSync("ca-cert.pem")
  }
});

await client.connect(transport);

// src/auth/jwt.ts
import jwt from "jsonwebtoken";
import { JwksClient } from "jwks-rsa";

const jwksClient = new JwksClient({
  jwksUri: `${process.env.OAUTH_ISSUER_URL}/.well-known/jwks.json`,
  cache: true,
  cacheMaxEntries: 5,
  cacheMaxAge: 86400000 // 24 hours
});

export async function validateJWT(token: string): Promise<AuthContext> {
  // Get signing key
  const getKey = (header: any, callback: any) => {
    jwksClient.getSigningKey(header.kid, (err, key) => {
      if (err) return callback(err);
      callback(null, key.getPublicKey());
    });
  };
  
  // Verify token
  const decoded = await new Promise<jwt.JwtPayload>((resolve, reject) => {
    jwt.verify(token, getKey, {
      algorithms: ["RS256"],
      issuer: process.env.OAUTH_ISSUER_URL,
      audience: process.env.OAUTH_AUDIENCE
    }, (err, decoded) => {
      if (err) reject(err);
      else resolve(decoded as jwt.JwtPayload);
    });
  });
  
  return {
    userId: decoded.sub!,
    tenantId: decoded.tenant_id as string,
    scopes: (decoded.scope as string).split(" "),
    permissions: decoded.permissions as string[],
    expiresAt: decoded.exp!
  };
}

# Kubernetes NetworkPolicy for MCP servers
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: mcp-server-network-policy
spec:
  podSelector:
    matchLabels:
      app: mcp-server
  policyTypes:
    - Ingress
    - Egress
  ingress:
    - from:
        - namespaceSelector:
            matchLabels:
              name: n8n
        - namespaceSelector:
            matchLabels:
              name: openclaw
      ports:
        - protocol: TCP
          port: 3000
  egress:
    - to:
        - namespaceSelector:
            matchLabels:
              name: database
      ports:
        - protocol: TCP
          port: 5432
    - to:
        - namespaceSelector:
            matchLabels:
              name: redis
      ports:
        - protocol: TCP
          port: 6379

// Strict input validation for all tool calls
import { z } from "zod";

const strictValidator = z.object({
  // Sanitize strings to prevent injection
  query: z.string()
    .min(1)
    .max(1000)
    .transform(s => s.replace(/[<>]/g, '')), // Remove HTML tags
  
  // Validate numeric ranges
  limit: z.number()
    .int()
    .min(1)
    .max(100)
    .default(10),
  
  // Validate UUID formats
  customerId: z.string()
    .uuid()
    .optional()
});

// Additional SQL injection prevention
function sanitizeSQLInput(input: string): string {
  // Use parameterized queries instead of string concatenation
  // This is a secondary defense layer
  return input.replace(/['";\\]/g, '');
}

// Rate limiting middleware
import { RateLimiterRedis } from "rate-limiter-flexible";

const rateLimiter = new RateLimiterRedis({
  storeClient: redisClient,
  keyPrefix: "mcp_ratelimit",
  points: 100,          // Requests
  duration: 60,       // Per minute
  blockDuration: 300   // Block for 5 minutes if exceeded
});

export async function rateLimitMiddleware(
  request: any,
  next: Function
) {
  const clientId = request.auth?.clientId || request.ip;
  
  try {
    await rateLimiter.consume(clientId);
    return next();
  } catch (rejRes) {
    throw new McpError(
      ErrorCode.InvalidRequest,
      "Rate limit exceeded. Please retry after 60 seconds.",
      { retryAfter: rejRes.msBeforeNext / 1000 }
    );
  }
}

// Comprehensive audit logging
interface AuditLog {
  timestamp: string;
  eventType: "tool_call" | "resource_access" | "auth_success" | "auth_failure";
  requestId: string;
  clientId: string;
  tenantId: string;
  method: string;
  resource?: string;
  tool?: string;
  arguments?: any;
  success: boolean;
  errorCode?: string;
  ipAddress: string;
  userAgent: string;
  duration: number;
}

async function logAudit(event: AuditLog) {
  // Log to secure audit system
  await auditLogger.info({
    ...event,
    // Hash sensitive data
    arguments: event.arguments ? 
      hashSensitiveFields(event.arguments) : undefined
  });
  
  // Send to SIEM if configured
  if (process.env.SIEM_ENDPOINT) {
    await sendToSIEM(event);
  }
}

// Use dedicated secret management
import { SecretManagerServiceClient } from "@google-cloud/secret-manager";
import { SecretsManagerClient } from "@aws-sdk/client-secrets-manager";

class SecretProvider {
  async getSecret(secretName: string): Promise<string> {
    // Never hardcode secrets
    // Use environment-specific secret stores
    
    if (process.env.CLOUD_PROVIDER === "gcp") {
      const client = new SecretManagerServiceClient();
      const [version] = await client.accessSecretVersion({
        name: `projects/${projectId}/secrets/${secretName}/versions/latest`
      });
      return version.payload!.data!.toString();
    }
    
    if (process.env.CLOUD_PROVIDER === "aws") {
      const client = new SecretsManagerClient();
      const response = await client.getSecretValue({ SecretId: secretName });
      return response.SecretString!;
    }
    
    // Fallback to environment variables for local dev
    return process.env[secretName]!;
  }
}

// Encrypt sensitive data before storage
import crypto from "crypto";

const algorithm = "aes-256-gcm";

export function encryptData(data: string, key: Buffer): EncryptedData {
  const iv = crypto.randomBytes(16);
  const cipher = crypto.createCipheriv(algorithm, key, iv);
  
  let encrypted = cipher.update(data, "utf8", "hex");
  encrypted += cipher.final("hex");
  
  const authTag = cipher.getAuthTag();
  
  return {
    encrypted,
    iv: iv.toString("hex"),
    authTag: authTag.toString("hex")
  };
}

export function decryptData(encrypted: EncryptedData, key: Buffer): string {
  const decipher = crypto.createDecipheriv(
    algorithm,
    key,
    Buffer.from(encrypted.iv, "hex")
  );
  
  decipher.setAuthTag(Buffer.from(encrypted.authTag, "hex"));
  
  let decrypted = decipher.update(encrypted.encrypted, "hex", "utf8");
  decrypted += decipher.final("utf8");
  
  return decrypted;
}

// Enforce TLS 1.3
const tlsOptions = {
  minVersion: "TLSv1.3",
  maxVersion: "TLSv1.3",
  // Strong cipher suites only
  cipherSuites: "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256"
};

// Certificate pinning for high-security scenarios
const trustedFingerprints = [
  "AA:BB:CC:DD:EE:FF:...", // Server cert fingerprint
];

export function verifyCertificateFingerprint(cert: any): boolean {
  const fingerprint = crypto
    .createHash("sha256")
    .update(cert.raw)
    .digest("hex")
    .toUpperCase()
    .match(/.{2}/g)!
    .join(":");
  
  return trustedFingerprints.includes(fingerprint);
}

// Mask sensitive data in logs
export function maskSensitiveData(data: any): any {
  if (typeof data === "string") {
    // Mask credit cards
    data = data.replace(/\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}/g, "****-****-****-****");
    // Mask SSNs
    data = data.replace(/\d{3}-?\d{2}-?\d{4}/g, "***-**-****");
    // Mask emails
    data = data.replace(/(\w{2})[\w.-]+@(\w+)/g, "$1***@$2");
  }
  
  if (typeof data === "object" && data !== null) {
    const masked: any = {};
    for (const [key, value] of Object.entries(data)) {
      // Mask known sensitive fields
      if (["password", "token", "secret", "apiKey", "creditCard"].includes(key)) {
        masked[key] = "***REDACTED***";
      } else {
        masked[key] = maskSensitiveData(value);
      }
    }
    return masked;
  }
  
  return data;
}