Zendesk Platform MCP Server

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

About Zendesk Platform APIs

Zendesk Platform APIs provide the foundation for extending and customizing Zendesk to meet unique business needs. These APIs enable custom objects, apps framework integration, custom fields, and advanced data management capabilities.

Key Capabilities

• Custom Objects: Extend data model
• Apps Framework: Build custom apps
• Custom Fields: Flexible data capture
• Relationships: Link data entities
• Sunshine Platform: Custom data and events
• APIs & Webhooks: Integration endpoints
• Admin Settings: Configuration management
• Security: Authentication and permissions

API Features

• Custom Objects API: Data model extension
• Apps API: App management and configuration
• OAuth 2.0: Secure authentication
• Webhooks: Event notifications
• Sunshine API: Custom data platform
• Admin API: Settings and configuration
• Target API: Integration endpoints
• Job Status API: Async operations

What You Can Do with Zendesk Platform MCP Server

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

Custom Objects

• Object Creation

  • "Create product catalog object"
  • "Build inventory tracking"
  • "Design contract management"
  • "Set up asset registry"

• Schema Definition

  • "Add SKU field to products"
  • "Create relationship to tickets"
  • "Define validation rules"
  • "Set field permissions"

• Data Management

  • "Import product records"
  • "Update inventory levels"
  • "Link contracts to accounts"
  • "Query custom objects"

Apps Framework

• App Management

  • "Install marketplace app"
  • "Configure app settings"
  • "Update app permissions"
  • "Enable app for agents"

• Custom Apps

  • "Create sidebar app"
  • "Build ticket app"
  • "Design nav bar app"
  • "Deploy background app"

• App Configuration

  • "Set secure settings"
  • "Configure parameters"
  • "Manage installations"
  • "Control visibility"

Sunshine Platform

• Custom Data

  • "Store customer preferences"
  • "Track interaction history"
  • "Manage external IDs"
  • "Sync third-party data"

• Events & Profiles

  • "Track custom events"
  • "Build user profiles"
  • "Create segments"
  • "Monitor behaviors"

• Relationships

  • "Link custom objects"
  • "Create associations"
  • "Map hierarchies"
  • "Define cardinality"

Custom Fields

• Field Creation

  • "Add account number field"
  • "Create priority matrix"
  • "Build product selector"
  • "Design date range picker"

• Field Types

  • "Configure dropdown"
  • "Create multi-select"
  • "Add regex validation"
  • "Build lookup field"

• Field Management

  • "Set field dependencies"
  • "Configure visibility"
  • "Apply to forms"
  • "Control permissions"

Integration Management

• Webhook Configuration

  • "Create ticket webhook"
  • "Set up user sync"
  • "Configure event triggers"
  • "Build custom notifications"

• Target Setup

  • "Add HTTP target"
  • "Configure email target"
  • "Set URL parameters"
  • "Test target endpoint"

• API Tokens

  • "Generate API token"
  • "Set token permissions"
  • "Configure expiration"
  • "Monitor usage"

Admin Configuration

• Account Settings

  • "Update company profile"
  • "Configure branding"
  • "Set security policies"
  • "Manage domains"

• User Management

  • "Create custom roles"
  • "Set permissions"
  • "Configure groups"
  • "Manage licenses"

• Business Rules

  • "Create SLA policies"
  • "Configure schedules"
  • "Set up holidays"
  • "Define workflows"

Data & Analytics

• Custom Metrics

  • "Track object usage"
  • "Monitor app performance"
  • "Measure API calls"
  • "Analyze patterns"

• Reporting

  • "Create custom reports"
  • "Build dashboards"
  • "Export analytics"
  • "Schedule reports"

• Data Export

  • "Export custom objects"
  • "Backup configurations"
  • "Archive data"
  • "Sync to warehouse"

Security & Compliance

• Access Control

  • "Set object permissions"
  • "Configure field access"
  • "Manage API scopes"
  • "Control app permissions"

• Audit Logging

  • "Track configuration changes"
  • "Monitor data access"
  • "Log API usage"
  • "Review permissions"

• Data Governance

  • "Implement retention"
  • "Configure encryption"
  • "Set compliance rules"
  • "Manage privacy"

Prerequisites

• Access to Cequence AI Gateway
• Zendesk Enterprise or above
• Platform admin permissions
• OAuth application credentials

Step 1: Create Zendesk OAuth Application

1.1 Access Admin Center

1. Log in to Zendesk
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 Platform MCP"
   • Company: Your company name
   • Description: "Platform API integration"
   • Redirect URLs:

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

1.3 Configure Permissions

1. Set client type to Confidential
2. Select platform scopes:
   • apps:read - Read app data
   • apps:write - Manage apps
   • custom_objects:read - Read custom objects
   • custom_objects:write - Manage custom objects

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 Platform APIs, and create MCP server.

Step 5: Configure API Endpoints

1. Base URL: https://{subdomain}.zendesk.com/api/v2
2. Sunshine API: https://{subdomain}.zendesk.com/api/sunshine
3. Select endpoints:
   • Custom Objects endpoints
   • Apps endpoints
   • Admin endpoints
4. Click Next

Step 6: MCP Server Configuration

1. Name: "Zendesk Platform"
2. Description: "Platform APIs and customization"
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 Platform OAuth Scopes

Platform Scopes

• apps:read

  • View installed apps
  • Read app settings
  • Access app data
  • See configurations

• apps:write

  • Install apps
  • Update settings
  • Manage permissions
  • Configure apps

Custom Objects Scopes

• custom_objects:read

  • View object schemas
  • Read object records
  • Access relationships
  • Query data

• custom_objects:write

  • Create objects
  • Update schemas
  • Manage records
  • Define relationships

Recommended Scope Combinations

For Platform Development:

apps:read
apps:write
custom_objects:read
custom_objects:write
read
write

For Data Management:

custom_objects:read
custom_objects:write
users:read
organizations:read

Step 8-10: Complete Setup

Configure security, choose deployment, and deploy.

Using Your Zendesk Platform MCP Server

With Claude Desktop

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

Natural Language Commands

• "Create product inventory custom object"
• "Add serial number field to assets"
• "Install and configure Slack app"
• "Create webhook for order updates"
• "Build custom report for contracts"

API Integration Example

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

// Create custom object schema
const customObject = await mcpClient.zendesk.platform.customObjects.create({
  data: {
    key: 'product_inventory',
    schema: {
      name: 'Product Inventory',
      properties: {
        sku: {
          type: 'string',
          description: 'Product SKU',
          required: true
        },
        name: {
          type: 'string',
          description: 'Product name'
        },
        quantity: {
          type: 'integer',
          description: 'Available quantity',
          default: 0
        },
        price: {
          type: 'number',
          description: 'Unit price'
        },
        category: {
          type: 'string',
          enum: ['Electronics', 'Clothing', 'Home', 'Sports']
        },
        last_updated: {
          type: 'string',
          format: 'date-time'
        }
      },
      required: ['sku', 'name']
    }
  }
});

// Create relationship to tickets
const relationship = await mcpClient.zendesk.platform.relationships.create({
  data: {
    key: 'ticket_products',
    source: 'zen:ticket',
    target: customObject.data.key,
    cardinality: 'many_to_many'
  }
});

// Create custom object record
const product = await mcpClient.zendesk.platform.customObjects.records.create({
  type: 'product_inventory',
  data: {
    attributes: {
      sku: 'PROD-12345',
      name: 'Wireless Headphones',
      quantity: 150,
      price: 79.99,
      category: 'Electronics',
      last_updated: new Date().toISOString()
    }
  }
});

// Install and configure app
const app = await mcpClient.zendesk.platform.apps.install({
  app_id: '123456', // Marketplace app ID
  settings: {
    name: 'Custom CRM Integration',
    configuration: {
      api_key: 'your-crm-api-key',
      sync_interval: 300,
      field_mappings: {
        account_id: 'crm_account_number',
        contact_email: 'primary_email'
      }
    },
    enabled: true,
    restricted: false
  }
});

// Create custom ticket field
const customField = await mcpClient.zendesk.platform.ticketFields.create({
  ticket_field: {
    type: 'tagger',
    title: 'Product Category',
    description: 'Select the product category',
    position: 1,
    active: true,
    required: false,
    custom_field_options: [
      { name: 'Hardware', value: 'hw' },
      { name: 'Software', value: 'sw' },
      { name: 'Service', value: 'svc' },
      { name: 'Accessory', value: 'acc' }
    ],
    visible_in_portal: true,
    editable_in_portal: false
  }
});

