製品アップデートステータスページWorkato Academy
English
日本語
トライアルを開始
AIRO
AIRO MCPサーバー

AIRO MCPでカスタムコネクターを構築する ​

このページは機械翻訳により提供されています。翻訳内容と英語版に相違がある場合は、英語版が優先されます。

AIRO MCPサーバーを使用して、Claude Code、Claude Desktop、CursorなどのMCPクライアントからカスタムコネクターを作成および編集できます。 APIと目的の動作を平易な言葉で説明すると、AIROがコネクション、アクション、トリガー、スキーマのConnector SDKコードを記述して検証します。

基盤となるSDKの概念と構文については、Connector SDKドキュメントを参照してください。

機能の提供状況

AIRO MCPを使用したカスタムコネクターの構築は、現在一部のお客様のみ利用できます。詳細については、カスタマーサクセス担当者にお問い合わせください。

前提条件 ​

  • ワークスペースでAIROが有効になっており、AIRO MCPサーバーがMCPクライアントに接続されていること。
  • カスタムコネクターを作成、編集、公開するためのConnector SDK権限。 Workatoは、OAuth 2.0コネクションにはWorkatoアカウントの権限を使用し、APIトークンコネクションにはAPIクライアントロールを使用します。リリース済みコネクターを選択してレシピを構築するには、Connector SDKのUse in recipes権限も必要です。 Connector SDK権限を参照してください。
  • 認証、エンドポイント、リクエストとレスポンスの例、ページネーション、エラー動作を含むターゲットAPIドキュメント。これがない場合、MCPクライアントは関連するAPIドキュメントをインターネットで検索することになり、見つかったAPIの詳細を検証する責任はユーザーにあります。
  • APIがレコードを作成、更新、または削除できる場合の非本番アカウントまたは安全なテストデータ。

パスワード、トークン、クライアントシークレット、その他の資格情報をプロンプトに貼り付けたり、コネクターソースにハードコードしたりしないでください。機密値をコネクションフィールドとして定義し、実際の値をWorkatoコネクションに保存します。

使用可能なツール ​

AIRO MCPは、MCPクライアントでコネクターを構築およびリリースできる次のツールで構成されています。

ツール機能
connector_builder_init_connector新しいコネクターを作成します。
connector_builder_get_latest_connector_code既存のコネクターの最新保存済みソースをセッションに読み込みます。
connector_builder_read_connector_codeセッションの現在のソースを変更せずに読み取りまたは検索します。
connector_builder_apply_connector_code_patchセッション内のコネクターを更新する前に、更新されたコードをSDKフレームワークとルールに照らして検証します。
connector_builder_save_latest_connector_code変更していないコードも含めてコネクター全体を検証し、新しいバージョンを保存します。
connector_builder_get_unreleased_code_diffセッションの現在のソースをコネクターの最新リリース済みバージョンと比較します。
connector_builder_release_connector現在の作業コピーを検証して保存し、有効なバージョンとしてリリースします。

MCPクライアントは、コネクターの作成、編集、保存、リリースなど、Workatoを変更する操作の承認を求める場合があります。承認する前に、操作とターゲットコネクターを確認してください。一部のクライアントでは、代わりにサーバー設定で各ツールの権限レベルを事前に設定できます。開始する前に、AIRO MCPコネクションが目的のワークスペースとEnvironmentを指していることを確認します。

例: 気象アラートコネクターを構築する ​

この例では、無料のNational Weather Service API用のコネクターを作成します。このAPIにはAPIキーは不要ですが、アプリケーションを識別し、連絡先情報を提供するUser-Agentヘッダーが必要です。

この例を完了すると、コネクターには次のものが含まれます。

  • 連絡先メール用のコネクションフィールド。
  • 州または地域のアクティブなアラートを取得するアクション。
  • 新しく発行されたアクティブなアラートのポーリングトリガー。
  • リリース前にレビューできる保存済みバージョン。

AIROは、同じリクエストに対して異なる有効な実装を生成できます。そのため、コネクターが同等の動作を提供する場合でも、生成されたコード、フィールド名、説明がこのガイドの例と異なる場合があります。

コネクターと最初のアクションを作成する ​

まず、AIROに構築させるコネクターと最初の動作を説明します。表示タイトルとAPIドキュメントを含めます。

text
Build a custom connector named National Weather Service Alerts for the National Weather Service API. Use <https://www.weather.gov/documentation/services-web-api> as the API documentation. Set the connector's SDK `title` to `National Weather Service Alerts`. Add an action that retrieves active weather alerts for a state or territory.

AIROはワークスペース内にコネクターをすぐに作成し、現在のセッションをそのコネクターにバインドします。クライアントで利用可能なAPIドキュメントを使用してコネクションとアクションを生成し、その結果を検証します。

