メインコンテンツまでスキップ

Custom Zendesk MCP Server を作成する

MCP server を作成し、Zendesk instance と interaction する Squid agent に接続します​

構築するもの​

  • Zendesk と interaction する custom Squid MCP server に接続する simple agent
  • ticket の作成、ticket status の update、ticket への comment の追加

この tutorial では次の feature を使用します。

AI AbilityInternal Connector
Model Context Protocol abilityModel Context Protocol server

学ぶこと​

  • Squid backend SDK を使用して MCP server を作成し、agent に接続する方法

必要なもの​

Squid App を作成する​

  1. Squid Console に移動し、Zendesk MCP Tutorial という名前の新しい Squid application を作成します。
  2. application overview page で Backend project section まで scroll します。Initialize Backend をクリックして initialization command を copy します。
  3. project の任意の location にある terminal で initialization command を実行します。

Zendesk Project をセットアップする​

starter Squid backend ができたので、Zendesk に接続する MCP server を作成するよう customize できます。

Zendesk と interaction する方法は複数ありますが、この tutorial では Zendesk API の call に Node Zendesk API client を使用します。

  1. 任意の IDE で project を開きます。client を install するには、terminal で以下の command を実行します。
npm install node-zendesk

tsconfig.json file も update し、以下の setting を含める必要があります。

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

  1. src/service/example-service.ts の name を zendesk-mcp.service.ts に変更し、class name を ZendeskMcpService に update します。

  2. 新しい service を export するように src/service/index.ts file を update します。

export * from './zendesk-mcp.service.ts';
  1. src directory に providers という新しい directory を作成します。providers directory 内に zendesk.provider.ts という新しい file を作成します。この file には、Node Zendesk client を使用して Zendesk API と interaction する logic が含まれます。ここには 2 つの basic function が含まれます。AI agent が comment を追加して ticket の status を update できる replyToTicket と、ticket を作成する createTicket です。src/providers/zendesk.provider.ts に以下の 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;
  }
}

さらに、MCP server を保護するには @mcpAuthorizer decorator を使用して、authorized user のみに access を制限します。createTicket method の下に、以下の 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. Zendesk API を使用するには Zendesk API key を指定する必要があります。Zendesk API key を作成するには、Zendesk documentationの instruction に従います。次に、左 sidebar の Squid Console Secrets page に移動します。Store New Secret をクリックし、次の value を追加します。

    • Secret key: ZENDESK_API_KEY
    • Value: Zendesk API key

    正しい authorization value を含む 2 つ目の secret を追加します。

    • Secret key: MCP_AUTH_VALUE
    • Value: Bearer some_secure_auth_value（または任意の secure value。ただし、上記の authorizeMcp method の value と一致することを確認してください）

  2. base-zendesk.service.ts という新しい service file を作成します。この file には、必要な credential で初期化した base Zendesk provider を含めます。src/service/base-zendesk.service.ts に credential を含む以下の code を追加します。

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'
  );
}

これらの step を完了すると、custom Zendesk MCP server を作成するために必要なすべての component が揃います。

Squid + Zendesk MCP Server を作成する​

  1. zendesk-mcp.service.ts file を開き、ticket を作成して ticket に reply する tool を持つ MCP server を作成するため、以下の code を追加します。@mcpServer decorator を使用すると、AI agent が使用できる MCP server を作成できます。
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. @mcpTool decorator は、AI agent が実行できる specific action を定義します。最初に追加する tool は Zendesk ticket を作成します。ZendeskMcpService class 内に以下の code を追加します。
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. ticket に reply して status を update できる tool をもう 1 つ作成します。
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);
    }
  }
}

AI Agent を MCP Server に接続する​

custom Zendesk MCP server を作成したので、AI agent に接続できます。

server を AI agent に expose するには、backend を deploy する必要があります。

  1. このため、backend を実行している terminal で CTRL + C を押して local backend を停止し、以下の command を実行します。
squid deploy

  1. 次に Squid Console の Connectors tab に移動し、Available Connectors をクリックします。MCP connector を見つけ、Add Connector をクリックします。

  2. 以下の connector detail を指定します。

    • Connector ID: 任意の unique ID。zendesk-mcp のように、簡潔で意味のある ID にすることをおすすめします。
    • MCP URL: deploy 済み backend が提供する MCP endpoint URL。MCP URL は console の Backend tab に移動し、MCP Servers の下で確認できます。

    次に Authorization を on に toggle し、以下の detail を指定します。

    • Authorization Header: Authorization
    • Authorization Value: 先ほど作成した MCP_AUTH_VALUE secret

  3. Test Connection をクリックして server への connection を test します。connection が failure した場合は、MCP URL の value を確認してください。connection が成功したら、Add Connector をクリックします。


MCP connector を追加したので、これを使用する AI agent を作成します。

  1. Squid Console の Agent Studio tab に移動し、Create New Agent をクリックします。
  2. 以下の detail を指定します。
    • Agent ID: Zendesk Agent などの agent name。
    • Agent Description: An agent that can create and reply to Zendesk tickets などの description。 Create をクリックします。
  3. agent の Overview tab で Add Abilities をクリックし、MCP ability を選択します。先ほど作成した zendesk-mcp connector を含む dropdown が開きます。connector を選択し、Add Connector をクリックします。次に agent が MCP server を invoke するタイミングについて specific instruction を指定できます。以下の instruction を追加します。
Use this MCP server when prompted to interact with Zendesk

これで agent は Zendesk MCP server を使用する準備ができました！

Agent をテストする​

agent を test するには、Agent Studio の Test Agent tab に移動します。agent に ticket の作成と reply を依頼して interaction できます。以下の example prompt を使用できます。

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

次のステップ​

custom Zendesk MCP server を作成して AI agent に接続できました！この foundation を拡張し、MCP server にさらに tool を追加するか、AI agent の capability を強化できます。