Skip to main content

Create a custom Zendesk MCP server

Create an MCP server and connect it to a Squid agent that interacts with your Zendesk instance​

What you'll build​

  • A simple agent that connects to a custom Squid MCP server to interact with Zendesk
  • Create tickets, update ticket status, and add comments to tickets

This tutorial uses the following features:

AI AbilitiesInternal Connectors
Model Context Protocol abilityModel Context Protocol server

What you'll learn​

  • How to create an MCP server and connect it to an agent using Squid's backend SDK

What you'll need​

Create a Squid app​

  1. Navigate to the Squid Console and create a new Squid application named Zendesk MCP Tutorial.
  2. On the application overview page, scroll to the Backend project section. Click Initialize Backend and copy the initialization command.
  3. Run the initialization command in your terminal in the desired location for your project.

Set up the Zendesk project​

Now that you have a starter Squid backend, you can customize it to create an MCP server that connects to Zendesk.

While there are multiple ways to interact with Zendesk, this tutorial will utilize the Node Zendesk API client to call the Zendesk API.

  1. Open the project in your IDE of choice. To install the client, run the following command in your terminal:
npm install node-zendesk

You will also need to update your tsconfig.json file to include the following settings:

{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "nodenext"
  }
}

  1. Rename the src/service/example-service.ts to zendesk-mcp.service.ts and update the class name to ZendeskMcpService.

  2. Update the src/service/index.ts file to export the new service:

export * from './zendesk-mcp.service.ts';
  1. Create a new directory named providers in the src directory. Inside the providers directory, create a new file named zendesk.provider.ts. This file will contain the logic to interact with the Zendesk API using the Node Zendesk client. It contains two basic functions: replyToTicket, which allows the AI agent to add comments and update the status of a ticket, and createTicket for creating tickets. In src/providers/zendesk.provider.ts, add the following code:
import { createClient, ZendeskClient } from 'node-zendesk';
import {
  CreateOrUpdateTicket,
  Status,
  Ticket,
  TicketComment,
} from 'node-zendesk/clients/core/tickets';

export class ZendeskProvider {
  private readonly zendeskClient: ZendeskClient;

  constructor(username: string, token: string, subdomain: string) {
    this.zendeskClient = createClient({ username, token, subdomain });
  }

  async replyToTicket(
    ticketId: number,
    replyText: string,
    isReplyToCustomer: boolean,
    reassignToEmail: string | undefined,
    status: Status | undefined,
  ): Promise<TicketComment | undefined> {
    const comment: Partial<TicketComment> = {
      html_body: replyText,
      public: isReplyToCustomer,
    };

    const response = await this.zendeskClient.tickets.update(ticketId, {
      ticket: { comment, status: status, assignee_email: reassignToEmail },
    });

    return response.result.comment;
  }

  async createTicket(
    subject: string,
    text: string,
    requesterId: number,
  ): Promise<Ticket | undefined> {
    const ticketData: CreateOrUpdateTicket = {
      ticket: {
        subject,
        description: text,
        requester_id: requesterId,
      },
    };

    const response = await this.zendeskClient.tickets.create(ticketData);
    return response.result;
  }
}

Additionally, to secure the MCP server, use the @mcpAuthorizer decorator to restrict access to authorized users only. Below the createTicket method, add the following code:

import { mcpAuthorizer } from '@squidcloud/backend';

export class ZendeskProvider {
  // existing code...

  @mcpAuthorizer()
  async authorizeMcp(request: McpAuthorizationRequest): Promise<boolean> {
    const authHeader = request.headers['authorization'];
    if (!authHeader) return false;

    const [scheme, token] = authHeader.split(' ');
    return scheme === 'Bearer' && token === 'some_secure_auth_value';
  }
}

  1. To use the Zendesk API, you need to provide a Zendesk API key. To create a Zendesk API key, follow the instructions in the Zendesk documentation. Then navigate to the Secrets page of the Squid Console in the left sidebar. Click Store New Secret and add the following value:

    • Secret key: ZENDESK_API_KEY
    • Value: Your Zendesk API key

    Add a second secret that contains the correct authorization value:

    • Secret key: MCP_AUTH_VALUE
    • Value: Bearer some_secure_auth_value (or any other secure value of your choice, but ensure it matches the value in the authorizeMcp method above)

  2. Create a new service file named base-zendesk.service.ts. This file will contain your base Zendesk provider initialized with the necessary credentials. In src/service/base-zendesk.service.ts, add the following code with your credentials.

import { SquidService } from '@squidcloud/backend';
import { ZendeskProvider } from '../providers/zendesk.provider';

export class BaseZendeskService extends SquidService {
  protected readonly zendeskProvider = new ZendeskProvider(
    'YOUR_ZENDESK_EMAIL',
    this.secrets['ZENDESK_API_KEY'] as string,
    'YOUR_ZENDESK_SUBDOMAIN', // e.g. 'mycompany' if your Zendesk URL is 'mycompany.zendesk.com'
  );
}

After following these steps, you now have all the necessary components to create your custom Zendesk MCP server.

