┌─────────────────────────────────────────────────────────────────┐
│                    MCP Architecture                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────┐          ┌──────────────────┐               │
│  │  AI Agent    │◄────────►│   MCP Client     │               │
│  │  (n8n,       │          │   (Transport     │               │
│  │   OpenClaw,  │          │    Layer)        │               │
│  │   Claude)    │          │                  │               │
│  └──────────────┘          └────────┬─────────┘               │
│                                     │                          │
│                                     │ Stdio / HTTP / SSE       │
│                                     │                          │
│                            ┌────────▼─────────┐               │
│                            │   MCP Server     │               │
│                            │   (Tool Host)    │               │
│                            │                  │               │
│                            │  ┌────────────┐  │               │
│                            │  │  Tools     │  │               │
│                            │  │  Resources │  │               │
│                            │  │  Prompts   │  │               │
│                            │  └────────────┘  │               │
│                            └──────────────────┘               │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

# For n8n custom nodes development
npm install @modelcontextprotocol/sdk

# For use in Function nodes (via npm in n8n settings)
npm install @modelcontextprotocol/sdk axios

// MCP Client Configuration Node
const { Client } = require('@modelcontextprotocol/sdk/client/index.js');
const { StdioClientTransport } = require('@modelcontextprotocol/sdk/client/stdio.js');
const { HttpClientTransport } = require('@modelcontextprotocol/sdk/client/http.js');

class N8nMCPClient {
  constructor(config) {
    this.config = config;
    this.clients = new Map();
  }

  async connectToServer(serverConfig) {
    const { name, transport, connection } = serverConfig;
    
    let transportInstance;
    
    if (transport === 'stdio') {
      transportInstance = new StdioClientTransport({
        command: connection.command,
        args: connection.args,
        env: connection.env || {}
      });
    } else if (transport === 'http') {
      transportInstance = new HttpClientTransport({
        url: connection.url,
        headers: connection.headers || {}
      });
    }

    const client = new Client({
      name: `n8n-client-${name}`,
      version: '1.0.0'
    });

    await client.connect(transportInstance);
    
    // Discover available tools
    const tools = await client.listTools();
    const resources = await client.listResources();
    
    this.clients.set(name, {
      client,
      transport: transportInstance,
      tools: tools.tools,
      resources: resources.resources
    });

    return {
      connected: true,
      server: name,
      toolCount: tools.tools.length,
      resourceCount: resources.resources.length,
      tools: tools.tools.map(t => ({ name: t.name, description: t.description }))
    };
  }

  async callTool(serverName, toolName, args) {
    const server = this.clients.get(serverName);
    if (!server) {
      throw new Error(`Server ${serverName} not connected`);
    }

    const result = await server.client.callTool({
      name: toolName,
      arguments: args
    });

    return result;
  }

  async disconnect(serverName) {
    const server = this.clients.get(serverName);
    if (server) {
      await server.client.close();
      this.clients.delete(serverName);
    }
  }
}

// Usage in n8n Function node
const mcpClient = new N8nMCPClient();

const serverConfigs = [
  {
    name: 'postgresql',
    transport: 'stdio',
    connection: {
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-postgres', 
             process.env.DATABASE_URL]
    }
  },
  {
    name: 'github',
    transport: 'stdio',
    connection: {
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-github'],
      env: {
        GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN
      }
    }
  }
];

const results = [];
for (const config of serverConfigs) {
  try {
    const result = await mcpClient.connectToServer(config);
    results.push(result);
  } catch (error) {
    results.push({
      connected: false,
      server: config.name,
      error: error.message
    });
  }
}

return [{ json: { connections: results } }];

// MCP Tool Executor Node
{
  "name": "MCP Tool Executor",
  "type": "n8n-nodes-base.function",
  "parameters": {
    "functionCode": `
      const { Client } = require('@modelcontextprotocol/sdk/client/index.js');
      const { StdioClientTransport } = require('@modelcontextprotocol/sdk/client/stdio.js');
      
      const serverName = $input.first().json.server_name;
      const toolName = $input.first().json.tool_name;
      const parameters = $input.first().json.parameters || {};
      
      // Load server configuration from credentials or static config
      const serverConfig = loadServerConfig(serverName);
      
      const transport = new StdioClientTransport({
        command: serverConfig.command,
        args: serverConfig.args,
        env: serverConfig.env
      });
      
      const client = new Client({
        name: 'n8n-mcp-executor',
        version: '1.0.0'
      });
      
      try {
        await client.connect(transport);
        
        // Validate tool exists
        const tools = await client.listTools();
        const tool = tools.tools.find(t => t.name === toolName);
        
        if (!tool) {
          throw new Error(\`Tool '\${toolName}' not found in server '\${serverName}'\`);
        }
        
        // Validate parameters against schema
        validateParameters(parameters, tool.inputSchema);
        
        // Execute tool
        const result = await client.callTool({
          name: toolName,
          arguments: parameters
        });
        
        await client.close();
        
        return [{
          json: {
            success: true,
            server: serverName,
            tool: toolName,
            result: result.content
          }
        }];
        
      } catch (error) {
        await client.close();
        return [{
          json: {
            success: false,
            server: serverName,
            tool: toolName,
            error: error.message
          }
        }];
      }
    `
  }
}

// n8n-as-mcp-server.js
const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
const {
  CallToolRequestSchema,
  ListToolsRequestSchema,
  ListResourcesRequestSchema,
  ReadResourceRequestSchema
} = require('@modelcontextprotocol/sdk/types.js');

class N8nMCPServer {
  constructor(n8nConfig) {
    this.n8nConfig = n8nConfig;
    this.server = new Server(
      {
        name: 'n8n-mcp-server',
        version: '1.0.0'
      },
      {
        capabilities: {
          tools: {},
          resources: {}
        }
      }
    );
    
    this.setupHandlers();
  }

  setupHandlers() {
    // List available tools (exposed n8n workflows)
    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
      return {
        tools: [
          {
            name: 'execute_n8n_workflow',
            description: 'Execute an n8n workflow with provided parameters',
            inputSchema: {
              type: 'object',
              properties: {
                workflow_id: {
                  type: 'string',
                  description: 'ID of the n8n workflow to execute'
                },
                parameters: {
                  type: 'object',
                  description: 'Parameters to pass to the workflow'
                }
              },
              required: ['workflow_id', 'parameters']
            }
          },
          {
            name: 'query_workflow_executions',
            description: 'Query historical workflow executions',
            inputSchema: {
              type: 'object',
              properties: {
                workflow_id: {
                  type: 'string',
                  description: 'Filter by workflow ID'
                },
                status: {
                  type: 'string',
                  enum: ['success', 'error', 'waiting'],
                  description: 'Filter by execution status'
                },
                limit: {
                  type: 'number',
                  default: 10,
                  description: 'Maximum number of results'
                }
              }
            }
          }
        ]
      };
    });

    // Handle tool execution
    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
      const { name, arguments: args } = request.params;
      
      if (name === 'execute_n8n_workflow') {
        return await this.executeWorkflow(args.workflow_id, args.parameters);
      } else if (name === 'query_workflow_executions') {
        return await this.queryExecutions(args);
      }
      
      throw new Error(`Unknown tool: ${name}`);
    });

    // List resources (exposed data sources)
    this.server.setRequestHandler(ListResourcesRequestSchema, async () => {
      return {
        resources: [
          {
            uri: 'n8n://workflows',
            name: 'Available Workflows',
            description: 'List of all available n8n workflows',
            mimeType: 'application/json'
          },
          {
            uri: 'n8n://executions/recent',
            name: 'Recent Executions',
            description: 'Recent workflow executions',
            mimeType: 'application/json'
          }
        ]
      };
    });

    // Read resource content
    this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
      const { uri } = request.params;
      
      if (uri === 'n8n://workflows') {
        const workflows = await this.fetchWorkflows();
        return {
          contents: [{
            uri,
            mimeType: 'application/json',
            text: JSON.stringify(workflows, null, 2)
          }]
        };
      }
      
      throw new Error(`Unknown resource: ${uri}`);
    });
  }

  async executeWorkflow(workflowId, parameters) {
    const axios = require('axios');
    
    try {
      const response = await axios.post(
        `${this.n8nConfig.baseUrl}/api/v1/workflows/${workflowId}/execute`,
        { data: parameters },
        {
          headers: {
            'X-N8N-API-KEY': this.n8nConfig.apiKey
          }
        }
      );
      
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(response.data, null, 2)
          }
        ]
      };
    } catch (error) {
      throw new Error(`Workflow execution failed: ${error.message}`);
    }
  }

  async queryExecutions(filters) {
    const axios = require('axios');
    
    const params = new URLSearchParams();
    if (filters.workflow_id) params.append('workflowId', filters.workflow_id);
    if (filters.status) params.append('status', filters.status);
    if (filters.limit) params.append('limit', filters.limit.toString());
    
    const response = await axios.get(
      `${this.n8nConfig.baseUrl}/api/v1/executions?${params.toString()}`,
      {
        headers: {
          'X-N8N-API-KEY': this.n8nConfig.apiKey
        }
      }
    );
    
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(response.data, null, 2)
        }
      ]
    };
  }

  async start() {
    const transport = new StdioServerTransport();
    await this.server.connect(transport);
    console.log('n8n MCP Server running on stdio');
  }
}

// Start server
const server = new N8nMCPServer({
  baseUrl: process.env.N8N_URL || 'http://localhost:5678',
  apiKey: process.env.N8N_API_KEY
});

server.start().catch(console.error);

// n8n workflow: AI Database Agent with MCP
{
  "name": "MCP Database AI Agent",
  "nodes": [
    {
      "type": "n8n-nodes-base.webhook",
      "name": "User Query",
      "parameters": {
        "httpMethod": "POST",
        "path": "db-agent"
      }
    },
    {
      "type": "n8n-nodes-base.agent",
      "name": "Query Understanding Agent",
      "parameters": {
        "options": {
          "systemMessage": "You are a database query specialist. Analyze the user's natural language query and determine what database operations are needed.\n\nAvailable tools via MCP:\n- postgres_query: Execute PostgreSQL queries\n- postgres_explain: Get query execution plans\n- postgres_schema: View table schemas\n\nProcess:\n1. Understand the user's intent\n2. Determine which tables are relevant\n3. Formulate appropriate SQL\n4. Consider security (no DROP, DELETE without WHERE)\n\nOutput JSON with: intent, tables_involved, suggested_query, needs_human_approval"
        }
      }
    },
    {
      "type": "n8n-nodes-base.function",
      "name": "Security Validator",
      "parameters": {
        "functionCode": `
          const query = $input.first().json.suggested_query;
          
          // Security checks
          const forbiddenPatterns = [
            /DROP\\s+TABLE/i,
            /DELETE\\s+FROM\\s+\\w+\\s*;?$/i,  // DELETE without WHERE
            /TRUNCATE/i,
            /ALTER\\s+TABLE.*DROP/i,
            /--/  // SQL injection attempt
          ];
          
          const violations = forbiddenPatterns.filter(p => p.test(query));
          
          if (violations.length > 0) {
            return [{
              json: {
                approved: false,
                reason: 'Security violation detected',
                violations: violations.map(p => p.toString())
              }
            }];
          }
          
          // Check if human approval needed
          const needsApproval = $input.first().json.needs_human_approval;
          
          if (needsApproval) {
            // Trigger approval workflow
            await $httpRequest({
              method: 'POST',
              url: process.env.APPROVAL_WEBHOOK_URL,
              body: {
                query: query,
                requester: $input.first().json.user_id,
                reason: $input.first().json.intent
              }
            });
            
            return [{
              json: {
                approved: false,
                status: 'pending_approval',
                message: 'Query requires human approval'
              }
            }];
          }
          
          return [{
            json: {
              approved: true,
              query: query,
              tables: $input.first().json.tables_involved
            }
          }];
        `
      }
    },
    {
      "type": "n8n-nodes-base.function",
      "name": "Execute MCP Query",
      "parameters": {
        "functionCode": `
          const { Client } = require('@modelcontextprotocol/sdk/client/index.js');
          const { StdioClientTransport } = require('@modelcontextprotocol/sdk/client/stdio.js');
          
          const transport = new StdioClientTransport({
            command: 'npx',
            args: ['-y', '@modelcontextprotocol/server-postgres', 
                   process.env.DATABASE_URL]
          });
          
          const client = new Client({
            name: 'n8n-db-agent',
            version: '1.0.0'
          });
          
          try {
            await client.connect(transport);
            
            const result = await client.callTool({
              name: 'query',
              arguments: {
                sql: $input.first().json.query
              }
            });
            
            await client.close();
            
            return [{
              json: {
                success: true,
                data: result.content,
                rowCount: result.content[0]?.text ? 
                  JSON.parse(result.content[0].text).length : 0
              }
            }];
            
          } catch (error) {
            await client.close();
            return [{
              json: {
                success: false,
                error: error.message
              }
            }];
          }
        `
      }
    },
    {
      "type": "n8n-nodes-base.agent",
      "name": "Results Interpreter",
      "parameters": {
        "options": {
          "systemMessage": "Convert database query results into natural language responses.\n\nGuidelines:\n1. Summarize key findings\n2. Highlight important metrics\n3. Suggest related queries\n4. Format numbers appropriately\n5. Provide context for the data\n\nTone: Professional, clear, helpful"
        }
      }
    }
  ],
  "connections": {
    "User Query": {
      "main": [
        [{"node": "Query Understanding Agent", "type": "main", "index": 0}]
      ]
    },
    "Query Understanding Agent": {
      "main": [
        [{"node": "Security Validator", "type": "main", "index": 0}]
      ]
    },
    "Security Validator": {
      "main": [
        [{"node": "Execute MCP Query", "type": "main", "index": 0}]
      ]
    },
    "Execute MCP Query": {
      "main": [
        [{"node": "Results Interpreter", "type": "main", "index": 0}]
      ]
    }
  }
}

# n8n workflow configuration: Multi-System MCP Integration
workflow:
  name: Enterprise MCP Integration Hub
  description: Central hub for MCP-based system integrations
  
  mcp_servers:
    - name: salesforce
      command: npx
      args: [-y, '@modelcontextprotocol/server-salesforce']
      env:
        SF_USERNAME: ${SF_USERNAME}
        SF_TOKEN: ${SF_TOKEN}
        
    - name: hubspot
      command: npx
      args: [-y, '@modelcontextprotocol/server-hubspot']
      env:
        HUBSPOT_API_KEY: ${HUBSPOT_API_KEY}
        
    - name: stripe
      command: npx
      args: [-y, '@modelcontextprotocol/server-stripe']
      env:
        STRIPE_API_KEY: ${STRIPE_SECRET_KEY}
        
    - name: slack
      command: npx
      args: [-y, '@modelcontextprotocol/server-slack']
      env:
        SLACK_BOT_TOKEN: ${SLACK_BOT_TOKEN}
        
    - name: notion
      command: npx
      args: [-y, '@modelcontextprotocol/server-notion']
      env:
        NOTION_API_KEY: ${NOTION_API_KEY}

  integrations:
    - name: customer_360_sync
      trigger: webhook
      description: Sync customer data across all systems
      steps:
        - action: mcp.call_tool
          server: salesforce
          tool: get_contact
          params:
            email: "{{ $input.email }}"
            
        - action: mcp.call_tool
          server: hubspot
          tool: get_contact
          params:
            email: "{{ $input.email }}"
            
        - action: n8n.transform
          description: Merge data from multiple sources
          code: |
            const merged = mergeCustomerData([
              $steps[0].result,
              $steps[1].result
            ]);
            return merged;
            
        - action: mcp.call_tool
          server: notion
          tool: update_page
          params:
            database_id: "customer-360"
            properties: "{{ $steps[2].result }}"
            
        - action: mcp.call_tool
          server: slack
          tool: send_message
          params:
            channel: "#customer-updates"
            text: "Customer {{ $input.email }} 360° profile updated"
            
    - name: invoice_to_payment_sync
      trigger: schedule
      cron: "0 */6 * * *"  # Every 6 hours
      description: Sync invoices from Stripe to Salesforce
      steps:
        - action: mcp.call_tool
          server: stripe
          tool: list_invoices
          params:
            status: open
            created[gte]: "{{ $now.minus({ hours: 6 }) }}"
            
        - action: n8n.loop
          items: "{{ $steps[0].result }}"
          steps:
            - action: mcp.call_tool
              server: salesforce
              tool: create_invoice
              params:
                stripe_invoice_id: "{{ $item.id }}"
                amount: "{{ $item.amount_due }}"
                customer_email: "{{ $item.customer_email }}"
                
        - action: mcp.call_tool
          server: slack
          tool: send_message
          params:
            channel: "#finance"
            text: "Synced {{ $steps[0].result.length }} invoices to Salesforce"

// Document Processing AI Workflow
{
  "name": "MCP Document Intelligence Pipeline",
  "nodes": [
    {
      "type": "n8n-nodes-base.webhook",
      "name": "Document Upload",
      "parameters": {
        "httpMethod": "POST",
        "path": "process-document"
      }
    },
    {
      "type": "n8n-nodes-base.function",
      "name": "Initialize MCP Connections",
      "parameters": {
        "functionCode": `
          // Connect to multiple MCP servers
          const connections = await Promise.all([
            connectMcpServer('pdf-processor', {
              command: 'npx',
              args: ['-y', '@modelcontextprotocol/server-pdf']
            }),
            connectMcpServer('ocr-service', {
              command: 'npx',
              args: ['-y', '@modelcontextprotocol/server-ocr']
            }),
            connectMcpServer('vector-store', {
              command: 'npx',
              args: ['-y', '@modelcontextprotocol/server-pinecone'],
              env: { PINECONE_API_KEY: process.env.PINECONE_API_KEY }
            })
          ]);
          
          return [{
            json: {
              connections: connections.map(c => ({
                name: c.name,
                connected: c.success,
                tools: c.tools?.length || 0
              })),
              document: $input.first().json
            }
          }];
        `
      }
    },
    {
      "type": "n8n-nodes-base.parallel",
      "name": "Parallel Processing",
      "parameters": {
        "branches": [
          {
            "name": "Extract Text",
            "nodes": [{
              "type": "n8n-nodes-base.function",
              "parameters": {
                "functionCode": "// Use MCP PDF server to extract text"
              }
            }]
          },
          {
            "name": "Extract Images",
            "nodes": [{
              "type": "n8n-nodes-base.function",
              "parameters": {
                "functionCode": "// Use MCP PDF server to extract images"
              }
            }]
          },
          {
            "name": "OCR Processing",
            "nodes": [{
              "type": "n8n-nodes-base.function",
              "parameters": {
                "functionCode": "// Use MCP OCR server for image text extraction"
              }
            }]
          }
        ]
      }
    },
    {
      "type": "n8n-nodes-base.agent",
      "name": "Document Analysis Agent",
      "parameters": {
        "options": {
          "systemMessage": "You are a document analysis expert. Review extracted content and provide structured insights.\n\nTasks:\n1. Identify document type (invoice, contract, report, etc.)\n2. Extract key entities (names, dates, amounts, clauses)\n3. Summarize content\n4. Flag items requiring attention\n5. Suggest next actions\n\nUse the MCP vector store tool to check for similar documents and context."
        }
      }
    },
    {
      "type": "n8n-nodes-base.function",
      "name": "Vectorize and Store",
      "parameters": {
        "functionCode": `
          // Store document embeddings via MCP
          const embedding = await generateEmbedding($input.first().json.content);
          
          const result = await mcpCall('vector-store', 'upsert', {
            index: 'documents',
            vectors: [{
              id: $input.first().json.document_id,
              values: embedding,
              metadata: {
                type: $input.first().json.document_type,
                source: $input.first().json.source,
                extracted_entities: $input.first().json.entities,
                summary: $input.first().json.summary
              }
            }]
          });
          
          return [{ json: { stored: true, vector_id: result.id } }];
        `
      }
    }
  ]
}

// MCP Security Middleware
class MCPSecurityGovernor {
  constructor(config) {
    this.config = {
      allowedServers: config.allowedServers || [],
      blockedTools: config.blockedTools || [],
      requireApproval: config.requireApproval || [],
      rateLimits: config.rateLimits || {},
      ...config
    };
    this.auditLog = [];
  }

  async validateServer(serverUrl) {
    // Check against allowlist
    const allowed = this.config.allowedServers.some(allowed => 
      serverUrl.startsWith(allowed)
    );
    
    if (!allowed) {
      throw new Error(`MCP server not authorized: ${serverUrl}`);
    }
    
    // Verify server identity
    const challenge = crypto.randomBytes(32).toString('hex');
    // ... verification logic
    
    return { authorized: true };
  }

  async validateToolCall(serverName, toolName, parameters) {
    // Check if tool is blocked
    if (this.config.blockedTools.includes(toolName)) {
      await this.logSecurityEvent('BLOCKED_TOOL_ATTEMPT', {
        server: serverName,
        tool: toolName
      });
      throw new Error(`Tool '${toolName}' is blocked`);
    }
    
    // Check if approval required
    if (this.config.requireApproval.includes(toolName)) {
      const approval = await this.requestHumanApproval({
        server: serverName,
        tool: toolName,
        parameters
      });
      
      if (!approval.granted) {
        throw new Error('Tool execution requires approval');
      }
    }
    
    // Check rate limits
    const limitKey = `${serverName}:${toolName}`;
    const withinLimit = await this.checkRateLimit(limitKey);
    
    if (!withinLimit) {
      throw new Error('Rate limit exceeded');
    }
    
    // Log for audit
    await this.logAudit({
      action: 'TOOL_CALL_APPROVED',
      server: serverName,
      tool: toolName,
      timestamp: new Date().toISOString()
    });
    
    return { approved: true };
  }

  async checkRateLimit(key) {
    const limit = this.config.rateLimits[key] || { requests: 100, window: 3600 };
    // Implementation using Redis or similar
    const current = await redis.incr(`ratelimit:${key}`);
    if (current === 1) {
      await redis.expire(`ratelimit:${key}`, limit.window);
    }
    return current <= limit.requests;
  }

  async logSecurityEvent(type, details) {
    await $httpRequest({
      method: 'POST',
      url: process.env.SECURITY_WEBHOOK,
      body: {
        type,
        details,
        timestamp: new Date().toISOString()
      }
    });
  }

