HubSpot Service Hub MCP Server

Create a powerful Model Context Protocol (MCP) server for HubSpot Service Hub in minutes with our AI Gateway. This guide walks you through setting up seamless customer service integration with enterprise-grade security and instant OAuth authentication.

About HubSpot Service Hub API

HubSpot Service Hub helps businesses deliver exceptional customer service experiences. The Service Hub API provides programmatic access to ticketing, knowledge base, customer feedback, and help desk automation features.

Key Capabilities

• Ticket Management: Create, track, and resolve support tickets
• Knowledge Base: Self-service help articles and documentation
• Customer Feedback: Surveys and satisfaction tracking
• Live Chat: Real-time customer communication
• Help Desk Automation: Ticket routing and workflows
• SLA Management: Service level agreement tracking
• Customer Portal: Self-service ticket management
• Reporting: Service metrics and analytics

API Features

• REST API v3: Modern RESTful interface
• Conversations API: Chat and messaging access
• Tickets API: Full ticket lifecycle management
• OAuth 2.0: Secure authentication
• Webhooks: Real-time event notifications
• Rate Limiting: 100-500 requests/10 seconds
• Batch Operations: Bulk ticket updates
• Custom Properties: Extended ticket fields

What You Can Do with HubSpot Service Hub MCP Server

The MCP server transforms HubSpot Service Hub's API into a natural language interface, enabling AI agents to:

Ticket Management

• Ticket Operations

  • "Create high-priority support ticket"
  • "Assign ticket to technical support team"
  • "Update ticket status to in progress"
  • "Close resolved tickets from yesterday"

• Ticket Routing

  • "Route billing tickets to finance team"
  • "Escalate unresolved priority tickets"
  • "Auto-assign based on expertise"
  • "Transfer ticket to senior agent"

• Ticket Search

  • "Find all open tickets for customer"
  • "Show tickets awaiting response"
  • "List overdue tickets by priority"
  • "Search tickets by keyword"

Customer Communication

• Response Management

  • "Send initial response to ticket"
  • "Add internal note to ticket"
  • "Request more information from customer"
  • "Send resolution confirmation"

• Chat Operations

  • "Start live chat session"
  • "Transfer chat to specialist"
  • "Convert chat to ticket"
  • "Send chat transcript"

• Email Integration

  • "Reply to customer email"
  • "Add email to ticket thread"
  • "Set up auto-responses"
  • "Track email open rates"

Knowledge Base Management

• Article Creation

  • "Create troubleshooting guide"
  • "Add FAQ article"
  • "Update product documentation"
  • "Publish release notes"

• Content Organization

  • "Organize articles by category"
  • "Tag articles with keywords"
  • "Set article visibility"
  • "Create article templates"

• Article Analytics

  • "Show most viewed articles"
  • "Track article helpfulness"
  • "Find articles needing updates"
  • "Monitor search queries"

Customer Feedback

• Survey Management

  • "Send CSAT survey after ticket closure"
  • "Create NPS survey campaign"
  • "Design custom feedback form"
  • "Schedule survey distribution"

• Feedback Analysis

  • "Show average satisfaction score"
  • "Analyze feedback trends"
  • "Identify unhappy customers"
  • "Track agent performance"

• Response Actions

  • "Follow up on negative feedback"
  • "Thank customers for positive reviews"
  • "Escalate critical feedback"
  • "Create improvement tasks"

SLA Management

• SLA Configuration

  • "Set first response time SLA"
  • "Configure resolution time targets"
  • "Create priority-based SLAs"
  • "Define business hours"

• SLA Monitoring

  • "Show SLA breach warnings"
  • "Track SLA compliance rate"
  • "Alert on approaching deadlines"
  • "Generate SLA reports"

• Escalation Rules

  • "Auto-escalate SLA breaches"
  • "Notify managers of violations"
  • "Reassign at-risk tickets"
  • "Apply priority upgrades"

Help Desk Automation

• Workflow Automation

  • "Auto-categorize incoming tickets"
  • "Apply tags based on content"
  • "Route by customer tier"
  • "Set default properties"

