Skip to main content

Zendesk Guide MCP Server

Create a powerful Model Context Protocol (MCP) server for Zendesk Guide in minutes with our AI Gateway. This guide walks you through setting up seamless knowledge base integration with enterprise-grade security and instant OAuth authentication.

About Zendesk Guide API​

Zendesk Guide is a smart knowledge base that helps you create and curate help content. The API provides comprehensive access to articles, sections, categories, and user permissions, enabling you to build, manage, and optimize your help center programmatically.

Key Capabilities​

  • Article Management: Create, edit, and organize help articles
  • Content Structure: Categories, sections, and articles hierarchy
  • Multi-language: Support for localized content
  • User Permissions: Granular access control
  • Search Integration: Powerful content discovery
  • Community Features: User contributions and voting
  • Content Analytics: Article performance metrics
  • Theme Customization: Help center branding

API Features​

  • REST API: Help Center API endpoints
  • OAuth 2.0: Secure authentication
  • Content Versioning: Article history
  • Bulk Operations: Mass content updates
  • Translation Management: Multi-locale support
  • Publishing Workflow: Draft and review
  • Media Management: Image and file handling
  • SEO Optimization: Meta tags and URLs

What You Can Do with Zendesk Guide MCP Server​

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

Article Management​

  • Article Creation

    • "Create troubleshooting guide for login issues"
    • "Write FAQ about billing"
    • "Draft product documentation"
    • "Build getting started guide"

  • Content Updates

    • "Update software version in docs"
    • "Revise pricing information"
    • "Add new feature documentation"
    • "Fix broken links in articles"

  • Article Organization

    • "Move article to different section"
    • "Reorganize help center structure"
    • "Create new category for APIs"
    • "Archive outdated content"

Multi-language Support​

  • Translation Management

    • "Translate article to Spanish"
    • "Create French version of FAQ"
    • "Update German documentation"
    • "Sync translations"

  • Locale Configuration

    • "Enable Japanese locale"
    • "Set default language"
    • "Configure locale fallbacks"
    • "Manage translation workflow"

  • Content Localization

    • "Adapt content for region"
    • "Localize screenshots"
    • "Update currency examples"
    • "Adjust date formats"

Content Organization​

  • Category Management

    • "Create product documentation category"
    • "Set category permissions"
    • "Reorder categories"
    • "Configure category visibility"

  • Section Structure

    • "Add troubleshooting section"
    • "Create API reference section"
    • "Organize by user type"
    • "Build nested sections"

  • Content Hierarchy

    • "Design information architecture"
    • "Create logical groupings"
    • "Implement navigation structure"
    • "Optimize content discovery"

Search & Discovery​

  • Search Configuration

    • "Configure search weights"
    • "Set up search synonyms"
    • "Create search labels"
    • "Optimize search results"

  • Content Labels

    • "Add topic labels"
    • "Tag by product version"
    • "Create audience labels"
    • "Implement label hierarchy"

  • SEO Optimization

    • "Update meta descriptions"
    • "Configure URL slugs"
    • "Set canonical URLs"
    • "Optimize page titles"

User Contributions​

  • Community Content

    • "Enable article comments"
    • "Moderate user posts"
    • "Approve contributions"
    • "Manage community guidelines"

  • Voting System

    • "Enable article voting"
    • "Track helpful votes"
    • "Sort by popularity"
    • "Identify top content"

  • User Permissions

    • "Grant editor access"
    • "Set contributor rights"
    • "Manage moderators"
    • "Configure view permissions"

Analytics & Insights​

  • Article Performance

    • "Show most viewed articles"
    • "Track search queries"
    • "Analyze vote patterns"
    • "Monitor engagement"

  • Content Gaps

    • "Identify missing topics"
    • "Find failed searches"
    • "Analyze support tickets"
    • "Discover content needs"

  • User Behavior

    • "Track navigation paths"
    • "Measure time on page"
    • "Monitor bounce rates"
    • "Analyze search behavior"

Theme & Branding​

  • Theme Customization

    • "Update help center theme"
    • "Configure brand colors"
    • "Upload company logo"
    • "Customize CSS"

  • Layout Configuration

    • "Design homepage layout"
    • "Configure navigation menu"
    • "Set up footer links"
    • "Create custom pages"

  • Widget Integration

    • "Add search widget"
    • "Embed contact form"
    • "Include chat widget"
    • "Configure feedback tools"

