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 creation and 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"
  • "Archive completed tickets"
  • "Get ticket details with all properties"

• Batch Ticket Operations

  • "Create 50 tickets from CSV import"
  • "Bulk create tickets for maintenance notification"
  • "Mass create tickets from feedback forms"

• 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"
  • "Filter tickets by date range"
  • "Find tickets with specific properties"

• Ticket Associations

  • "Link ticket to customer contact"
  • "Associate ticket with company account"
  • "Connect ticket to related deal"
  • "Associate tickets with each other"
  • "Remove ticket association from contact"
  • "Link ticket to custom CRM objects"

• Pipeline & Property Management

  • "Get all ticket pipeline stages"
  • "View available ticket properties"
  • "List custom ticket fields"
  • "Show pipeline configuration"

Customer Communication

• Response Management

  • "Send initial response to ticket"
  • "Add internal note to ticket"
  • "Request more information from customer"
  • "Send resolution confirmation"
  • "Send message with rich text formatting"
  • "Add formatted HTML response"

• Conversation Thread Management

  • "List all active conversation threads"
  • "Get conversations by inbox"
  • "Filter conversations by assigned agent"
  • "Update conversation status"
  • "Assign conversation to team member"
  • "Change conversation to waiting on customer"
  • "Mark conversation as closed"

• Message Operations

  • "Send message to conversation thread"
  • "Add note to conversation (internal only)"
  • "Log call details to conversation"
  • "Create task from conversation"
  • "Get all messages in a thread"
  • "Send email through conversation"

• Message Attachments

  • "Attach file to customer response"
  • "Send document link in message"
  • "Share knowledge article link"
  • "Include multiple attachments"

• 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 & Management

  • "Create troubleshooting guide"
  • "Add FAQ article"
  • "Update product documentation"
  • "Publish release notes"
  • "Get specific article by ID"
  • "Update article content and title"
  • "Archive outdated articles"
  • "Create draft article for review"

• Content Organization

  • "Organize articles by category"
  • "Tag articles with keywords"
  • "Set article visibility"
  • "Create article templates"
  • "List all published articles"
  • "Show archived articles"
  • "Filter articles by state"
  • "Set article language"

• Article Analytics

  • "Show most viewed articles"
  • "Track article helpfulness"
  • "Find articles needing updates"
  • "Monitor search queries"
  • "View article view count"
  • "Check helpful vs not helpful ratings"

Customer Feedback

• Survey Management

  • "Send CSAT survey after ticket closure"
  • "Create NPS survey campaign"
  • "Design custom feedback form"
  • "Schedule survey distribution"
  • "Submit customer satisfaction score"
  • "Create feedback submission with comments"

• Feedback Data Management

  • "List all feedback submissions"
  • "Get specific feedback by ID"
  • "Update feedback submission details"
  • "Archive old feedback entries"
  • "Filter feedback by properties"
  • "View feedback with associations"

• Feedback Analysis

  • "Show average satisfaction score"
  • "Analyze feedback trends"
  • "Identify unhappy customers"
  • "Track agent performance"
  • "Filter NPS promoters and detractors"
  • "View feedback sentiment (positive/negative/neutral)"
  • "Get CES survey responses"
  • "Analyze custom survey results"

• Response Actions

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

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"

Advanced Query Capabilities

• Pagination & Data Retrieval

  • "Get next page of tickets with cursor"
  • "Limit results to 50 items per page"
  • "Retrieve all tickets with pagination"
  • "Navigate through large datasets"

• Property & Association Selection

  • "Get tickets with specific properties only"
  • "Include contact associations with tickets"
  • "Fetch tickets with company data"
  • "Request custom properties in response"
  • "Include multiple associations at once"

• Filtering & Sorting

  • "Sort tickets by creation date descending"
  • "Filter archived vs active records"
  • "Query with multiple filter conditions"
  • "Combine filters with AND/OR logic"
  • "Apply date range filters"

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:

"content",
"conversations",
"conversations.read",
"conversations.write",
"crm.objects.contacts.read",
"crm.objects.feedback_submissions.read",
"crm.objects.feedback_submissions.write",
"crm.schemas.contacts.read",
"oauth",
"tickets"

Step 8-10: Complete Setup

Configure security, choose deployment, and deploy.

Using Your HubSpot Service Hub MCP Server

Setup Instructions:

• Claude Desktop
• Cursor
• Windsurf

Natural Language Commands

Ticket Operations:

• "Create support ticket for billing issue"
• "Show all high-priority open tickets"
• "Associate ticket #123 with contact John Smith"
• "Get all ticket properties and custom fields"
• "Bulk create 20 tickets from this list"
• "Search tickets by priority and date range"

Conversation Management:

• "List all open conversation threads in support inbox"
• "Assign conversation to agent Sarah"
• "Send message with attachment to thread #456"
• "Update conversation status to waiting on customer"
• "Get all messages in conversation #789"

Feedback & Surveys:

• "Create NPS feedback submission with score 9"
• "List all feedback submissions from last month"
• "Show feedback with negative sentiment"
• "Get feedback response for contact ID 12345"

Knowledge Base:

• "Create knowledge article about password reset"
• "Update article #101 with new content"
• "Archive outdated articles"
• "List all published articles in English"
• "Show article view counts and ratings"

Analytics & Reporting:

• "Calculate average response time this week"
• "Show ticket volume by category"
• "Find all tickets associated with company ABC Corp"

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

---