Skip to main content

Freshdesk MCP Server

Create a powerful Model Context Protocol (MCP) server for Freshdesk in minutes with our AI Gateway. This guide walks you through setting up seamless customer support integration with comprehensive ticketing and instant API authentication.

About Freshdesk API​

Freshdesk is a cloud-based customer support software that enables businesses to streamline customer conversations across multiple channels. The API provides comprehensive access to tickets, contacts, agents, automation, and analytics capabilities.

Key Capabilities​

  • Ticket Management: Create, update, and track support tickets
  • Contact Management: Customer and company profiles
  • Agent Productivity: Assignment, collision detection, canned responses
  • Automation: Ticket routing, SLA management, triggers
  • Multi-channel Support: Email, phone, chat, social media
  • Knowledge Base: Solution articles and FAQs
  • Reporting: Analytics and performance metrics
  • Time Tracking: Agent productivity and billing

API Features​

  • RESTful API: JSON over HTTPS
  • API Key Authentication: Simple and secure
  • Rate Limiting: 1000 requests per hour
  • Pagination: Handle large datasets
  • Webhooks: Real-time notifications
  • Custom Fields: Extensible data model
  • Bulk Operations: Mass updates
  • Attachments: File handling support

What You Can Do with Freshdesk MCP Server​

The MCP server transforms Freshdesk API into a natural language interface, enabling AI agents to:

Ticket Management​

  • Ticket Operations

    • "Create urgent ticket for customer complaint"
    • "Update ticket status to resolved"
    • "Assign ticket to senior agent"
    • "Merge duplicate tickets"

  • Ticket Search

    • "Find all open tickets from VIP customers"
    • "Show overdue tickets"
    • "List tickets awaiting customer response"
    • "Search tickets about billing issues"

  • Bulk Actions

    • "Close all spam tickets"
    • "Reassign tickets from John to Sarah"
    • "Update priority for product bug tickets"
    • "Add tag to all feature requests"

Contact & Company Management​

  • Contact Operations

    • "Create new customer contact"
    • "Update customer email address"
    • "Mark contact as VIP"
    • "View customer ticket history"

  • Company Management

    • "Add new enterprise customer"
    • "Link contacts to company"
    • "Update company renewal date"
    • "Set custom SLA for company"

  • Contact Search

    • "Find contacts without recent activity"
    • "List VIP customers"
    • "Show contacts with multiple tickets"
    • "Search by custom fields"

Agent Management​

  • Agent Operations

    • "Check agent availability"
    • "Update agent skills"
    • "Set out of office"
    • "View agent workload"

  • Groups & Roles

    • "Create support group"
    • "Assign agents to groups"
    • "Set group escalation rules"
    • "Configure role permissions"

  • Performance Tracking

    • "Show agent response times"
    • "Calculate resolution rates"
    • "Track customer satisfaction"
    • "Monitor SLA compliance"

Automation & Workflows​

  • Automation Rules

    • "Create ticket routing rule"
    • "Set up auto-response"
    • "Configure SLA policies"
    • "Build escalation workflow"

  • Triggers & Observers

    • "Trigger on high priority tickets"
    • "Notify manager on escalation"
    • "Auto-assign based on skills"
    • "Update fields on status change"

  • Macros & Canned Responses

    • "Create response template"
    • "Build resolution macro"
    • "Share macro with team"
    • "Track macro usage"

Knowledge Base​

  • Article Management

    • "Create solution article"
    • "Update FAQ section"
    • "Publish troubleshooting guide"
    • "Archive outdated content"

  • Categories & Folders

    • "Organize by product"
    • "Create category structure"
    • "Set access permissions"
    • "Manage article visibility"

  • Search & Suggestions

    • "Find relevant articles"
    • "Suggest solutions for ticket"
    • "Track article effectiveness"
    • "Identify content gaps"

Analytics & Reporting​

  • Performance Metrics

    • "Generate SLA report"
    • "Show ticket volume trends"
    • "Calculate average response time"
    • "Track customer satisfaction"

  • Custom Reports

    • "Build agent productivity report"
    • "Analyze ticket categories"
    • "Export data for analysis"
    • "Schedule report delivery"

  • Dashboards

    • "Create team dashboard"
    • "Monitor real-time metrics"
    • "Set up alerts"
    • "Track KPIs"