コネクターの命名

ワークスペースで作成されたコネクターレコードと、SDKソース内のtitleキーは別々のものです。ユーザーがレシピでコネクターを選択するときに目的の表示名が表示されるように、SDKのtitleを明示的に設定します。

コネクタータイトルはワークスペース内で一意である必要があります。タイトルがすでに使用されている場合は、別のタイトルを選択するか、(Custom)などの修飾子を追加します。

このAPIの場合、生成されるコネクションとリクエストロジックには、連絡先フィールド、User-Agentヘッダー、active-alertsエンドポイントが含まれている必要があります。

生成されたコネクションとアクションのコードを表示
ruby
connection: {
  fields: [
    {
      name: 'contact_email',
      label: 'Contact email',
      optional: false,
      hint: 'Used in the User-Agent header required by the National Weather Service API.'
    }
  ],
  authorization: { type: 'no_auth' },
  base_uri: lambda do |_connection|
    'https://api.weather.gov/'
  end
},

test: lambda do |connection|
  get('alerts/active').
    headers('User-Agent': "(workato-integration, #{connection['contact_email']})").
    params(area: 'CA')
end,

actions: {
  get_active_alerts: {
    title: 'Get active alerts',
    input_fields: lambda do
      [
        {
          name: 'area',
          label: 'State or territory code',
          optional: false,
          hint: 'Two-letter code, for example CA or NY.'
        }
      ]
    end,
    execute: lambda do |connection, input|
      response = get('alerts/active').
        headers('User-Agent': "(workato-integration, #{connection['contact_email']})").
        params(area: input['area']).
        after_error_response(/.*/) do |_code, body, _header, message|
          error("#{message}: #{body}")
        end

      { alerts: response['features'].map { |feature| feature['properties'] } }
    end,

    output_fields: lambda do
      [
        {
          name: 'alerts',
          type: 'array',
          of: 'object',
          properties: [
            { name: 'id' },
            { name: 'event' },
            { name: 'headline' },
            { name: 'severity' },
            { name: 'sent', type: 'date_time' },
            { name: 'expires', type: 'date_time' }
          ]
        }
      ]
    end
  }
}

気象アラートは、汎用的な作成、取得、更新、削除のパターンには適合しません。たとえばget_active_alertsのようなオブジェクト固有のアクションにすると、コネクターを理解して使用しやすくなります。

生成されたコードをレビューしてから、変更をバージョンとして保存します。

text
Save this connector.

AIROはコネクター全体を検証し、保存されたバージョン番号とWorkato内のコネクターへのリンクを返します。正確なバージョン番号は、コネクターの保存履歴によって異なります。

ポーリングトリガーを追加する ​

次に、ポーリングトリガーでコネクターを拡張します。現在のセッションはすでにコネクターにバインドされているため、コネクターIDを繰り返す必要はありません。

text
Add a trigger for new active alerts in a state or territory.

AIROは既存のコネクターにトリガーを追加し、更新されたSDKコードを検証します。

生成されたトリガーコードを表示
ruby
triggers: {
  new_active_alert: {
    title: 'New active alert',
    input_fields: lambda do
      [
        {
          name: 'area',
          label: 'State or territory code',
          optional: false,
          hint: 'Two-letter code, for example CA or NY.'
        },
        {
          name: 'since',
          label: 'When first started, this recipe should pick up alerts from',
          type: 'timestamp',
          optional: true,
          sticky: true
        }
      ]
    end,
    poll: lambda do |connection, input, closure|
      closure = {} unless closure.present?

      sent_since = (closure['cursor'] || input['since'] || Time.now).to_time.utc.iso8601

      response = get('alerts/active').
        headers('User-Agent': "(workato-integration, #{connection['contact_email']})").
        params(area: input['area']).
        after_error_response(/.*/) do |_code, body, _header, message|
          error("#{message}: #{body}")
        end

      alerts = response['features'].
        map { |feature| feature['properties'] }.
        select { |alert| alert['sent'].to_time.utc.iso8601 > sent_since }

      closure['cursor'] = alerts.
        map { |alert| alert['sent'].to_time.utc.iso8601 }.
        max || sent_since

      {
        events: alerts,
        next_poll: closure,
        can_poll_more: false
      }
    end,
    dedup: lambda do |record|
      "#{record['id']}@#{record['sent']}"
    end,
    output_fields: lambda do
      [
        { name: 'id' },
        { name: 'event' },
        { name: 'headline' },
        { name: 'severity' },
        { name: 'sent', type: 'date_time' },
        { name: 'expires', type: 'date_time' }
      ]
    end
  }
}