Publishing Workflow​

  • Draft Management

    • "Create article draft"
    • "Review pending changes"
    • "Schedule publication"
    • "Set expiration dates"

  • Approval Process

    • "Submit for review"
    • "Approve article changes"
    • "Request edits"
    • "Track review status"

  • Version Control

    • "View article history"
    • "Compare versions"
    • "Restore previous version"
    • "Track changes"

Prerequisites​

  • Access to Cequence AI Gateway
  • Zendesk Guide subscription
  • Admin or Agent permissions
  • OAuth application credentials

Step 1: Create Zendesk OAuth Application​

1.1 Access Admin Center​

  1. Log in to Zendesk Support
  2. Go to Admin Center > Apps and integrations
  3. Select APIs > Zendesk API
  4. Click OAuth Clients tab

1.2 Create OAuth Client​

  1. Click Add OAuth Client
  2. Fill in details:
    • Client Name: "AI Gateway Guide MCP"
    • Company: Your company name
    • Description: "Knowledge base management"
    • Redirect URLs: 
      https://auth.aigateway.cequence.ai/v1/outbound/oauth/callback

1.3 Configure Permissions​

  1. Set client type to Confidential
  2. Select Guide-specific scopes:
    • hc:read - Read help center content
    • hc:write - Manage help center content

1.4 Save Credentials​

  1. Click Save
  2. Copy Client ID
  3. Copy Client Secret
  4. Note your Subdomain

Step 2-4: Standard Setup​

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

Step 5: Configure API Endpoints​

  1. Base URL: https://{subdomain}.zendesk.com/api/v2/help_center
  2. Select endpoints:
    • Articles endpoints
    • Categories endpoints
    • Sections endpoints
    • Translations endpoints
  3. Click Next

Step 6: MCP Server Configuration​

  1. Name: "Zendesk Guide"
  2. Description: "Knowledge base and help center"
  3. Configure production mode
  4. Click Next

Step 7: Configure Authentication​

  1. Authentication Type: OAuth 2.0
  2. Authorization URL: 
    https://{subdomain}.zendesk.com/oauth/authorizations/new
  3. Token URL: 
    https://{subdomain}.zendesk.com/oauth/tokens
  4. Enter Client ID and Secret
  5. Select required scopes

Available Zendesk Guide OAuth Scopes​

Help Center Scopes​

  • hc:read

    • View articles
    • Read categories
    • Access sections
    • See translations

  • hc:write

    • Create articles
    • Update content
    • Manage structure
    • Publish changes

Additional Permissions​

  • Theme Access

    • Customize appearance
    • Update templates
    • Manage assets
    • Configure settings

  • Community Features

    • Moderate content
    • Manage users
    • Configure voting
    • Handle contributions

For Content Editors:

hc:read
hc:write

For Administrators:

hc:read
hc:write
read
write

Step 8-10: Complete Setup​

Configure security, choose deployment, and deploy.

Using Your Zendesk Guide MCP Server​

With Claude Desktop​

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

Natural Language Commands​

  • "Create troubleshooting article for password reset"
  • "Translate getting started guide to Spanish"
  • "Show most popular articles this month"
  • "Update API documentation with new endpoints"
  • "Organize articles by product category"

API Integration Example​

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

// Create a help article
const article = await mcpClient.zendesk.guide.articles.create({
  article: {
    title: 'How to Reset Your Password',
    body: `
      <h2>Password Reset Instructions</h2>
      <p>Follow these steps to reset your password:</p>
      <ol>
        <li>Go to the login page</li>
        <li>Click "Forgot Password"</li>
        <li>Enter your email address</li>
        <li>Check your email for reset link</li>
        <li>Create a new password</li>
      </ol>
      <p>Need more help? <a href="/hc/requests/new">Contact Support</a></p>
    `,
    locale: 'en-us',
    user_segment_id: null,
    permission_group_id: publicPermissionGroupId,
    author_id: currentUserId,
    comments_disabled: false,
    promoted: true,
    position: 1,
    label_names: ['password', 'account', 'security'],
    draft: false
  },
  section_id: troubleshootingSectionId
});

// Create article translation
const translation = await mcpClient.zendesk.guide.translations.create({
  article_id: article.article.id,
  translation: {
    locale: 'es',
    title: 'Cmo Restablecer tu Contrasea',
    body: `
      <h2>Instrucciones para Restablecer Contrasea</h2>
      <p>Sigue estos pasos para restablecer tu contrasea:</p>
      <ol>
        <li>Ve a la pgina de inicio de sesin</li>
        <li>Haz clic en "Olvidmi Contrasea"</li>
        <li>Ingresa tu direccin de correo electrnico</li>
        <li>Revisa tu correo para el enlace de restablecimiento</li>
        <li>Crea una nueva contrasea</li>
      </ol>
    `,
    draft: false
  }
});

// Create category structure
const category = await mcpClient.zendesk.guide.categories.create({
  category: {
    name: 'Product Documentation',
    description: 'Technical documentation for all products',
    locale: 'en-us',
    position: 1
  }
});

// Create section within category
const section = await mcpClient.zendesk.guide.sections.create({
  section: {
    name: 'API Reference',
    description: 'Complete API documentation',
    locale: 'en-us',
    category_id: category.category.id,
    position: 1,
    sorting: 'manual',
    parent_section_id: null
  }
});

// Search articles
const searchResults = await mcpClient.zendesk.guide.search({
  query: 'password reset',
  locale: 'en-us',
  per_page: 10,
  label_names: ['security']
});

// Update article with SEO metadata
await mcpClient.zendesk.guide.articles.update({
  article_id: article.article.id,
  article: {
    title: 'Password Reset Guide - Complete Instructions',
    meta_description: 'Learn how to reset your password quickly and securely with our step-by-step guide.',
    meta_keywords: 'password reset, forgot password, account recovery, security',
    search_keywords: 'reset password forgot login access account',
    promoted: true
  }
});

// Configure article permissions
await mcpClient.zendesk.guide.articles.updatePermissions({
  article_id: article.article.id,
  permission_group_id: registeredUsersGroupId,
  user_segment_ids: [premiumUsersSegmentId]
});

// Get article analytics
const analytics = await mcpClient.zendesk.guide.articles.analytics({
  article_id: article.article.id,
  start_date: '2025-01-01',
  end_date: '2025-01-31'
});

console.log(`Views: ${analytics.view_count}`);
console.log(`Votes: ${analytics.vote_sum}`);
console.log(`Comments: ${analytics.comment_count}`);

// Create article with attachments
const articleWithImages = await mcpClient.zendesk.guide.articles.create({
  article: {
    title: 'Visual Setup Guide',
    body: `
      <h2>Installation Steps</h2>
      <p>Follow these visual instructions:</p>
      <img src="{{article.attachments[0].content_url}}" alt="Step 1">
      <p>Step 1: Download the installer</p>
      <img src="{{article.attachments[1].content_url}}" alt="Step 2">
      <p>Step 2: Run the installation</p>
    `,
    attachments: [
      { file_name: 'step1.png', content_type: 'image/png', inline: true },
      { file_name: 'step2.png', content_type: 'image/png', inline: true }
    ]
  },
  section_id: gettingStartedSectionId
});

// Enable voting and comments
await mcpClient.zendesk.guide.articles.updateSettings({
  article_id: article.article.id,
  settings: {
    comments_disabled: false,
    votes_disabled: false,
    reactions_disabled: false,
    followups_disabled: false,
    content_tag_ids: [videoTagId, tutorialTagId]
  }
});

// Create custom page
const customPage = await mcpClient.zendesk.guide.pages.create({
  page: {
    title: 'Developer Portal',
    body: '<h1>Welcome to our Developer Portal</h1>',
    promoted: true,
    position: 1
  }
});

// Schedule article publication
await mcpClient.zendesk.guide.articles.schedule({
  article_id: draftArticle.id,
  publish_at: '2025-02-01T09:00:00Z',
  notification_users: [editorId, managerId]
});

Common Use Cases​

Knowledge Base Creation​

  • Product documentation
  • User guides
  • API references
  • Troubleshooting articles

Multi-language Support​

  • Global help centers
  • Localized content
  • Regional variations
  • Translation management

Self-Service Portal​

  • FAQ sections
  • How-to guides
  • Video tutorials
  • Community forums

Content Management​

  • Publishing workflows
  • Version control
  • Content updates
  • Archive management

Security Best Practices​

  1. Access Control:

    • Implement role-based permissions
    • Use permission groups
    • Configure user segments
    • Audit content access

  2. Content Security:

    • Sanitize HTML input
    • Validate attachments
    • Monitor external links
    • Implement content moderation

  3. API Security:

    • Use minimal OAuth scopes
    • Rotate credentials
    • Monitor API usage
    • Implement rate limiting

Troubleshooting​

Common Issues​

  1. Content Errors

    • Validate HTML structure
    • Check character encoding
    • Verify locale settings
    • Test translations

  2. Permission Issues

    • Review user roles
    • Check group permissions
    • Verify segment configuration
    • Test access levels

  3. Search Problems

    • Index new content
    • Configure search weights
    • Update search labels
    • Clear search cache

Getting Help​