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

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

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

前提条件 ​

• ワークスペースで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クライアントでコネクターを構築できる次のツールで構成されています。

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

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

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

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

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

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

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

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

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ドキュメントを使用してコネクションとアクションを生成し、その結果を検証します。

新しいコネクターは、次のような最小構造で始まります。

{
  title: 'National Weather Service Alerts',
  connection: {
    fields: [],
    authorization: { type: 'no_auth' }
  },
  test: ->(_connection) { true },
  actions: {},
  triggers: {}
}

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

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のようなオブジェクト固有のアクションにすると、コネクターを理解して使用しやすくなります。

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

Save this connector.

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

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

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

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

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

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
  }
}

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

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に依頼することもできます。

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 MCPツールに含まれません: AIROはコネクターを作成、編集、保存できますが、保存済みバージョンはWorkato UIで自分でリリースします。

コネクターをリリースするには、次の手順を実行します。

詳細については、最新バージョンをリリースするを参照してください。

検証する:

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

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

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

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

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

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

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

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

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、変更するコンポーネント、従うべき既存パターン、期待される結果を指定します。

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、エラーテキスト全文、影響を受けるコンポーネント、直近の変更を含めます。

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

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

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

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

操作が拒否される ​

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

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

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

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

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

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

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

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

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

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

最新の保存済みバージョンはすでにアクティブバージョンだったため、リリースによる変更はありませんでした。 Workato UIでリリースを2回実行し、その間にAIROで新しい編集を保存していない場合は、この動作が予想されます。

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

保存済みバージョンは、リリースされるまでアクティブになりません。 Workatoでコネクターを開き、最新の保存済みバージョンとアクティブなリリース済みバージョンを比較します。