// Create webhook
const webhook = await mcpClient.zendesk.platform.webhooks.create({
  webhook: {
    name: 'Order Status Updates',
    status: 'active',
    endpoint: 'https://api.example.com/webhooks/zendesk',
    http_method: 'POST',
    request_format: 'json',
    subscriptions: [
      'zen:event-type:ticket.created',
      'zen:event-type:ticket.updated',
      'zen:event-type:ticket.solved'
    ],
    authentication: {
      type: 'bearer_token',
      data: {
        token: 'webhook-secret-token'
      }
    },
    custom_headers: {
      'X-Source': 'Zendesk',
      'X-Environment': 'Production'
    }
  }
});

// Create target
const target = await mcpClient.zendesk.platform.targets.create({
  target: {
    type: 'http_target',
    title: 'External API Integration',
    target_url: 'https://api.external.com/zendesk',
    method: 'post',
    username: 'api-user',
    password: 'api-password',
    content_type: 'json'
  }
});

// Configure Sunshine event
const sunshineEvent = await mcpClient.zendesk.platform.sunshine.events.create({
  event: {
    type: 'purchase_completed',
    source: 'ecommerce',
    description: 'Customer completed purchase',
    properties: {
      order_id: { type: 'string' },
      total_amount: { type: 'number' },
      items_count: { type: 'integer' },
      payment_method: { type: 'string' },
      timestamp: { type: 'string', format: 'date-time' }
    }
  }
});

// Track custom event
await mcpClient.zendesk.platform.sunshine.events.track({
  profile: {
    type: 'customer',
    id: 'cust_12345'
  },
  event: {
    type: 'purchase_completed',
    properties: {
      order_id: 'ORD-98765',
      total_amount: 299.99,
      items_count: 3,
      payment_method: 'credit_card',
      timestamp: new Date().toISOString()
    }
  }
});

// Create custom role
const customRole = await mcpClient.zendesk.platform.customRoles.create({
  custom_role: {
    name: 'Product Manager',
    description: 'Manages product catalog and inventory',
    configuration: {
      ticket_access: 'within_groups',
      ticket_commenting: true,
      ticket_tag_editing: true,
      forum_access_restricted_content: false,
      view_access: 'playonly',
      custom_objects: {
        product_inventory: {
          read: true,
          create: true,
          update: true,
          delete: true
        }
      }
    }
  }
});

// Query custom objects
const products = await mcpClient.zendesk.platform.customObjects.records.search({
  type: 'product_inventory',
  query: {
    filter: {
      category: 'Electronics',
      quantity: { $gt: 0 }
    },
    sort: '-price',
    limit: 10
  }
});

// Create job for bulk operation
const bulkJob = await mcpClient.zendesk.platform.jobs.create({
  job: {
    action: 'update',
    items: products.data.map(p => ({
      type: 'product_inventory',
      id: p.id,
      attributes: {
        quantity: p.attributes.quantity - 1,
        last_updated: new Date().toISOString()
      }
    }))
  }
});

// Monitor job status
const jobStatus = await mcpClient.zendesk.platform.jobs.show({
  id: bulkJob.job.id
});

Common Use Cases

Data Extension

• Custom objects for products
• Asset management
• Contract tracking
• Project management

App Development

• Custom integrations
• Workflow automation
• UI extensions
• Data synchronization

Business Logic

• Complex workflows
• Custom validation
• Automated processes
• Advanced routing

Integration Hub

• External system sync
• Webhook orchestration
• API gateway
• Event streaming

Security Best Practices

1. API Security:

   • Use minimal scopes
   • Rotate API tokens
   • Implement rate limiting
   • Monitor API usage

2. Data Protection:

   • Encrypt sensitive data
   • Implement field-level security
   • Audit data access
   • Control permissions

3. App Security:

   • Review app permissions
   • Validate app sources
   • Monitor app behavior
   • Control installations

Troubleshooting

Common Issues

1. Schema Errors

   • Validate JSON schema
   • Check field types
   • Review relationships
   • Test with sample data

2. Permission Issues

   • Verify OAuth scopes
   • Check role permissions
   • Review object access
   • Test with admin account

3. Integration Failures

   • Check webhook URLs
   • Validate authentication
   • Review error logs
   • Test endpoints

Getting Help

• Documentation: AI Gateway Docs
• Support: support@cequence.ai
• Zendesk API: developer.zendesk.com/api-reference

---