生成されたトリガー全体をレビューし、特にカーソル処理、タイムスタンプ比較、ページネーション、重複排除ロジックに注意してください。次に、コネクターを保存します。

text
Save this connector.

リリース前にレビューおよびテストする ​

AIROは、保存前に生成されたConnector SDKコードを検証し、Ruby構文エラーもチェックします。リリース前に、完全な実装をレビューし、Workatoでテストして、コネクターがターゲットAPIで想定どおりに動作することを確認します。検証に成功しても、API固有のレビューやランタイムテストの代わりにはなりません。

リリース前に次のチェックを完了します。

  1. 完全な実装をレビューします。 AIROが返す概要を全体像として使用し、返されたWorkatoリンクをたどってコネクター全体を確認します。理解できないブロックがあれば、AIROに説明を依頼します。
  2. 実装をAPIドキュメントと比較します。 ベースURL、パス、認証、ヘッダー、フィールド名、リクエストパラメーター、レスポンス構造、ページネーション、レート制限、エラーレスポンスを確認します。
  3. Workatoでテストコネクションを作成します。 この例では、連絡先メールを指定し、コネクションテストが成功することを確認します。
  4. 安全な入力でアクションを実行します。 SDKのTest codeタブを使用してアクションを実行します。たとえば、CAのアクティブなアラートをリクエストし、返されたフィールドが宣言済みの出力スキーマと一致することを確認します。 Test codeタブを使用するを参照してください。
  5. トリガーをテストします。 初期since動作、カーソル更新、順序、ページネーション、重複排除を確認します。ランタイムテストにより、コードレビューだけでは明らかにならないスキップされたイベントや繰り返し発生するイベントを検出できます。
  6. ターゲットEnvironmentを確認します。 既存のレシピが使用する可能性のある変更をリリースする前に、DevelopmentまたはテストEnvironmentでテストします。

リリース前に、重点的なレビューをAIROに依頼することもできます。

text
Review the current connector for release readiness without changing it. Compare the connection, action, and trigger with the National Weather Service API documentation. Check the authentication, request paths and parameters, input and output schemas, response mapping, pagination, cursor behavior, deduplication, and error handling. Explain any risks you find and recommend changes.

コネクターをリリースする ​

AIROにコネクターのリリースを依頼します。

text
Save and release these changes.

リリースはすべてのレシピに即時反映

リリースすると保存済みバージョンがただちにアクティブバージョンになり、そのコネクターを使用するすべてのレシピで使用が開始されます。

AIROは未リリースの変更をレビューし、公開予定の内容のサマリーとともにこの警告を表示して、コネクターをリリースする前に確認を求めます。このコネクターにはまだリリース済みバージョンがないため、AIROはこれを変更サマリーではなく初回リリースとして報告します。以前に承認した内容にかかわらず、各リリースには個別の明示的な確認が必要です。独自のリリースノートを指定することも、AIROに差分から提案させることもできます。

AIROは、次のどれが発生したかを通知します。

  • リリース済み。 コネクターは新しいバージョンになりました。
  • すでに最新。 保存済みバージョンはすでに有効であったため、何も変更されませんでした。
  • 保存済みだが未リリース。 保存は成功しましたが、その後のリリース手順が失敗しました。
  • 拒否。 検証結果により保存がブロックされたため、何も保持されませんでした。

拒否または未リリースの結果は、有効なバージョンが変更されなかったことを意味します。報告された問題を解決して、もう一度依頼します。

コネクターのリリース後に次のことを確認します。

  • 想定されるバージョンがアクティブであること。
  • コネクターがSDKのtitleフィールドの値で表示されること。
  • コネクターが目的のEnvironmentのレシピで利用可能であること。

後続のリリース前に変更内容を確認する ​

コネクターをリリースした後に編集する場合は、いつでもAIROに変更内容を確認できます。

text
What changed in this connector since the last release?

AIROは、破壊的変更、追加項目、変更項目にグループ化されたサマリーを返すため、コネクター全体ではなく更新内容に絞ってレビューできます。

効果的なプロンプトを作成する ​

優れたプロンプトには、目標、信頼できる情報源、関連するコネクターコンテキスト、重要な制約、検証する具体的な結果が含まれます。

有用なパターンは次のとおりです。

目標 + ターゲットコネクターまたはAPI + 従うべきドキュメントまたは既存コード + 要件と制約 + 受け入れチェック

大きなコネクターを、レビュー可能な変更に分割します。最初にコネクションと1つのアクションを構築してテストし、保存してから、トリガーまたはより複雑なアクションを追加します。これにより、検証結果と動作上の問題を分離しやすくなります。

新しいコネクターを構築する ​