  sanitizeParameters(parameters, schema) {
    // Remove sensitive fields
    const sensitive = ['password', 'token', 'secret', 'key', 'credential'];
    const sanitized = { ...parameters };
    
    for (const key of Object.keys(sanitized)) {
      if (sensitive.some(s => key.toLowerCase().includes(s))) {
        sanitized[key] = '[REDACTED]';
      }
    }
    
    return sanitized;
  }
}

// Usage in n8n
const securityGovernor = new MCPSecurityGovernor({
  allowedServers: [
    'https://mcp.company.com',
    'https://mcp.safe-vendor.io'
  ],
  blockedTools: ['execute_shell', 'delete_database', 'drop_table'],
  requireApproval: ['update_customer', 'process_refund', 'modify_permissions'],
  rateLimits: {
    'salesforce:query': { requests: 1000, window: 3600 },
    'stripe:create_charge': { requests: 100, window: 3600 }
  }
});

# MCP Data Protection Configuration
data_protection:
  pii_detection:
    enabled: true
    patterns:
      - type: email
        regex: \\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Z|a-z]{2,}\\b
        action: mask
      - type: ssn
        regex: \\b\\d{3}-\\d{2}-\\d{4}\\b
        action: reject
      - type: credit_card
        regex: \\b\\d{4}[\\s-]?\\d{4}[\\s-]?\\d{4}[\\s-]?\\d{4}\\b
        action: reject
      - type: phone
        regex: \\b\\+?[\\d\\s-]{10,20}\\b
        action: mask
        
  encryption:
    at_rest: true
    in_transit: true
    key_rotation_days: 90
    
  retention:
    mcp_logs_days: 90
    tool_invocations_days: 365
    audit_trail_years: 7
    
  gdpr:
    right_to_be_forgotten: true
    data_portability: true
    consent_tracking: true
    
  audit:
    log_all_calls: true
    include_request_context: true
    hash_sensitive_params: true

// MCP Observability Integration
class MCPObservability {
  constructor(langfuseConfig) {
    this.langfuse = new Langfuse(langfuseConfig);
  }

  async traceMCPSession(sessionConfig) {
    const trace = this.langfuse.trace({
      name: `mcp-session-${sessionConfig.server}`,
      userId: sessionConfig.userId,
      metadata: {
        server: sessionConfig.server,
        tools: sessionConfig.tools,
        startTime: new Date().toISOString()
      }
    });

    return {
      trace,
      
      async logToolCall(toolName, parameters, result, duration) {
        const generation = trace.generation({
          name: `mcp-tool-${toolName}`,
          model: `mcp-server:${sessionConfig.server}`,
          input: this.sanitize(parameters),
          output: this.sanitize(result),
          usage: {
            duration_ms: duration,
            // MCP servers don't typically provide token counts
            // but can provide other metrics
          }
        });

        // Send metrics to monitoring
        await this.sendMetrics({
          server: sessionConfig.server,
          tool: toolName,
          duration,
          success: !result.error,
          timestamp: new Date().toISOString()
        });
      },

      async score(quality, comment) {
        await this.langfuse.score({
          traceId: trace.id,
          name: 'mcp_session_quality',
          value: quality,
          comment
        });
      }
    };
  }

  async sendMetrics(metrics) {
    await $httpRequest({
      method: 'POST',
      url: process.env.METRICS_ENDPOINT,
      body: metrics
    });
  }

  sanitize(data) {
    // Remove PII and sensitive data
    return JSON.parse(JSON.stringify(data, (key, value) => {
      if (typeof value === 'string') {
        if (key.toLowerCase().includes('password')) return '[REDACTED]';
        if (key.toLowerCase().includes('token')) return '[REDACTED]';
        if (key.toLowerCase().includes('secret')) return '[REDACTED]';
      }
      return value;
    }));
  }
}