Settings & Configuration​

  • Business Hours

    • "Set support hours"
    • "Configure holidays"
    • "Define SLA timings"
    • "Manage time zones"

  • Email Configuration

    • "Set up support mailbox"
    • "Configure email templates"
    • "Manage signatures"
    • "Set reply settings"

  • Custom Fields

    • "Add ticket fields"
    • "Create contact properties"
    • "Set field dependencies"
    • "Configure validations"

Prerequisites​

  • Access to Cequence AI Gateway
  • Freshdesk account (Trial or paid plan)
  • API key from Freshdesk admin
  • Your Freshdesk subdomain

Step 1: Configure Freshdesk API Access​

1.1 Get Your API Key​

  1. Log in to your Freshdesk account
  2. Click on your profile picture Profile Settings
  3. In the right panel, you'll find your API key
  4. Copy the API key (keep it secure!)

1.2 Note Your Domain​

Your Freshdesk domain is: https://yourcompany.freshdesk.com

1.3 Verify API Access​

Test your API key:

curl -u YOUR_API_KEY:X https://yourcompany.freshdesk.com/api/v2/tickets

1.4 Check Rate Limits​

  • Default: 1000 requests per hour
  • Enterprise: Higher limits available
  • Monitor X-RateLimit headers

Step 2-4: Standard Setup​

Follow standard steps to access AI Gateway, find Freshdesk API, and create MCP server.

Step 5: Configure API Endpoints​

  1. Base URL: https://yourcompany.freshdesk.com/api/v2
  2. API Version: v2 (recommended)
  3. Endpoints: Select required modules
  4. Click Next

Step 6: MCP Server Configuration​

  1. Name: "Freshdesk Support"
  2. Description: "Customer support ticketing"
  3. Request Timeout: 30 seconds
  4. Click Next

Step 7: Configure Authentication​

  1. Authentication Type: Basic Auth
  2. Username: Your API key
  3. Password: X (literal character X)
  4. Test connection

Available Freshdesk API Operations​

Ticket APIs​

  • Ticket Operations

    • Create ticket
    • View ticket
    • Update ticket
    • Delete ticket
    • List all tickets
    • Filter tickets
    • Search tickets

  • Ticket Fields

    • List ticket fields
    • Create custom field
    • Update field

  • Conversations

    • Add note
    • Add reply
    • Update conversation
    • List conversations

Contact APIs​

  • Contact Management

    • Create contact
    • View contact
    • Update contact
    • Delete contact
    • List contacts
    • Search contacts

  • Company Management

    • Create company
    • View company
    • Update company
    • List companies

Agent APIs​

  • Agent Management

    • List agents
    • View agent
    • Update agent
    • Check availability

  • Groups

    • List groups
    • Create group
    • Update group
    • Assign agents

  • Roles

    • List roles
    • View permissions

Automation APIs​

  • Automation Rules

    • List rules
    • Create rule
    • Update rule
    • Enable/disable

  • SLA Policies

    • List SLAs
    • Create SLA
    • Update targets

Solution APIs​

  • Articles

    • Create article
    • Update article
    • List articles
    • Search articles

  • Categories

    • Create category
    • List categories
    • Update category

Step 8-10: Complete Setup​

Configure security settings, choose deployment options, and deploy your server.

Using Your Freshdesk MCP Server​

With Claude Desktop​

{
  "servers": {
    "freshdesk": {
      "url": "your-mcp-server-url",
      "auth": {
        "type": "basic",
        "username": "your-api-key",
        "password": "X"
      },
      "config": {
        "subdomain": "yourcompany",
        "default_group_id": 123456
      }
    }
  }
}

Natural Language Commands​

  • "Create a high priority ticket about server outage"
  • "Show me all tickets from john@example.com"
  • "Update ticket #1234 status to pending"
  • "Find solution articles about password reset"
  • "Assign all new tickets to available agents"

API Integration Example​