ターゲットAPI、コネクタータイトル、認証、最初の操作を指定します。"気象データ用のコネクターを構築して"のような曖昧なプロンプトでは、4つすべてが省略されています。

text
Build a custom connector named National Weather Service Alerts for the National Weather Service API. Use <https://www.weather.gov/documentation/services-web-api> as the source of truth. Set the SDK `title` to `National Weather Service Alerts`. The API doesn't use an API key but requires a User-Agent with contact information. Add an action that retrieves active alerts for a two-letter state or territory code.

APIで認証が必要な場合は、認証タイプ、必要なスコープ、トークン更新動作、コネクションをテストするための安全なエンドポイントも含めます。

既存のコネクターを編集する ​

コネクターID、変更するコンポーネント、従うべき既存パターン、期待される結果を指定します。

text
Open connector 4821. Read its existing get-ticket action, then add an update-ticket action that follows the same object schema and error-handling pattern. Don't change unrelated actions. Validate the edit and summarize the exact blocks changed.

名前が曖昧または重複している場合は、数値のコネクターIDを使用します。別のコネクターに切り替える前に作業を保存し、その後新しいコネクターを明示的に開いて、セッションが前のコネクターの編集を継続しないようにします。

失敗した保存を修正する ​

コネクターID、エラーテキスト全文、影響を受けるコンポーネント、直近の変更を含めます。

text
Open connector 4821. Its polling trigger returns the following validation error after my last edit: [paste the error]. Read the complete trigger, explain the cause, make the smallest safe correction, and validate the connector.

制限事項 ​

  • AIRO MCPはカスタムコネクターを削除できません。 Workato UIから未使用のコネクターを削除します。まず、そのコネクターを使用しているアクティブなレシピをすべて停止する必要があります。カスタムコネクターを削除するを参照してください。
  • AIRO MCPは、Workato SDKエディターを操作するのではなくMCPセッションを通じてコネクターを変更し、同期されたローカルソースファイルは維持しません。保存ごとにバージョンが書き込まれ、その後Workatoで開いてテストできます。
  • 保存時には、最新の編集だけでなくコネクター全体が検証されます。ソース内の他の場所にある検出結果により、それらを解決するまで保存がブロックされる場合があります。
  • connector_builder_get_unreleased_code_diffは、セッションですでに開いているソースのみを比較します。まず、connector_builder_get_latest_connector_codeまたはconnector_builder_init_connectorを使用してコネクターを開きます。

トラブルシューティング ​

AIROが誤った場所でコネクターを作成または開いた ​

AIRO MCPコネクションに関連付けられているワークスペースとEnvironmentを確認します。他のものを作成または保存する前に、目的のターゲットに再接続します。

操作が拒否される ​

接続されているWorkatoユーザーまたはAPIクライアントロールに、必要なConnector SDK権限があることを確認します。 AIRO MCPは、接続されたIDの権限を超えることはできません。

自分が導入していない検出結果により保存が失敗する ​

保存時にはソース全体が検証されます。現在のすべての検出結果を一覧表示し、変更したブロックの外にあるものを特定するようAIROに依頼します。保存する前に検出結果を解決します。コードを一時的にコメントアウトする場合は、コネクターを保存またはリリースする前に機能への影響をレビューしてください。

サイズが原因で保存が拒否される ​

繰り返し使われているスキーマまたはロジックを特定し、ソースを削減するようAIROに依頼します。繰り返し使われているフィールドスキーマをobject_definitionsに移動することが、通常は最も大きな削減になります。

AIROが名前でコネクターを見つけられない ​

数値のコネクターIDを使用します。別のコネクターがリクエストしたタイトルをすでに使用している場合は、一意のタイトルを選択します。

パスが正しく見えるのにコネクションテストが失敗する ​

base_uriとリクエストパスの結合方法を確認します。 /で始まるリクエストパスは、base_uri内のパスセグメントを置き換えます。たとえば、https://host/api/v2/を/usersと組み合わせると、/api/v2/配下ではなくホストルートから解決されます。ベースパスを維持するには、base_uriの末尾に/を使用し、相対リクエストパスの先頭の/を省略します。 base_uriの設定を参照してください。

リリースでバージョンがすでに最新であると報告される ​

最新の保存済みバージョンがすでに有効なバージョンだったため、リリースでは何も変更されませんでした。 AIROまたはWorkato UIから同じ保存済みバージョンを2回リリースし、その間に新しい編集を保存しない場合、この結果が想定されます。

コネクターは保存されたが、レシピではまだ古い動作が使用されている ​

保存済みバージョンは、リリースされるまでアクティブになりません。 AIROに前回のリリース以降の変更内容を確認するか、Workatoでコネクターを開いて、最新の保存済みバージョンと有効なリリース済みバージョンを比較します。

最終更新日: