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

MCP サーバーを作成し、Zendesk インスタンスと連携する Squid agent に接続する

作成するもの

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

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

AI Abilities	Internal Connectors
Model Context Protocol ability	Model Context Protocol server

学ぶこと

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

必要なもの

• Squid CLI
• Squid Console のアカウント
• Zendesk アカウント
• TypeScript の基本的な経験

Squid app を作成する

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

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

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

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

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

npm install node-zendesk

また、tsconfig.json に次の設定を追加する必要があります:

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

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

3. src/service/index.ts を更新して新しい service を export します:

export * from './zendesk-mcp.service.ts';

4. src ディレクトリに providers という新しいディレクトリを作成します。providers ディレクトリ内に zendesk.provider.ts という新しいファイルを作成します。このファイルには、Node Zendesk client を使って Zendesk API とやり取りするロジックを記述します。基本的な関数は 2 つ含まれます: replyToTicket（AI agent がチケットにコメントを追加し、ステータスを更新できる）と、チケット作成用の 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 デコレータを使用して認可されたユーザーのみにアクセスを制限します。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';
  }
}

5. 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 メソッド内の値と一致するようにしてください）

6. 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 を開き、チケット作成とチケット返信の tool を備えた MCP サーバーを作成するために次のコードを追加します。@mcpServer デコレータを使用することで、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 {
  
}

2. @mcpTool デコレータは、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);
  }
}

3. チケットに返信し、ステータスも更新できる 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. これを行うには、実行中のターミナルで CTRL + C を押して local backend を停止し、次のコマンドを実行します:

squid deploy

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

3. 次の connector 詳細を入力します:

   • 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

4. 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 をクリックします。その後、agent がいつこの MCP server を呼び出すべきかについて具体的な指示を入力できます。次の指示を追加します:

Use this MCP server when prompted to interact with Zendesk

これで agent は Zendesk MCP サーバーを使用する準備ができました!

agent をテストする

agent をテストするには、Agent Studio の Test Agent タブに移動します。チケット作成やチケット返信を依頼して agent と対話できます。以下は使用できるプロンプト例です:

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 サーバーにさらに tool を追加したり、AI agent の機能を強化したりして、この基盤を発展させることができます。

• Squid AI agents について詳しくは、documentation を参照してください。
• Squid の real-time data capabilities について詳しくは、Client SDK documentation を参照してください。
• 独自の data sources と統合する方法については、database connectors documentation を参照してください。