Create the Squid + Zendesk MCP server​

  1. Open the zendesk-mcp.service.ts file and add the following code to create an MCP server with tools to create tickets and reply to tickets. By using the @mcpServer decorator, you create an MCP server that can be used by your AI agents.
import { mcpServer, mcpTool } from '@squidcloud/backend';
import { BaseZendeskService } from './base-zendesk.service';

@mcpServer({
  name: 'zendesk-mcp',
  id: 'zendesk-mcp',
  description: 'This MCP knows how to communicate with Zendesk',
  version: '1.0.0'
})
export class ZendeskMcpService extends BaseZendeskService {
  
}
  1. The @mcpTool decorator defines the specific actions the AI agent can perform. The first tool to add will create Zendesk tickets. Add the following code inside the ZendeskMcpService class:
export class ZendeskMcpService extends BaseZendeskService {
  @mcpTool({
    description: 'This tool creates a Zendesk ticket',
    inputSchema: {
      type: 'object',
      properties: {
        title: {
          type: 'string',
          description: 'The title of the ticket to create',
        },
        text: {
          type: 'string',
          description: 'The text of the ticket to create',
        },
        userId: {
          type: 'number',
          description: 'The user ID who is requesting to create the ticket',
        }
      },
      required: ['title', 'text', 'userId'],
    },
  })
  async createTicket({ title, text, userId }) {
    return await this.zendeskProvider.createTicket(title, text, userId);
  }
}
  1. Create one more tool that can reply to tickets and update their status:
export class ZendeskMcpService extends BaseZendeskService {
  @mcpTool({
    description: 'This tool replies to a Zendesk ticket',
    inputSchema: {
      type: 'object',
      properties: {
        ticketId: {
          type: 'number',
          description: 'The ID of the ticket to reply to',
        },
        replyText: {
          type: 'string',
          description: 'The text of the reply to the ticket',
        },
        isReplyToCustomer: {
          type: 'boolean',
          description: 'Whether the reply is public (to customer) or private (internal note)',
        },
        status: {
          type: 'string',
          enum: ['new', 'open', 'pending', 'hold', 'solved', 'closed'],
          description: 'The status to set the ticket to',
        },
      },
      required: ['ticketId', 'replyText', 'isReplyToCustomer'],
    },
  })
  async replyToTicket({ ticketId, replyText, isReplyToCustomer, status }) {
    try {
      await this.zendeskProvider.replyToTicket(ticketId, replyText, isReplyToCustomer, undefined, status);
      return { success: true };
    } catch (error) {
      throw new Error(error);
    }
  }
}

Connect an AI agent to the MCP server​

Now that you have created your custom Zendesk MCP server, you can connect an AI agent to it.

In order to expose the server to your AI agent, you need to deploy your backend.

  1. To do this, stop the local backend by pressing CTRL + C in the terminal where it is running, and then run the following command:
squid deploy

  1. Next, navigate to the Connectors tab in the Squid Console and click Available Connectors. Find the MCP connector and click Add Connector.

  2. Provide the following connector details:

    • Connector ID: A unique ID of your choice. It is best to keep it brief and meaningful, such as zendesk-mcp.
    • MCP URL: The MCP endpoint URL provided by your deployed backend. To find your MCP URL, navigate to the Backend tab in the console and locate the MCP URL under MCP Servers.

    Next, toggle on Authorization and provide the following details:

    • Authorization Header: Authorization
    • Authorization Value: The MCP_AUTH_VALUE secret you created earlier

  3. Click Test Connection to test your connection to the server. If the connection fails, verify the value of your MCP URL. Once the connection is successful, click Add Connector.


Now that you have added the MCP connector, it is time to create an AI agent that uses it.

  1. Navigate to the Agent Studio tab in the Squid Console and click Create New Agent.
  2. Provide the following details:
    • Agent ID: A name for the agent, such as Zendesk Agent.
    • Agent Description: A description, such as An agent that can create and reply to Zendesk tickets. Click Create.
  3. In the agent Overview tab, click on Add Abilities and select the MCP ability. This will open a dropdown that contains the zendesk-mcp connector you created earlier. Select it and click Add Connector. You will then be able to provide specific instructions on when the agent should invoke this MCP server. Add the following instructions:
Use this MCP server when prompted to interact with Zendesk

Your agent is now ready to use the Zendesk MCP server!

Test the agent​

To test the agent, navigate to the Test Agent tab in the Agent Studio. You can interact with your agent by asking it to create and reply to tickets. Here are some example prompts you can use:

Create a ticket with the following details - 
Title: 'Bug report'
Text: 'User reported login feature is not currently working'
User ID: (Your User ID. Can be found by navigating to your profile in Zendesk and copying the ID value from the URL)
Update ticket ID (the ID of the ticket created in the previous step) to reply to the customer with the following details -
Text: 'The login issue has been resolved. Please try again.'
Status: solved

Next steps​

Congratulations on creating your custom Zendesk MCP server and connecting it to an AI agent! You can now expand on this foundation by adding more tools to your MCP server or enhancing your AI agent's capabilities.