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

カスタム Zendesk MCP サーバーを作成する

MCP サーバーを作成し、Zendesk インスタンスとやり取りする Squid agent に接続する​

作成するもの​

  • カスタム Squid MCP サーバーに接続して Zendesk とやり取りするシンプルな agent
  • チケットの作成、チケットステータスの更新、チケットへのコメント追加

このチュートリアルでは次の機能を使用します:

AI AbilitiesInternal Connectors
Model Context Protocol abilityModel Context Protocol server

学ぶこと​

  • Squid の backend SDK を使って MCP サーバーを作成し、agent に接続する方法

必要なもの​

Squid app を作成する​

  1. Squid Console に移動し、Zendesk MCP Tutorial という名前で新しい Squid application を作成します。
  2. application overview ページで Backend project セクションまでスクロールします。Initialize Backend をクリックし、初期化コマンドをコピーします。
  3. ターミナルで、プロジェクトを置きたい場所に移動して初期化コマンドを実行します。

Zendesk プロジェクトをセットアップする​

スターターの Squid backend を用意できたので、これをカスタマイズして Zendesk に接続する MCP サーバーを作成できます。

Zendesk とやり取りする方法はいくつかありますが、このチュートリアルでは Zendesk API を呼び出すために Node Zendesk API client を利用します。

  1. お好みの IDE でプロジェクトを開きます。client をインストールするために、ターミナルで次のコマンドを実行します:
npm install node-zendesk

また、tsconfig.json ファイルを更新して次の設定を含める必要があります:

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

  1. src/service/example-service.ts を zendesk-mcp.service.ts にリネームし、クラス名を ZendeskMcpService に更新します。

  2. src/service/index.ts ファイルを更新して、新しい service を export します:

export * from './zendesk-mcp.service.ts';
  1. src ディレクトリに providers という新しいディレクトリを作成します。providers ディレクトリ内に zendesk.provider.ts という新しいファイルを作成します。このファイルには Node Zendesk client を使って Zendesk API とやり取りするロジックを含めます。ここには 2 つの基本関数が含まれます: AI agent がチケットにコメントを追加しステータスを更新できる replyToTicket と、チケットを作成する createTicket です。src/providers/zendesk.provider.ts に次のコードを追加します:
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 サーバーを保護するために、@mcpAuthorizer decorator を使用して、認可されたユーザーのみにアクセスを制限します。createTicket メソッドの下に次のコードを追加します:

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 の手順に従ってください。次に、Squid Console の左サイドバーにある Secrets ページに移動します。Store New Secret をクリックして、次の値を追加します:

    • Secret key: ZENDESK_API_KEY
    • Value: あなたの Zendesk API key

    次に、正しい authorization value を含む 2 つ目の secret を追加します:

    • Secret key: MCP_AUTH_VALUE
    • Value: Bearer some_secure_auth_value（または任意の安全な値。ただし上記の authorizeMcp メソッド内の値と一致していることを確認してください）

  2. base-zendesk.service.ts という新しい service ファイルを作成します。このファイルには、必要な認証情報で初期化されたベースの Zendesk provider を含めます。src/service/base-zendesk.service.ts に、あなたの認証情報を使って次のコードを追加します。

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

これらの手順に従うことで、カスタム Zendesk MCP サーバーを作成するために必要なコンポーネントがすべて揃いました。

Squid + Zendesk MCP サーバーを作成する​

  1. zendesk-mcp.service.ts ファイルを開き、チケットの作成とチケットへの返信を行う tools を持つ MCP サーバーを作成するため、次のコードを追加します。@mcpServer decorator を使用することで、AI agents が利用できる MCP サーバーを作成できます。
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 が実行できる具体的なアクションを定義します。最初に追加する tool は Zendesk チケットを作成します。次のコードを ZendeskMcpService クラス内に追加します:
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. チケットへの返信とステータス更新ができる 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 サーバーに接続する​

カスタム Zendesk MCP サーバーを作成できたので、それを AI agent に接続できます。

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

  1. これを行うには、backend を実行しているターミナルで CTRL + C を押してローカル backend を停止し、次のコマンドを実行します:
squid deploy

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

  2. 次の connector details を入力します:

    • Connector ID: 任意の一意な ID。zendesk-mcp のように、短く意味のあるものにするのがベストです。
    • MCP URL: deploy 済み backend により提供される MCP endpoint URL。MCP URL を確認するには、console の Backend タブに移動し、MCP Servers の下にある MCP URL を確認します。

    次に Authorization をオンに切り替え、次の詳細を入力します:

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

  3. Test Connection をクリックして server への接続をテストします。接続に失敗する場合は MCP URL の値を確認してください。接続に成功したら Add Connector をクリックします。


MCP connector を追加できたので、次はそれを使う AI agent を作成します。

  1. Squid Console の Agent Studio タブに移動し、Create New Agent をクリックします。
  2. 次の詳細を入力します:
    • Agent ID: Zendesk Agent のような agent 名。
    • Agent Description: An agent that can create and reply to Zendesk tickets のような説明。 Create をクリックします。
  3. agent の Overview タブで Add Abilities をクリックし、MCP ability を選択します。これにより、先ほど作成した zendesk-mcp connector を含む dropdown が開きます。それを選択し Add Connector をクリックします。その後、この MCP server を agent がいつ呼び出すべきかの具体的な指示を入力できます。次の指示を追加します:
Use this MCP server when prompted to interact with Zendesk

これで、あなたの agent は Zendesk MCP server を使用する準備が整いました!

agent をテストする​

agent をテストするには、Agent Studio の Test Agent タブに移動します。チケットの作成や返信を依頼して agent とやり取りできます。以下は使用できる 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

次のステップ​

カスタム Zendesk MCP サーバーを作成し、AI agent に接続できました。おめでとうございます! ここから、MCP サーバーにさらに多くの tools を追加したり、AI agent の機能を強化したりして、この基盤を拡張できます。