• Response Automation

  • "Send acknowledgment emails"
  • "Provide suggested articles"
  • "Auto-close inactive tickets"
  • "Schedule follow-ups"

• Integration Automation

  • "Sync with CRM records"
  • "Update deal stage on resolution"
  • "Create tasks for follow-up"
  • "Log activities automatically"

Reporting & Analytics

• Performance Metrics

  • "Show average response time"
  • "Calculate resolution rate"
  • "Track ticket volume trends"
  • "Measure agent productivity"

• Customer Insights

  • "Identify frequent requesters"
  • "Analyze issue patterns"
  • "Track customer journey"
  • "Monitor satisfaction trends"

• Team Analytics

  • "Compare agent performance"
  • "Track team workload"
  • "Identify training needs"
  • "Measure efficiency gains"

Prerequisites

• Access to Cequence AI Gateway
• HubSpot Service Hub Professional or Enterprise
• Super Admin permissions in HubSpot
• OAuth app creation capabilities

Step 1: Create HubSpot App

1.1 Access HubSpot App Dashboard

1. Log in to your HubSpot account
2. Navigate to Settings Integrations Private Apps
3. Click Create a private app

1.2 Configure App Settings

1. Basic Info:

   • Name: "AI Gateway Service Hub MCP"
   • Description: "MCP server for customer service automation"

2. Scopes:

   • Enable Service Hub specific scopes
   • Add ticket and conversation permissions
   • Include knowledge base access

1.3 Set OAuth Configuration

1. Redirect URLs:

   https://auth.aigateway.cequence.ai/v1/outbound/oauth/callback

2. Scopes: Select based on needs (see scopes section)

1.4 Get Credentials

1. Copy Client ID
2. Copy Client Secret
3. Note App ID

Step 2-4: Standard Setup

Follow standard steps to access AI Gateway, find HubSpot Service Hub API, and create MCP server.

Step 5: Configure API Endpoints

1. Base URL: https://api.hubapi.com
2. Select Service Hub endpoints:
   • Tickets endpoints
   • Conversations endpoints
   • Feedback endpoints
   • Knowledge base endpoints
3. Click Next

Step 6: MCP Server Configuration

1. Name: "HubSpot Service Hub"
2. Description: "Customer service and support automation"
3. Configure production mode
4. Click Next

Step 7: Configure Authentication

1. Authentication Type: OAuth 2.0
2. Authorization URL:

   https://app.hubspot.com/oauth/authorize

3. Token URL:

   https://api.hubapi.com/oauth/v1/token

4. Enter Client ID and Secret
5. Select required scopes

Available HubSpot Service Hub OAuth Scopes

Ticket Management

• tickets
  • Create and manage tickets
  • Update ticket properties
  • Access ticket pipelines
  • Handle ticket associations

Conversations & Communication

• conversations.read / conversations.write
  • Access chat conversations
  • Send messages
  • Manage chat sessions
  • View conversation history

Knowledge Base

• content
  • Manage knowledge articles
  • Create help content
  • Organize categories
  • Track article metrics

Feedback & Surveys

• crm.objects.feedback_submissions.read / crm.objects.feedback_submissions.write
  • Access survey responses
  • Create feedback forms
  • Analyze satisfaction data
  • Manage survey campaigns

Service Analytics

• reports
  • Access service reports
  • View performance metrics
  • Export analytics data
  • Create custom reports

Standard CRM Scopes

• crm.objects.contacts.read / crm.objects.contacts.write
  • Access customer information
  • Update contact records
  • View interaction history
  • Manage contact properties

Recommended Scope Combinations

For Help Desk Operations:

tickets
conversations.read
conversations.write
crm.objects.contacts.read
crm.objects.companies.read

For Full Service Hub:

tickets
conversations.read
conversations.write
content
crm.objects.feedback_submissions.read
crm.objects.feedback_submissions.write
crm.objects.contacts.read
crm.objects.contacts.write
crm.objects.companies.read
reports

Step 8-10: Complete Setup

Configure security, choose deployment, and deploy.

Using Your HubSpot Service Hub MCP Server

With Claude Desktop