// Dashboard queries for MCP metrics
const mcpDashboardQueries = {
  // Tool usage by server
  toolUsage: `
    SELECT 
      server_name,
      tool_name,
      COUNT(*) as invocation_count,
      AVG(duration_ms) as avg_duration,
      SUM(CASE WHEN success THEN 1 ELSE 0 END) / COUNT(*)::float as success_rate
    FROM mcp_tool_invocations
    WHERE timestamp >= NOW() - INTERVAL '24 hours'
    GROUP BY server_name, tool_name
    ORDER BY invocation_count DESC
  `,

  // Error rates
  errorRates: `
    SELECT 
      server_name,
      error_type,
      COUNT(*) as error_count,
      COUNT(*) * 100.0 / SUM(COUNT(*)) OVER (PARTITION BY server_name) as error_percentage
    FROM mcp_errors
    WHERE timestamp >= NOW() - INTERVAL '24 hours'
    GROUP BY server_name, error_type
    ORDER BY error_count DESC
  `,

  // Latency percentiles
  latencyPercentiles: `
    SELECT 
      server_name,
      tool_name,
      percentile_cont(0.50) WITHIN GROUP (ORDER BY duration_ms) as p50,
      percentile_cont(0.95) WITHIN GROUP (ORDER BY duration_ms) as p95,
      percentile_cont(0.99) WITHIN GROUP (ORDER BY duration_ms) as p99
    FROM mcp_tool_invocations
    WHERE timestamp >= NOW() - INTERVAL '24 hours'
    GROUP BY server_name, tool_name
  `
};

// Composite MCP Tool
class CompositeMCPTool {
  constructor(tools) {
    this.tools = tools;
  }

  async executeCustomerOnboarding(customerData) {
    // Step 1: Create customer in CRM
    const crmResult = await this.tools.crm.callTool('create_contact', {
      email: customerData.email,
      first_name: customerData.firstName,
      last_name: customerData.lastName,
      company: customerData.company
    });

    // Step 2: Create Stripe customer
    const stripeResult = await this.tools.stripe.callTool('create_customer', {
      email: customerData.email,
      name: `${customerData.firstName} ${customerData.lastName}`,
      metadata: { crm_id: crmResult.id }
    });

    // Step 3: Send welcome email
    await this.tools.email.callTool('send_template', {
      to: customerData.email,
      template: 'welcome',
      variables: {
        first_name: customerData.firstName,
        company: customerData.company
      }
    });

    // Step 4: Notify Slack
    await this.tools.slack.callTool('send_message', {
      channel: '#new-customers',
      text: `🎉 New customer onboarded: ${customerData.email}`,
      blocks: [
        {
          type: 'section',
          text: {
            type: 'mrkdwn',
            text: `*New Customer*\\n${customerData.firstName} ${customerData.lastName}\\n${customerData.company}`
          }
        }
      ]
    });

    // Step 5: Create Notion page
    await this.tools.notion.callTool('create_page', {
      parent: { database_id: process.env.NOTION_CUSTOMERS_DB },
      properties: {
        Name: { title: [{ text: { content: `${customerData.firstName} ${customerData.lastName}` } }] },
        Email: { email: customerData.email },
        Company: { rich_text: [{ text: { content: customerData.company } }] },
        Status: { select: { name: 'Active' } },
        'CRM ID': { rich_text: [{ text: { content: crmResult.id } }] },
        'Stripe ID': { rich_text: [{ text: { content: stripeResult.id } }] }
      }
    });

    return {
      success: true,
      crm_id: crmResult.id,
      stripe_id: stripeResult.id,
      onboarded_at: new Date().toISOString()
    };
  }
}

// MCP Circuit Breaker
class MCPCircuitBreaker {
  constructor(config) {
    this.failureThreshold = config.failureThreshold || 5;
    this.timeoutDuration = config.timeoutDuration || 30000;
    this.resetTimeout = config.resetTimeout || 60000;
    this.state = 'CLOSED'; // CLOSED, OPEN, HALF_OPEN
    this.failureCount = 0;
    this.lastFailureTime = null;
  }

  async execute(fn) {
    if (this.state === 'OPEN') {
      if (Date.now() - this.lastFailureTime > this.resetTimeout) {
        this.state = 'HALF_OPEN';
        this.failureCount = 0;
      } else {
        throw new Error('Circuit breaker is OPEN');
      }
    }

    try {
      const result = await Promise.race([
        fn(),
        new Promise((_, reject) => 
          setTimeout(() => reject(new Error('MCP timeout')), this.timeoutDuration)
        )
      ]);

      this.onSuccess();
      return result;

    } catch (error) {
      this.onFailure();
      throw error;
    }
  }

  onSuccess() {
    this.failureCount = 0;
    this.state = 'CLOSED';
  }

  onFailure() {
    this.failureCount++;
    this.lastFailureTime = Date.now();

    if (this.failureCount >= this.failureThreshold) {
      this.state = 'OPEN';
    }
  }
}

// Usage
const circuitBreaker = new MCPCircuitBreaker({
  failureThreshold: 3,
  timeoutDuration: 10000,
  resetTimeout: 30000
});