// Initialize MCP client
const mcpClient = new MCPClient({
  serverUrl: 'your-mcp-server-url',
  auth: {
    type: 'basic',
    username: 'your-api-key',
    password: 'X'
  }
});

// Create a ticket
const ticket = await mcpClient.freshdesk.createTicket({
  subject: 'Unable to access dashboard',
  description: 'Getting 500 error when trying to log in to dashboard',
  email: 'customer@example.com',
  priority: 3, // High
  status: 2, // Open
  source: 3, // Email
  tags: ['dashboard', 'login-issue', 'bug'],
  custom_fields: {
    cf_impact: 'Multiple Users',
    cf_product: 'Web Application'
  }
});

console.log(`Created ticket #${ticket.id}`);

// Update ticket with internal note
const note = await mcpClient.freshdesk.addNote({
  ticketId: ticket.id,
  body: 'Investigated the issue. Found database connection timeout. Escalating to DevOps team.',
  private: true,
  notify_emails: ['devops@company.com']
});

// Search for similar tickets
const similarTickets = await mcpClient.freshdesk.searchTickets({
  query: '"dashboard" AND "500 error"',
  page: 1,
  per_page: 10
});

console.log(`Found ${similarTickets.results.length} similar tickets`);

// Create or update contact
const contact = await mcpClient.freshdesk.createOrUpdateContact({
  email: 'customer@example.com',
  name: 'John Doe',
  phone: '+1-555-123-4567',
  company_id: 12345,
  view_all_tickets: true,
  custom_fields: {
    cf_customer_tier: 'Premium',
    cf_account_manager: 'Sarah Smith'
  }
});

// Bulk update tickets
const bulkUpdate = await mcpClient.freshdesk.bulkUpdateTickets({
  ids: [1001, 1002, 1003, 1004],
  properties: {
    status: 5, // Closed
    tags: ['resolved', 'q1-2025']
  }
});

// Create automation rule
const automationRule = await mcpClient.freshdesk.createAutomationRule({
  name: 'Auto-assign VIP tickets',
  description: 'Assign high priority tickets from VIP customers to senior agents',
  active: true,
  position: 1,
  conditions: {
    all: [
      { field: 'priority', operator: 'is', value: [3, 4] }, // High or Urgent
      { field: 'cf_customer_tier', operator: 'is', value: 'VIP' }
    ]
  },
  actions: [
    { field: 'group_id', value: 456789 }, // Senior Support Group
    { field: 'tags', value: ['vip-customer', 'priority-handling'] },
    { field: 'email_config_id', value: 789012 } // Send notification
  ]
});

// Set up SLA policy
const slaPolicy = await mcpClient.freshdesk.createSLA({
  name: 'Premium Customer SLA',
  description: 'Enhanced SLA for premium customers',
  active: true,
  targets: {
    priority_1: { respond_within: 30, resolve_within: 240 }, // 30 min, 4 hours
    priority_2: { respond_within: 60, resolve_within: 480 }, // 1 hour, 8 hours
    priority_3: { respond_within: 120, resolve_within: 960 }, // 2 hours, 16 hours
    priority_4: { respond_within: 240, resolve_within: 1440 } // 4 hours, 24 hours
  },
  applicable_to: {
    company_ids: [12345, 67890],
    custom_fields: {
      cf_customer_tier: ['Premium', 'VIP']
    }
  },
  escalation: {
    response: [
      { escalate_after: 15, assign_to: 'group', group_id: 456789 }
    ],
    resolution: [
      { escalate_after: 120, assign_to: 'agent', agent_id: 789012 }
    ]
  }
});

// Create solution article
const article = await mcpClient.freshdesk.createArticle({
  title: 'How to Reset Your Password',
  description: 'Step-by-step guide to reset your account password',
  article_type: 1, // Permanent
  folder_id: 234567,
  status: 2, // Published
  tags: ['password', 'account', 'security'],
  seo: {
    meta_title: 'Password Reset Guide',
    meta_description: 'Learn how to reset your password quickly',
    meta_keywords: ['password reset', 'forgot password', 'account recovery']
  },
  content: `
    <h2>Reset Your Password</h2>
    <ol>
      <li>Click on "Forgot Password" on the login page</li>
      <li>Enter your email address</li>
      <li>Check your email for reset link</li>
      <li>Click the link and set new password</li>
    </ol>
    <p>Password must be at least 8 characters with one uppercase, lowercase, and number.</p>
  `
});

// Generate report
const report = await mcpClient.freshdesk.generateReport({
  metric: 'ticket_volume',
  group_by: 'source',
  date_range: {
    from: '2025-01-01',
    to: '2025-01-31'
  },
  filters: {
    group_id: [123456, 456789],
    priority: [3, 4]
  }
});

console.log('Ticket Volume by Source:');
report.data.forEach(row => {
  console.log(`${row.source}: ${row.count} tickets`);
});

// Monitor agent availability
const agents = await mcpClient.freshdesk.listAgents({
  state: 'active',
  availability: true
});

const availableAgents = agents.filter(agent => agent.available);
console.log(`${availableAgents.length} agents currently available`);

// Handle webhook events
app.post('/webhooks/freshdesk', async (req, res) => {
  const event = req.body;
  
  if (event.ticket_event_type === 'ticket_created') {
    const ticket = event.ticket;
    
    // Auto-respond to new tickets
    if (ticket.source === 3) { // Email
      await mcpClient.freshdesk.addReply({
        ticketId: ticket.id,
        body: 'Thank you for contacting support. We have received your request and will respond within 2 hours.',
        user_id: botAgentId
      });
    }
    
    // Check for urgent keywords
    const urgentKeywords = ['down', 'critical', 'urgent', 'emergency'];
    const isUrgent = urgentKeywords.some(keyword => 
      ticket.subject.toLowerCase().includes(keyword) ||
      ticket.description.toLowerCase().includes(keyword)
    );
    
    if (isUrgent && ticket.priority < 4) {
      await mcpClient.freshdesk.updateTicket({
        id: ticket.id,
        priority: 4 // Urgent
      });
    }
  }
  
  res.status(200).send('OK');
});

// Canned response macro
const macro = await mcpClient.freshdesk.createCannedResponse({
  name: 'Request More Information',
  content: `Hi {{ticket.requester.name}},

Thank you for reaching out. To better assist you, could you please provide:

1. Steps to reproduce the issue
2. Error messages (if any)
3. Browser/OS information
4. Screenshots if applicable

This will help us resolve your issue more quickly.

Best regards,
{{agent.name}}`,
  available_for: 'all_agents',
  labels: ['information', 'troubleshooting']
});

// Time tracking
const timeEntry = await mcpClient.freshdesk.addTimeEntry({
  ticketId: ticket.id,
  time_spent: '00:30', // 30 minutes
  executed_at: new Date().toISOString(),
  billable: true,
  note: 'Initial investigation and response'
});

Common Use Cases​

Customer Support Operations​

  • Ticket triage and routing
  • SLA management
  • Customer communication
  • Escalation handling

Knowledge Management​

  • Solution articles
  • FAQ maintenance
  • Self-service portal
  • Content effectiveness

Team Management​

  • Workload distribution
  • Performance tracking
  • Skill-based routing
  • Training needs

Process Automation​

  • Auto-responses
  • Ticket categorization
  • Workflow automation
  • Integration triggers

Best Practices​

  1. Ticket Management:

    • Use consistent tagging
    • Set clear priorities
    • Maintain ticket hygiene
    • Regular status updates

  2. Automation:

    • Start simple, iterate
    • Test rules thoroughly
    • Monitor rule impacts
    • Document automation logic

  3. Performance:

    • Use pagination for large datasets
    • Cache frequently used data
    • Batch operations when possible
    • Monitor API usage

Troubleshooting​

Common Issues​

  1. Authentication Errors

    • Verify API key format
    • Check domain spelling
    • Ensure account is active
    • Validate permissions

  2. Rate Limiting

    • Monitor X-RateLimit headers
    • Implement backoff strategy
    • Use bulk operations
    • Cache responses

  3. Data Issues

    • Validate required fields
    • Check field types
    • Handle custom fields
    • Verify ID references

Getting Help​