{
  "servers": {
    "hubspot-service": {
      "url": "your-mcp-server-url",
      "auth": {
        "type": "oauth2",
        "client_id": "your-client-id"
      }
    }
  }
}

Natural Language Commands

• "Create support ticket for billing issue"
• "Show all high-priority open tickets"
• "Send CSAT survey to resolved tickets"
• "Find knowledge articles about password reset"
• "Calculate average response time this week"

API Integration Example

// Initialize MCP client
const mcpClient = new MCPClient({
  serverUrl: 'your-mcp-server-url',
  auth: {
    type: 'oauth2',
    token: 'access-token'
  }
});

// Create support ticket
const ticket = await mcpClient.hubspot.tickets.create({
  properties: {
    subject: 'Unable to access account',
    content: 'Customer reports login issues after password reset',
    priority: 'HIGH',
    category: 'Account_Access',
    source_type: 'EMAIL'
  },
  associations: [
    {
      to: { id: 'contact-id' },
      types: [{ associationTypeId: 16 }]
    }
  ]
});

// Add note to ticket
await mcpClient.hubspot.tickets.addNote({
  ticketId: ticket.id,
  note: {
    body: 'Verified account status - password reset link sent',
    type: 'NOTE'
  }
});

// Send chat message
const conversation = await mcpClient.hubspot.conversations.send({
  conversationId: 'conv-id',
  message: {
    text: 'Hi! I can help you with your account access issue.',
    type: 'MESSAGE',
    direction: 'OUTGOING'
  }
});

// Create knowledge article
const article = await mcpClient.hubspot.content.create({
  type: 'knowledge_article',
  properties: {
    title: 'How to Reset Your Password',
    body: '### Step-by-step password reset guide...',
    category: 'Account Management',
    tags: ['password', 'security', 'account'],
    visibility: 'PUBLIC'
  }
});

// Send feedback survey
const survey = await mcpClient.hubspot.feedback.send({
  surveyId: 'csat-survey-id',
  recipients: [{ email: 'customer@example.com' }],
  properties: {
    ticket_id: ticket.id,
    agent_id: 'agent-123'
  }
});

// Get service metrics
const metrics = await mcpClient.hubspot.reports.getServiceMetrics({
  dateRange: 'THIS_WEEK',
  metrics: [
    'average_response_time',
    'resolution_rate', 
    'customer_satisfaction',
    'ticket_volume'
  ],
  groupBy: 'agent'
});

// Set up SLA
const sla = await mcpClient.hubspot.tickets.configureSLA({
  name: 'Premium Support SLA',
  conditions: {
    priority: 'HIGH',
    customer_tier: 'PREMIUM'
  },
  targets: {
    first_response_time: 60, // minutes
    resolution_time: 240 // minutes
  }
});

Common Use Cases

Help Desk Operations

• Ticket triage and routing
• Response automation
• Escalation management
• Resolution tracking

Customer Self-Service

• Knowledge base creation
• FAQ management
• Help center optimization
• Search improvement

Quality Assurance

• Satisfaction surveys
• Performance monitoring
• Quality scoring
• Training identification

Process Automation

• Workflow creation
• SLA enforcement
• Follow-up scheduling
• Integration orchestration

Security Best Practices

1. OAuth Security:

   • Use minimal required scopes
   • Rotate credentials regularly
   • Monitor API usage
   • Implement IP restrictions

2. Data Protection:

   • Encrypt sensitive ticket data
   • Implement access controls
   • Audit agent activities
   • Mask customer information

3. Communication Security:

   • Verify sender identities
   • Scan attachments
   • Monitor for spam
   • Secure chat sessions

Troubleshooting

Common Issues

1. Ticket Creation Failures

   • Verify required properties
   • Check pipeline configuration
   • Validate associations
   • Review permissions

2. Chat Connection Issues

   • Check conversation status
   • Verify agent availability
   • Review chat settings
   • Monitor rate limits

3. Survey Delivery Problems

   • Validate email addresses
   • Check survey status
   • Review send limits
   • Verify template setup

Getting Help

• Documentation: AI Gateway Docs
• Support: support@cequence.ai
• HubSpot Service Hub Docs: developers.hubspot.com/docs/api/service

---