const result = await circuitBreaker.execute(async () => {
  return await mcpClient.callTool(serverName, toolName, params);
});

// MCP Response Cache
class MCPCache {
  constructor(redisClient, defaultTTL = 3600) {
    this.redis = redisClient;
    this.defaultTTL = defaultTTL;
  }

  generateCacheKey(server, tool, params) {
    const normalized = JSON.stringify({ server, tool, params }, Object.keys(params).sort());
    return crypto.createHash('md5').update(normalized).digest('hex');
  }

  async get(server, tool, params) {
    const key = this.generateCacheKey(server, tool, params);
    const cached = await this.redis.get(`mcp:cache:${key}`);
    
    if (cached) {
      return {
        cached: true,
        data: JSON.parse(cached),
        age: Date.now() - JSON.parse(cached)._cached_at
      };
    }
    
    return null;
  }

  async set(server, tool, params, result, ttl = this.defaultTTL) {
    const key = this.generateCacheKey(server, tool, params);
    const toCache = {
      ...result,
      _cached_at: Date.now()
    };
    
    await this.redis.setex(`mcp:cache:${key}`, ttl, JSON.stringify(toCache));
  }

  async callWithCache(server, tool, params, executeFn, options = {}) {
    const { ttl = this.defaultTTL, skipCache = false } = options;
    
    if (!skipCache) {
      const cached = await this.get(server, tool, params);
      if (cached) return cached.data;
    }
    
    const result = await executeFn();
    await this.set(server, tool, params, result, ttl);
    
    return { ...result, _cached: false };
  }
}

// Cache invalidation strategies
const cacheInvalidationRules = {
  // Invalidate when specific tools are called
  'salesforce:update_contact': (params) => [`salesforce:contact:${params.id}`],
  
  // Invalidate based on time patterns
  'stripe:invoice': () => ['stripe:balance', 'stripe:transactions'],
  
  // Invalidate all related caches
  'notion:update_page': (params) => [
    `notion:page:${params.page_id}`,
    'notion:database:*'
  ]
};

// MCP Diagnostic Tool
class MCPDiagnostics {
  async diagnoseConnection(serverConfig) {
    const diagnostics = {
      timestamp: new Date().toISOString(),
      server: serverConfig.name,
      checks: []
    };

    // Check 1: Command availability
    try {
      const commandExists = await this.checkCommand(serverConfig.command);
      diagnostics.checks.push({
        name: 'command_available',
        status: commandExists ? 'PASS' : 'FAIL',
        details: commandExists ? null : `Command '${serverConfig.command}' not found`
      });
    } catch (error) {
      diagnostics.checks.push({
        name: 'command_available',
        status: 'ERROR',
        details: error.message
      });
    }

    // Check 2: Environment variables
    const requiredEnv = serverConfig.env ? Object.keys(serverConfig.env) : [];
    const missingEnv = requiredEnv.filter(key => !process.env[key]);
    
    diagnostics.checks.push({
      name: 'environment_variables',
      status: missingEnv.length === 0 ? 'PASS' : 'FAIL',
      details: missingEnv.length > 0 ? `Missing: ${missingEnv.join(', ')}` : null
    });

    // Check 3: Network connectivity (for HTTP servers)
    if (serverConfig.transport === 'http') {
      try {
        const response = await $httpRequest({
          method: 'HEAD',
          url: serverConfig.connection.url,
          timeout: 5000
        });
        
        diagnostics.checks.push({
          name: 'network_connectivity',
          status: 'PASS',
          details: `Status: ${response.statusCode}`
        });
      } catch (error) {
        diagnostics.checks.push({
          name: 'network_connectivity',
          status: 'FAIL',
          details: error.message
        });
      }
    }

    // Check 4: MCP protocol handshake
    try {
      const client = new Client({ name: 'diagnostic', version: '1.0.0' });
      const transport = serverConfig.transport === 'stdio' 
        ? new StdioClientTransport({
            command: serverConfig.command,
            args: serverConfig.args
          })
        : new HttpClientTransport({ url: serverConfig.connection.url });
      
      await client.connect(transport);
      const tools = await client.listTools();
      await client.close();
      
      diagnostics.checks.push({
        name: 'mcp_handshake',
        status: 'PASS',
        details: `Connected, ${tools.tools.length} tools available`
      });
    } catch (error) {
      diagnostics.checks.push({
        name: 'mcp_handshake',
        status: 'FAIL',
        details: error.message
      });
    }

    return diagnostics;
  }

  async checkCommand(command) {
    try {
      await exec(`which ${command}`);
      return true;
    } catch {
      return false;
    }
  }
}