N8n Personal Assistant Integration - sieteunoseis/mcp-cisco-support GitHub Wiki

N8n Personal Assistant Integration

This guide shows how to integrate the Cisco Support MCP Server with N8n's Personal Assistant agent to create a powerful AI-powered support workflow.

Overview

The N8n Personal Assistant agent can be configured to use the mcp-cisco-support server as a tool, enabling intelligent Cisco support queries through a conversational interface with persistent memory.

Architecture Components

Chat Trigger: Webhook endpoint for receiving user messages
Personal Assistant Agent: LangChain-powered AI agent with tool capabilities
MCP Client Tool: Connection to mcp-cisco-support server
Chat Memory: PostgreSQL-backed conversation persistence
Language Model: OpenRouter integration for AI responses

N8n Workflow Configuration

Workflow JSON Template

{
  "name": "OHSU Cisco Support Agent",
  "nodes": [
    {
      "parameters": {
        "public": true,
        "options": {}
      },
      "id": "e94218b9-8ee3-476a-bc35-82bbe392c345",
      "name": "When chat message received",
      "type": "@n8n/n8n-nodes-langchain.chatTrigger",
      "position": [380, 240],
      "webhookId": "44955ca2-3fcd-4d59-b1cb-7803c0da99ec",
      "typeVersion": 1.1
    },
    {
      "parameters": {
        "options": {
          "systemMessage": "You are a specialized Cisco Support Assistant with access to comprehensive Cisco support tools and databases. Your primary role is to help users troubleshoot Cisco networking equipment, find bug information, analyze software releases, and provide technical guidance.\n\n## Your Capabilities\n\nYou have access to multiple Cisco Support APIs through specialized tools:\n\n### Bug Search & Analysis\n- Search for bugs by keywords, product IDs, or product names\n- Get detailed bug information including severity, status, and affected/fixed releases\n- Find bugs related to specific software versions or product series\n- Analyze bug patterns and provide recommendations\n- Use multi-severity search for comprehensive coverage\n\n### Product Information\n- Look up detailed product specifications and technical information\n- Find product family relationships and compatibility information\n- Access product documentation and support resources\n\n### Software Analysis\n- Get software suggestions and recommendations for products\n- Find information about software releases and their fixes\n- Analyze compatibility between products and software versions\n\n### Security Vulnerability Research\n- Search PSIRT (Product Security Incident Response Team) advisories\n- Find CVE vulnerability information for Cisco products\n- Get security recommendations and mitigation strategies\n\n## Communication Guidelines\n\n1. **Be Proactive**: When users mention Cisco products or issues, immediately search for relevant bugs, advisories, or product information\n\n2. **Provide Context**: Always explain the significance of findings - why a bug matters, what the severity means, and what actions should be taken\n\n3. **Use Multiple Sources**: Combine information from different APIs to provide comprehensive answers (e.g., product info + bug search + software suggestions)\n\n4. **Be Specific**: Include bug IDs, software versions, product part numbers, and other specific identifiers in your responses\n\n5. **Prioritize Security**: Always highlight security-related bugs, CVEs, and PSIRT advisories with high visibility\n\n6. **Research Bug Severity Strategically**: Always research multiple severity levels to provide comprehensive coverage\n   - Start with Critical Issues: Begin with severity 1-2 for immediate threats\n   - Expand for Complete Picture: Include severity 3 for moderate issues that may become critical\n   - Use Multi-Severity Search: Leverage multi_severity_search tool for comprehensive analysis\n   - Explain Severity Impact: Always explain what each severity level means for operations\n\n## Cisco Bug Severity Levels\n\nAlways explain severity levels when presenting findings:\n- **Severity 1 (Catastrophic)**: Complete network failure, major security vulnerability - IMMEDIATE ACTION REQUIRED\n- **Severity 2 (High)**: Significant degradation, partial network failure - Schedule maintenance within days\n- **Severity 3 (Medium)**: Minor degradation, workaround available - Plan for next maintenance window\n- **Severity 4-6 (Low)**: Cosmetic issues, minimal impact - Include in routine maintenance\n\n## Response Format\n\nStructure your responses to include:\n- **Summary**: Quick overview with total bug counts by severity\n- **Critical Issues**: Severity 1-2 bugs requiring immediate attention\n- **Moderate Issues**: Severity 3 bugs requiring planned maintenance\n- **Severity Assessment**: Clear explanation of risk levels and operational impact\n- **Recommendations**: Specific actions prioritized by severity and urgency\n- **Additional Resources**: Links to documentation, bug details, or advisories\n\n## Example Research Process\n\n**User**: \"We're having memory issues with our Catalyst 9200 running 17.5.1\"\n\n**Your Process**:\n1. Use multi_severity_search for \"Catalyst 9200\" with max_severity=3\n2. Search specifically for \"memory\" + \"Catalyst 9200\" \n3. Check bugs affecting 17.5.1 specifically\n4. Look up software suggestions for newer releases\n5. Present: \"Found X bugs (Y critical, Z high, W moderate) - Critical issues require immediate attention: [specific bugs with IDs]\"\n\n**Always Use Multi-Severity Search**: For any product inquiry, use the multi_severity_search tool to get comprehensive coverage across severity levels. This ensures you don't miss critical issues.\n\nRemember: You are the expert bridge between complex Cisco technical data and actionable user guidance. Always prioritize accuracy, security, and practical recommendations based on severity levels."
        }
      },
      "id": "5cbafcfa-1f33-436d-b153-5c26ce302402",
      "name": "Personal Assistant",
      "type": "@n8n/n8n-nodes-langchain.agent",
      "position": [640, 240],
      "typeVersion": 1.9,
      "retryOnFail": false
    },
    {
      "parameters": {},
      "type": "@n8n/n8n-nodes-langchain.memoryPostgresChat",
      "typeVersion": 1.3,
      "position": [700, 440],
      "id": "9b08bc86-17e0-4947-98fc-9288ed8aa6f4",
      "name": "Postgres Chat Memory",
      "credentials": {
        "postgres": {
          "id": "HtYYYKuX9hwn1nAO",
          "name": "Postgres account"
        }
      }
    },
    {
      "parameters": {
        "sseEndpoint": "http://biccapps01.ohsu.edu:3100/sse",
        "authentication": "bearerAuth"
      },
      "id": "de0ab665-b392-4cca-8ce7-e8ce310cd60a",
      "name": "mcp-cisco-support",
      "type": "@n8n/n8n-nodes-langchain.mcpClientTool",
      "position": [1040, 500],
      "typeVersion": 1,
      "credentials": {
        "httpBearerAuth": {
          "id": "VBD76z8X5TOeLLTK",
          "name": "Bearer Auth account"
        }
      }
    },
    {
      "parameters": {
        "options": {}
      },
      "type": "@n8n/n8n-nodes-langchain.lmChatOpenRouter",
      "typeVersion": 1,
      "position": [560, 440],
      "id": "8694c277-5ef6-44ba-acdf-ba92d2b86e26",
      "name": "OpenRouter Chat Model",
      "credentials": {
        "openRouterApi": {
          "id": "ZBZ8pxWtoKzbOJzQ",
          "name": "OpenRouter account"
        }
      }
    }
  ],
  "connections": {
    "When chat message received": {
      "main": [
        [
          {
            "node": "Personal Assistant",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Postgres Chat Memory": {
      "ai_memory": [
        [
          {
            "node": "Personal Assistant",
            "type": "ai_memory",
            "index": 0
          }
        ]
      ]
    },
    "mcp-cisco-support": {
      "ai_tool": [
        [
          {
            "node": "Personal Assistant",
            "type": "ai_tool",
            "index": 0
          }
        ]
      ]
    },
    "OpenRouter Chat Model": {
      "ai_languageModel": [
        [
          {
            "node": "Personal Assistant",
            "type": "ai_languageModel",
            "index": 0
          }
        ]
      ]
    }
  }
}

Configuration Steps

1. MCP Server Setup

Ensure your mcp-cisco-support server is running in HTTP mode:

# Start the server with HTTP transport
npx mcp-cisco-support --http --port 3100

# Or using Docker
docker run -d -p 3100:3100 \
  -e CISCO_CLIENT_ID=your_id \
  -e CISCO_CLIENT_SECRET=your_secret \
  ghcr.io/sieteunoseis/mcp-cisco-support:latest --http

2. N8n Node Configuration

Chat Trigger Node

Type: @n8n/n8n-nodes-langchain.chatTrigger
Configuration: Enable public access for webhook endpoint
Webhook ID: Auto-generated unique identifier

Personal Assistant Agent Node

Type: @n8n/n8n-nodes-langchain.agent
System Message: Use the comprehensive system message provided above
Tools: Connected to MCP Client Tool
Memory: Connected to PostgreSQL Chat Memory
Language Model: Connected to OpenRouter Chat Model

MCP Client Tool Node

Type: @n8n/n8n-nodes-langchain.mcpClientTool
SSE Endpoint: http://your-server:3100/sse
Authentication: Bearer token (if required)

PostgreSQL Chat Memory Node

Type: @n8n/n8n-nodes-langchain.memoryPostgresChat
Database: PostgreSQL credentials for conversation persistence

OpenRouter Chat Model Node

Type: @n8n/n8n-nodes-langchain.lmChatOpenRouter
API Key: OpenRouter API credentials
Model: Choose appropriate model (Claude, GPT-4, etc.)

System Message Prompt

The system message configures the AI assistant's behavior and capabilities:

You are a specialized Cisco Support Assistant with access to comprehensive Cisco support tools and databases. Your primary role is to help users troubleshoot Cisco networking equipment, find bug information, analyze software releases, and provide technical guidance.

## Your Capabilities

You have access to multiple Cisco Support APIs through specialized tools:

### Bug Search & Analysis
- Search for bugs by keywords, product IDs, or product names
- Get detailed bug information including severity, status, and affected/fixed releases
- Find bugs related to specific software versions or product series
- Analyze bug patterns and provide recommendations

### Product Information
- Look up detailed product specifications and technical information
- Find product family relationships and compatibility information
- Access product documentation and support resources

### Software Analysis
- Get software suggestions and recommendations for products
- Find information about software releases and their fixes
- Analyze compatibility between products and software versions

### Security Vulnerability Research
- Search PSIRT (Product Security Incident Response Team) advisories
- Find CVE vulnerability information for Cisco products
- Get security recommendations and mitigation strategies

## Communication Guidelines

1. **Be Proactive**: When users mention Cisco products or issues, immediately search for relevant bugs, advisories, or product information

2. **Provide Context**: Always explain the significance of findings - why a bug matters, what the severity means, and what actions should be taken

3. **Use Multiple Sources**: Combine information from different APIs to provide comprehensive answers (e.g., product info + bug search + software suggestions)

4. **Be Specific**: Include bug IDs, software versions, product part numbers, and other specific identifiers in your responses

5. **Prioritize Security**: Always highlight security-related bugs, CVEs, and PSIRT advisories with high visibility

6. **Research Bug Severity Strategically**: Always research multiple severity levels to provide comprehensive coverage
   - **Start with Critical Issues**: Begin with severity 1-2 for immediate threats
   - **Expand for Complete Picture**: Include severity 3 for moderate issues that may become critical
   - **Use Multi-Severity Search**: Leverage `multi_severity_search` tool for comprehensive analysis
   - **Explain Severity Impact**: Always explain what each severity level means for operations

## Response Format

Structure your responses to include:
- **Summary**: Quick overview of findings with total bug counts by severity
- **Critical Issues**: Any high-severity bugs or security vulnerabilities (Severity 1-2)
- **Moderate Issues**: Important bugs that require attention (Severity 3)
- **Severity Assessment**: Clear explanation of risk levels and operational impact
- **Recommendations**: Specific actions prioritized by severity and urgency
- **Additional Resources**: Links to documentation, bug details, or advisories

## Cisco Bug Severity Levels

Always explain severity levels when presenting findings:

- **Severity 1 (Catastrophic)**: 
  - **Impact**: Complete network failure, major security vulnerability
  - **Action**: Immediate attention required, emergency maintenance window
  - **Response Time**: Within hours

- **Severity 2 (High)**: 
  - **Impact**: Significant degradation, partial network failure
  - **Action**: Schedule maintenance within days, high priority
  - **Response Time**: Within 1-2 business days

- **Severity 3 (Medium)**: 
  - **Impact**: Minor degradation, workaround available
  - **Action**: Plan for next maintenance window, medium priority
  - **Response Time**: Within 1-2 weeks

- **Severity 4-6 (Low)**: 
  - **Impact**: Cosmetic issues, minimal operational impact
  - **Action**: Include in routine maintenance, low priority
  - **Response Time**: Next scheduled maintenance

## Example Interactions

**User**: "We're having memory issues with our Catalyst 9200 running 17.5.1"

**Your Response Process**:
1. **Multi-Severity Search**: Use `multi_severity_search` for "Catalyst 9200" with max_severity=3
2. **Targeted Search**: Search for "memory" + "Catalyst 9200" specifically
3. **Version Analysis**: Check bugs affecting 17.5.1 specifically
4. **Software Suggestions**: Look up newer stable releases
5. **Present Results**:
   - "Found X bugs affecting Catalyst 9200 (Y severity 1-2, Z severity 3)"
   - "Critical Issues (Severity 1-2): [List with immediate action required]"
   - "Moderate Issues (Severity 3): [List with planned maintenance needed]"
   - "Recommendation: Upgrade to version X.X.X which resolves Y critical bugs"

**User**: "What's the latest secure software for ASR 9000?"

**Your Response Process**:
1. **Security Focus**: Use `multi_severity_search` with max_severity=2 for critical security issues
2. **PSIRT Check**: Search PSIRT advisories for ASR 9000 security vulnerabilities
3. **Software Analysis**: Get latest software suggestions for ASR 9000 series
4. **Present Results**:
   - "Security Assessment: Found X security-related bugs (Y critical, Z high severity)"
   - "Latest Secure Version: X.X.X (resolves CVE-YYYY-XXXX and other critical issues)"
   - "Immediate Action Required: [List Severity 1-2 security vulnerabilities]"
   - "Upgrade Path: [Specific steps and considerations]"

**User**: "Should we upgrade our ISR4431 from 17.9.6 to 17.12.4?"

**Your Response Process**:
1. **Current Version Analysis**: Search bugs affecting 17.9.6 on ISR4431
2. **Target Version Analysis**: Search bugs affecting 17.12.4 on ISR4431  
3. **Fixed Issues**: Search bugs fixed in 17.12.4
4. **Comprehensive Assessment**: Use multi-severity search for complete picture
5. **Present Upgrade Analysis**:
   - "Current Version (17.9.6): X bugs (Y critical, Z high, W moderate)"
   - "Target Version (17.12.4): A bugs (B critical, C high, D moderate)"
   - "Bugs Fixed by Upgrade: [List critical and high severity fixes]"
   - "New Issues Introduced: [Any new bugs in target version]"
   - "Recommendation: [Clear upgrade decision with risk assessment]"

Remember: You are the expert bridge between complex Cisco technical data and actionable user guidance. Always prioritize accuracy, security, and practical recommendations.

Authentication & Security

MCP Server Authentication

If your MCP server requires authentication:

Bearer Token: Configure HTTP Bearer Auth credentials in N8n
API Keys: Set Cisco API credentials as environment variables
Network Security: Ensure proper firewall rules for server communication

N8n Security Considerations

Webhook Security: Consider enabling authentication for chat triggers
Database Security: Use encrypted connections for PostgreSQL memory
API Key Management: Store credentials securely in N8n credential store
Network Isolation: Deploy on secure networks with proper access controls

Usage Examples

Basic Bug Search

User: "Find bugs for Catalyst 9300 switch" Agent: Searches bug database, returns relevant bugs with severity, status, and recommendations

Product-Specific Troubleshooting

User: "C9300-48P having high CPU usage" Agent:

Searches for CPU-related bugs on C9300-48P
Checks software suggestions for stable releases
Provides specific bug IDs and upgrade paths

Security Advisory Lookup

User: "Any security issues with ASR 1000 series?" Agent:

Searches PSIRT database for ASR 1000 advisories
Lists CVEs and severity levels
Recommends mitigation strategies

Monitoring & Troubleshooting

N8n Workflow Monitoring

Execution Logs: Monitor workflow execution history
Error Handling: Configure retry logic for API failures
Performance Metrics: Track response times and success rates

MCP Server Health

Health Endpoint: Monitor http://server:3100/health
SSE Connection: Verify Server-Sent Events connectivity
API Rate Limits: Monitor Cisco API usage quotas

Common Issues

SSE Connection Closing Immediately:
- Symptoms: MCP server logs show "SSE connection closed" immediately after connection
- Cause: N8n authentication or connection handshake issues
- Solution:
  - Verify Bearer token is correctly configured in N8n credentials
  - Check that sseEndpoint uses correct URL: http://biccapps01.ohsu.edu:3100/sse
  - Ensure MCP server is accessible from N8n instance
  - Test SSE endpoint manually: curl -H "Authorization: Bearer YOUR_TOKEN" http://biccapps01.ohsu.edu:3100/sse
SSE Timeout Errors (Body Timeout Error):
- Symptoms: SseError: SSE error: TypeError: terminated: Body Timeout Error
- Cause: Network timeout, connection instability, or server overload
- Server-Side Fixes (v1.9.4+):
  - Added automatic heartbeat every 30 seconds to keep connections alive
  - Improved timeout handling with 2-minute connection timeout
  - Enhanced error logging with detailed error information
  - Graceful connection cleanup on errors
- Client-Side Solutions:
  - Restart N8n Workflow: Stop and restart the workflow to re-establish connection
  - Check Network Stability: Ensure stable network connection between N8n and MCP server
  - Increase Timeout: If possible, increase timeout settings in N8n MCP Client Tool
  - Monitor Server Load: Check if MCP server is under heavy load
- Prevention:
  - Use latest mcp-cisco-support version (1.9.4+) with improved timeout handling
  - Monitor server logs for connection patterns and errors
  - Consider load balancing if running multiple N8n instances
MCP Tools Not Available in N8n:
- Symptoms: N8n shows empty tool list or "no tools available"
- Cause: SSE connection not establishing properly
- Solution:
  - Check MCP server logs for successful tool list requests
  - Verify N8n MCP Client Tool is properly connected to Personal Assistant
  - Restart N8n workflow after fixing SSE connection issues
API Rate Limiting: Implement proper backoff and retry strategies
Memory Persistence: Verify PostgreSQL connectivity and schema
Token Expiration: Monitor OAuth2 token refresh cycles
Invalid Sort Parameter Values:
- Issue: Tool calls fail with "sort_by: LAST_MODIFIED_DATE which isn't valid"
- Cause: Invalid sort_by parameter value - API only accepts specific values
- Solution: Use valid sort_by values: status, modified_date, severity, support_case_count, modified_date_earliest
Keyword Search Length Limitation:
- Issue: multi_severity_search with search_type: "keyword" fails for long product names
- Cause: Cisco Bug API keyword searches limited to 50 characters
- Examples:
  - ❌ "Cisco 4000 Series Integrated Services Routers" (52 chars) fails
  - ✅ "ISR4000" (7 chars) works
- Solutions:
  - Use search_type: "product_series" with affected_releases for full product names
  - Server auto-shortens: "Cisco 4000 Series..." → "ISR4000"
  - Use shorter keywords: "4000 Series", "ISR4431", etc.

API Parameter Validation Errors

If you encounter errors like:

Tool: multi_severity_search failed with: sort_by: LAST_MODIFIED_DATE which isn't valid

This indicates the Cisco API received an invalid parameter value. Common fixes:

Use Valid Sort Values: Only use supported sort_by values from the enum list
Check Parameter Values: Verify parameter values match API documentation
Review Tool Schemas: Ensure tool calls use valid enum values

Cisco API Limitations (Important)

The Cisco Bug API v2.0 has specific parameter limitations:

Severity: Only single values ("1", "2", "3") - no comma-separated lists
Status: Only single values ("O", "F", "T") - no comma-separated lists
Sort By: Only accepts: status, modified_date, severity, support_case_count, modified_date_earliest
Multiple Values: For searches requiring multiple severities/statuses, make separate API calls

Best Practices

Workflow Design

Error Handling: Implement comprehensive error handling nodes
Rate Limiting: Respect API rate limits with appropriate delays
Caching: Consider caching frequent queries to improve performance
Logging: Enable detailed logging for troubleshooting

System Message Optimization

Context Awareness: Update system message based on organizational needs
Tool Utilization: Encourage proactive use of available tools
Response Format: Standardize output format for consistency
Domain Expertise: Include organization-specific Cisco environment details

Performance Optimization

Database Indexing: Optimize PostgreSQL for chat memory performance
Connection Pooling: Use connection pooling for database and API calls
Async Processing: Leverage N8n's async capabilities for parallel operations
Resource Monitoring: Monitor memory and CPU usage during peak loads

Advanced Configuration

Custom Prompts

Modify the system message to include:

Organization-specific product inventory
Custom troubleshooting workflows
Integration with internal ticketing systems
Escalation procedures for critical issues
Specific severity response procedures for your organization

Severity Research Configuration

Ensure your N8n Personal Assistant is configured to:

Always use multi_severity_search for comprehensive bug analysis
Explain severity impact in terms relevant to your business operations
Provide prioritized recommendations based on your maintenance schedules
Include bug counts by severity in all responses for quick assessment
Escalate critical findings according to your organization's procedures

Multi-Agent Workflows

Extend the workflow with additional agents:

Triage Agent: Initial problem classification
Specialist Agents: Product-specific expertise
Escalation Agent: Complex issue handling

Integration Extensions

Connect additional tools and services:

Ticket Systems: ServiceNow, Jira integration
Monitoring Tools: Network monitoring system queries
Documentation: Internal knowledge base access
Notification Systems: Slack, Teams, email alerts

This N8n Personal Assistant integration provides a powerful, conversational interface to Cisco support data with persistent memory and intelligent tool usage.