エージェントコネクタ

エージェントコネクタは、外部サービスのツールや API を AIエージェントやMCPクライアントから利用するための設定です。外部の MCP サーバーへの接続と、HTTP API への接続の2種類があります。

コネクタ経由の呼び出しでは、Codatum が保持する認証情報を使って外部サービスへリクエストを送ります。データが Codatum の外へ出るため、呼び出しごとに宛先を outbound に記録します。

認証情報は、ワークスペースで共有するものとユーザーごとのものに分かれます。どちらも、登録・差し替え・失効を到達可能性の変更として記録します。

どのコネクタを利用できるかは AIプロファイルのツール権限でも制限されます。

イベント一覧

イベント	リソース	説明
`agent_connector.create`	`agent_connector`	エージェントコネクタが作成された
`agent_connector.rename`	`agent_connector`	エージェントコネクタ名が変更された
`agent_connector.change_status`	`agent_connector`	エージェントコネクタが有効化・無効化された
`agent_connector.change_allowed_urls`	`agent_connector`	エージェントコネクタの追加の許可 URL が変更された
`agent_connector.change_credential`	`agent_connector`	エージェントコネクタの認証情報が差し替えられた
`agent_connector.connect`	`agent_connector`	エージェントコネクタが接続された
`agent_connector.disconnect`	`agent_connector`	エージェントコネクタが切断された
`agent_connector.call_mcp_tool`	`agent_connector`	外部の MCP サーバーのツールが呼び出された
`agent_connector.call_api`	`agent_connector`	エージェントコネクタ経由で外部 API が呼び出された
`agent_connector.delete`	`agent_connector`	エージェントコネクタが削除された

イベント詳細

`agent_connector.create` 準備中

エージェントコネクタの作成を記録します。

フィールド	値
`event.code`	`agent_connector.create`
`scope.type`	`workspace`
`resource.type`	`agent_connector`
`references`	（なし）
`query`	（なし）
`outbound`	（なし）
`change`	作成時の設定
`grant`	（なし）
`extra`	接続方式と認証の構成

`change`

作成時点の有効状態・接続先・追加の許可 URL が入ります。接続先はオリジンまでを記録します。

名前	モード	型	必須	説明
`enabled`	値	`bool`	必須	作成時の有効状態
`endpoint`	値	`string`	必須	作成時の接続先のオリジン sensitivity: `confidential`
`allowed_url_prefixes`	値	`string[]`	任意	作成時の追加の許可 URL プレフィックスの一覧。1つも指定されていないときは `null` です sensitivity: `confidential`

`extra`

作成されたコネクタの接続方式・認証情報の共有範囲・認証方式が入ります。

名前	型	必須	説明
`connector_type`	`ConnectorType`	必須	接続方式
`auth_scope`	`ConnectorAuthScope`	必須	認証情報を共有する範囲
`auth_type`	`ConnectorAuthType`	必須	認証方式

サンプル

共有認証の API コネクタ

json

{
  "event": {
    "code": "agent_connector.create",
    ...
  },
  "scope": {
    "type": "workspace",
    ...
  },
  "resource": {
    "type": "agent_connector",
    "uid": "63e1be654aa70ad689601c30",
    "name": "Example CRM",
    "path": "agent_connector/63e1be654aa70ad689601c30",
    "parts": [
      {
        "type": "agent_connector",
        "uid": "63e1be654aa70ad689601c30",
        "name": "Example CRM"
      }
    ],
    ...
  },
  "change": {
    "fields": [
      {
        "name": "enabled",
        "new": true
      },
      {
        "name": "endpoint",
        "new": "https://api.example.com"
      },
      {
        "name": "allowed_url_prefixes",
        "new": [
          "https://files.example.com/upload/"
        ]
      }
    ]
  },
  "extra": {
    "connector_type": "direct_api",
    "auth_scope": "workspace",
    "auth_type": "api_key"
  },
  ...
}

個人認証の MCP コネクタ

json

{
  "event": {
    "code": "agent_connector.create",
    ...
  },
  "scope": {
    "type": "workspace",
    ...
  },
  "resource": {
    "type": "agent_connector",
    "uid": "63e1be654aa70ad689601c30",
    "name": "Example CRM",
    "path": "agent_connector/63e1be654aa70ad689601c30",
    "parts": [
      {
        "type": "agent_connector",
        "uid": "63e1be654aa70ad689601c30",
        "name": "Example CRM"
      }
    ],
    ...
  },
  "change": {
    "fields": [
      {
        "name": "enabled",
        "new": true
      },
      {
        "name": "endpoint",
        "new": "https://api.example.com"
      }
    ]
  },
  "extra": {
    "connector_type": "mcp",
    "auth_scope": "account",
    "auth_type": "oauth"
  },
  ...
}

`agent_connector.rename` 準備中

エージェントコネクタの表示名の変更を記録します。

フィールド	値
`event.code`	`agent_connector.rename`
`scope.type`	`workspace`
`resource.type`	`agent_connector`
`references`	（なし）
`query`	（なし）
`outbound`	（なし）
`change`	`display_name`
`grant`	（なし）
`extra`	（なし）

`change`

名前	モード	型	必須	説明
`display_name`	値	`string`	必須	変更前後の表示名 sensitivity: `pii`

サンプル

json

{
  "event": {
    "code": "agent_connector.rename",
    ...
  },
  "scope": {
    "type": "workspace",
    ...
  },
  "resource": {
    "type": "agent_connector",
    "uid": "63e1be654aa70ad689601c30",
    "name": "Example CRM",
    "path": "agent_connector/63e1be654aa70ad689601c30",
    "parts": [
      {
        "type": "agent_connector",
        "uid": "63e1be654aa70ad689601c30",
        "name": "Example CRM"
      }
    ],
    ...
  },
  "change": {
    "fields": [
      {
        "name": "display_name",
        "old": "CRM",
        "new": "Example CRM"
      }
    ]
  },
  ...
}

`agent_connector.change_status` 準備中

エージェントコネクタの有効化・無効化を記録します。

フィールド	値
`event.code`	`agent_connector.change_status`
`scope.type`	`workspace`
`resource.type`	`agent_connector`
`references`	（なし）
`query`	（なし）
`outbound`	（なし）
`change`	`enabled`
`grant`	（なし）
`extra`	（なし）

`change`

名前	モード	型	必須	説明
`enabled`	値	`bool`	必須	変更前後の有効状態

サンプル

有効化

json

{
  "event": {
    "code": "agent_connector.change_status",
    ...
  },
  "scope": {
    "type": "workspace",
    ...
  },
  "resource": {
    "type": "agent_connector",
    "uid": "63e1be654aa70ad689601c30",
    "name": "Example CRM",
    "path": "agent_connector/63e1be654aa70ad689601c30",
    "parts": [
      {
        "type": "agent_connector",
        "uid": "63e1be654aa70ad689601c30",
        "name": "Example CRM"
      }
    ],
    ...
  },
  "change": {
    "fields": [
      {
        "name": "enabled",
        "old": false,
        "new": true
      }
    ]
  },
  ...
}

無効化

json

{
  "event": {
    "code": "agent_connector.change_status",
    ...
  },
  "scope": {
    "type": "workspace",
    ...
  },
  "resource": {
    "type": "agent_connector",
    "uid": "63e1be654aa70ad689601c30",
    "name": "Example CRM",
    "path": "agent_connector/63e1be654aa70ad689601c30",
    "parts": [
      {
        "type": "agent_connector",
        "uid": "63e1be654aa70ad689601c30",
        "name": "Example CRM"
      }
    ],
    ...
  },
  "change": {
    "fields": [
      {
        "name": "enabled",
        "old": true,
        "new": false
      }
    ]
  },
  ...
}

`agent_connector.change_allowed_urls` 準備中

エージェントコネクタが接続先に加えて到達できる URL プレフィックスの変更を記録します。接続先そのものは作成後に変更できないため、ここに現れるのは追加分だけです。

フィールド	値
`event.code`	`agent_connector.change_allowed_urls`
`scope.type`	`workspace`
`resource.type`	`agent_connector`
`references`	（なし）
`query`	（なし）
`outbound`	（なし）
`change`	変更前後の許可 URL
`grant`	（なし）
`extra`	（なし）

`change`

変更前後の URL プレフィックスの一覧が入ります。差分ではありません。

名前	モード	型	必須	説明
`allowed_url_prefixes`	値	`string[]`	必須	変更前後の URL プレフィックスの一覧。1つも設定されていないときは `null` です sensitivity: `confidential`

サンプル

json

{
  "event": {
    "code": "agent_connector.change_allowed_urls",
    ...
  },
  "scope": {
    "type": "workspace",
    ...
  },
  "resource": {
    "type": "agent_connector",
    "uid": "63e1be654aa70ad689601c30",
    "name": "Example CRM",
    "path": "agent_connector/63e1be654aa70ad689601c30",
    "parts": [
      {
        "type": "agent_connector",
        "uid": "63e1be654aa70ad689601c30",
        "name": "Example CRM"
      }
    ],
    ...
  },
  "change": {
    "fields": [
      {
        "name": "allowed_url_prefixes",
        "old": null,
        "new": [
          "https://api.example.com/v2/"
        ]
      }
    ]
  },
  ...
}

`agent_connector.change_credential` 準備中

エージェントコネクタの認証情報の登録・差し替えを記録します。

フィールド	値
`event.code`	`agent_connector.change_credential`
`scope.type`	`workspace`
`resource.type`	`agent_connector`
`references`	（なし）
`query`	（なし）
`outbound`	（なし）
`change`	（なし）
`grant`	（なし）
`extra`	認証情報の共有範囲

`extra`

差し替えられた認証情報の共有範囲が入ります。

名前	型	必須	説明
`auth_scope`	`ConnectorAuthScope`	必須	認証情報を共有する範囲

サンプル

共有認証情報の差し替え

json

{
  "event": {
    "code": "agent_connector.change_credential",
    ...
  },
  "scope": {
    "type": "workspace",
    ...
  },
  "resource": {
    "type": "agent_connector",
    "uid": "63e1be654aa70ad689601c30",
    "name": "Example CRM",
    "path": "agent_connector/63e1be654aa70ad689601c30",
    "parts": [
      {
        "type": "agent_connector",
        "uid": "63e1be654aa70ad689601c30",
        "name": "Example CRM"
      }
    ],
    ...
  },
  "extra": {
    "auth_scope": "workspace"
  },
  ...
}

個人の認証情報の差し替え

json

{
  "event": {
    "code": "agent_connector.change_credential",
    ...
  },
  "scope": {
    "type": "workspace",
    ...
  },
  "resource": {
    "type": "agent_connector",
    "uid": "63e1be654aa70ad689601c30",
    "name": "Example CRM",
    "path": "agent_connector/63e1be654aa70ad689601c30",
    "parts": [
      {
        "type": "agent_connector",
        "uid": "63e1be654aa70ad689601c30",
        "name": "Example CRM"
      }
    ],
    ...
  },
  "extra": {
    "auth_scope": "account"
  },
  ...
}

`agent_connector.connect` 準備中

OAuth による外部サービスへの接続の完了を記録します。

フィールド	値
`event.code`	`agent_connector.connect`
`scope.type`	`workspace`
`resource.type`	`agent_connector`
`references`	（なし）
`query`	（なし）
`outbound`	（なし）
`change`	（なし）
`grant`	（なし）
`extra`	許可された操作の範囲

`extra`

接続に許可された外部サービス側の操作の範囲が入ります。外部サービスが範囲を返さない場合は入りません。

名前	型	必須	説明
`scopes`	`string[]`	任意	接続に許可された操作の範囲

サンプル

json

{
  "event": {
    "code": "agent_connector.connect",
    ...
  },
  "scope": {
    "type": "workspace",
    ...
  },
  "resource": {
    "type": "agent_connector",
    "uid": "63e1be654aa70ad689601c30",
    "name": "Example CRM",
    "path": "agent_connector/63e1be654aa70ad689601c30",
    "parts": [
      {
        "type": "agent_connector",
        "uid": "63e1be654aa70ad689601c30",
        "name": "Example CRM"
      }
    ],
    ...
  },
  "extra": {
    "scopes": [
      "contacts.read",
      "contacts.write"
    ]
  },
  ...
}

`agent_connector.disconnect` 準備中

エージェントコネクタの認証情報の失効を記録します。

フィールド	値
`event.code`	`agent_connector.disconnect`
`scope.type`	`workspace`
`resource.type`	`agent_connector`
`references`	（なし）
`query`	（なし）
`outbound`	（なし）
`change`	（なし）
`grant`	（なし）
`extra`	認証情報の共有範囲

`extra`

失効した認証情報の共有範囲が入ります。

名前	型	必須	説明
`auth_scope`	`ConnectorAuthScope`	必須	認証情報を共有する範囲

サンプル

json

{
  "event": {
    "code": "agent_connector.disconnect",
    ...
  },
  "scope": {
    "type": "workspace",
    ...
  },
  "resource": {
    "type": "agent_connector",
    "uid": "63e1be654aa70ad689601c30",
    "name": "Example CRM",
    "path": "agent_connector/63e1be654aa70ad689601c30",
    "parts": [
      {
        "type": "agent_connector",
        "uid": "63e1be654aa70ad689601c30",
        "name": "Example CRM"
      }
    ],
    ...
  },
  "extra": {
    "auth_scope": "account"
  },
  ...
}

`agent_connector.call_mcp_tool` 準備中

エージェントコネクタ経由の外部 MCP サーバーのツール呼び出しを記録します。

フィールド	値
`event.code`	`agent_connector.call_mcp_tool`
`scope.type`	`workspace`
`resource.type`	`agent_connector`
`references`	（なし）
`query`	（なし）
`outbound`	呼び出した MCP サーバー
`change`	（なし）
`grant`	（なし）
`extra`	（なし）

`outbound`

呼び出した外部 MCP サーバーのオリジンと、呼び出したツールの名前が入ります。リクエストの引数とレスポンスの内容は記録しません。

サンプル

AIエージェントからの呼び出し

json

{
  "event": {
    "code": "agent_connector.call_mcp_tool",
    ...
  },
  "scope": {
    "type": "workspace",
    ...
  },
  "resource": {
    "type": "agent_connector",
    "uid": "63e1be654aa70ad689601c30",
    "name": "Example CRM",
    "path": "agent_connector/63e1be654aa70ad689601c30",
    "parts": [
      {
        "type": "agent_connector",
        "uid": "63e1be654aa70ad689601c30",
        "name": "Example CRM"
      }
    ],
    ...
  },
  "context": {
    "ai_agent": {
      "ai_profile": {
        "type": "ai_profile",
        "uid": "63e1be654aa70ad689601c10",
        "name": "Default"
      },
      "session": {
        "type": "agent_session",
        "uid": "63e1be654aa70ad689601c01",
        "name": "Weekly sales analysis"
      },
      "tool": "mcp_call_tool"
    }
  },
  "outbound": {
    "targets": [
      {
        "type": "mcp_server",
        "uid": "https://mcp.example.com",
        "name": "Example CRM",
        "tool": "search_documents"
      }
    ]
  },
  ...
}

MCPクライアントからの直接呼び出し

Codatum をゲートウェイとして外部サービスを呼び出します。AIエージェントセッションを経由しないため ai_agent は付きません。

json

{
  "event": {
    "code": "agent_connector.call_mcp_tool",
    ...
  },
  "scope": {
    "type": "workspace",
    ...
  },
  "resource": {
    "type": "agent_connector",
    "uid": "63e1be654aa70ad689601c30",
    "name": "Example CRM",
    "path": "agent_connector/63e1be654aa70ad689601c30",
    "parts": [
      {
        "type": "agent_connector",
        "uid": "63e1be654aa70ad689601c30",
        "name": "Example CRM"
      }
    ],
    ...
  },
  "context": {
    "mcp": {
      "client": {
        "type": "mcp_client",
        "uid": "cursor-dcr-01",
        "name": "Cursor"
      },
      "oauth_session": {
        "type": "mcp_oauth_session",
        "uid": "oauth_sess_01"
      },
      "scopes": [
        "connector:execute"
      ]
    }
  },
  "outbound": {
    "targets": [
      {
        "type": "mcp_server",
        "uid": "https://mcp.example.com",
        "name": "Example CRM",
        "tool": "search_documents"
      }
    ]
  },
  ...
}

`agent_connector.call_api` 準備中

エージェントコネクタ経由の外部 API の呼び出しを記録します。コネクタに定義されたアクションの実行と、任意の HTTP リクエストの送信の両方が対象です。

フィールド	値
`event.code`	`agent_connector.call_api`
`scope.type`	`workspace`
`resource.type`	`agent_connector`
`references`	（なし）
`query`	（なし）
`outbound`	呼び出した外部 API
`change`	（なし）
`grant`	（なし）
`extra`	（なし）

`outbound`

呼び出した外部 API のオリジンが入ります。コネクタに定義されたアクションを実行した場合は、そのアクション名が tool に入ります。エージェントが組み立てた任意の HTTP リクエストでは tool は入りません。

リクエストの内容（メソッド・パス・ヘッダ・ボディ）とレスポンスは記録しません。

サンプル

コネクタのアクションの実行

コネクタに定義されたアクションを実行した場合です。アクション名が tool に入ります。

json

{
  "event": {
    "code": "agent_connector.call_api",
    ...
  },
  "scope": {
    "type": "workspace",
    ...
  },
  "resource": {
    "type": "agent_connector",
    "uid": "63e1be654aa70ad689601c30",
    "name": "Example CRM",
    "path": "agent_connector/63e1be654aa70ad689601c30",
    "parts": [
      {
        "type": "agent_connector",
        "uid": "63e1be654aa70ad689601c30",
        "name": "Example CRM"
      }
    ],
    ...
  },
  "context": {
    "ai_agent": {
      "ai_profile": {
        "type": "ai_profile",
        "uid": "63e1be654aa70ad689601c10",
        "name": "Default"
      },
      "session": {
        "type": "agent_session",
        "uid": "63e1be654aa70ad689601c01",
        "name": "Weekly sales analysis"
      },
      "tool": "mcp_call_tool"
    }
  },
  "outbound": {
    "targets": [
      {
        "type": "connector_api",
        "uid": "https://api.example.com",
        "name": "Example CRM",
        "tool": "create_contact"
      }
    ]
  },
  ...
}

任意の HTTP リクエストの送信

エージェントがメソッドと URL を組み立てて送信した場合です。tool は入りません。

json

{
  "event": {
    "code": "agent_connector.call_api",
    ...
  },
  "scope": {
    "type": "workspace",
    ...
  },
  "resource": {
    "type": "agent_connector",
    "uid": "63e1be654aa70ad689601c30",
    "name": "Example CRM",
    "path": "agent_connector/63e1be654aa70ad689601c30",
    "parts": [
      {
        "type": "agent_connector",
        "uid": "63e1be654aa70ad689601c30",
        "name": "Example CRM"
      }
    ],
    ...
  },
  "context": {
    "ai_agent": {
      "ai_profile": {
        "type": "ai_profile",
        "uid": "63e1be654aa70ad689601c10",
        "name": "Default"
      },
      "session": {
        "type": "agent_session",
        "uid": "63e1be654aa70ad689601c01",
        "name": "Weekly sales analysis"
      },
      "tool": "connector_http_request"
    }
  },
  "outbound": {
    "targets": [
      {
        "type": "connector_api",
        "uid": "https://api.example.com",
        "name": "Example CRM"
      }
    ]
  },
  ...
}

MCPクライアントからの直接呼び出し

Codatum をゲートウェイとして外部サービスを呼び出します。AIエージェントのセッションを経由しないため ai_agent は付きません。

json

{
  "event": {
    "code": "agent_connector.call_api",
    ...
  },
  "scope": {
    "type": "workspace",
    ...
  },
  "resource": {
    "type": "agent_connector",
    "uid": "63e1be654aa70ad689601c30",
    "name": "Example CRM",
    "path": "agent_connector/63e1be654aa70ad689601c30",
    "parts": [
      {
        "type": "agent_connector",
        "uid": "63e1be654aa70ad689601c30",
        "name": "Example CRM"
      }
    ],
    ...
  },
  "context": {
    "mcp": {
      "client": {
        "type": "mcp_client",
        "uid": "cursor-dcr-01",
        "name": "Cursor"
      },
      "oauth_session": {
        "type": "mcp_oauth_session",
        "uid": "oauth_sess_01"
      },
      "scopes": [
        "connector:execute"
      ]
    }
  },
  "outbound": {
    "targets": [
      {
        "type": "connector_api",
        "uid": "https://api.example.com",
        "name": "Example CRM",
        "tool": "create_contact"
      }
    ]
  },
  ...
}

`agent_connector.delete` 準備中

エージェントコネクタの削除を記録します。

フィールド	値
`event.code`	`agent_connector.delete`
`scope.type`	`workspace`
`resource.type`	`agent_connector`
`references`	（なし）
`query`	（なし）
`outbound`	（なし）
`change`	（なし）
`grant`	（なし）
`extra`	（なし）

サンプル

json

{
  "event": {
    "code": "agent_connector.delete",
    ...
  },
  "scope": {
    "type": "workspace",
    ...
  },
  "resource": {
    "type": "agent_connector",
    "uid": "63e1be654aa70ad689601c30",
    "name": "Example CRM",
    "path": "agent_connector/63e1be654aa70ad689601c30",
    "parts": [
      {
        "type": "agent_connector",
        "uid": "63e1be654aa70ad689601c30",
        "name": "Example CRM"
      }
    ],
    ...
  },
  ...
}

Enums

`ConnectorType`

エージェントコネクタの接続方式です。

値	説明
`mcp`	外部の MCP サーバー
`direct_api`	外部の HTTP API

`ConnectorAuthScope`

エージェントコネクタの認証情報を共有する範囲です。

値	説明
`workspace`	ワークスペースで共有する認証情報
`account`	ユーザーごとの認証情報

`ConnectorAuthType`

エージェントコネクタの認証方式です。

値	説明
`oauth`	OAuth による認証
`api_key`	APIキーなどの固定の認証情報

エージェントコネクタ ​

イベント一覧 ​

イベント詳細 ​

agent_connector.create 準備中 ​

change ​

extra ​

サンプル ​

共有認証の API コネクタ ​

個人認証の MCP コネクタ ​

agent_connector.rename 準備中 ​

change ​

サンプル ​

agent_connector.change_status 準備中 ​

change ​

サンプル ​

有効化 ​

無効化 ​

agent_connector.change_allowed_urls 準備中 ​

change ​

サンプル ​

agent_connector.change_credential 準備中 ​

extra ​

サンプル ​

共有認証情報の差し替え ​

個人の認証情報の差し替え ​

agent_connector.connect 準備中 ​

extra ​

サンプル ​

agent_connector.disconnect 準備中 ​

extra ​

サンプル ​

agent_connector.call_mcp_tool 準備中 ​

outbound ​

サンプル ​

AIエージェントからの呼び出し ​

MCPクライアントからの直接呼び出し ​

agent_connector.call_api 準備中 ​

outbound ​

サンプル ​

コネクタのアクションの実行 ​

任意の HTTP リクエストの送信 ​

MCPクライアントからの直接呼び出し ​

agent_connector.delete 準備中 ​

サンプル ​

Enums ​

ConnectorType ​

ConnectorAuthScope ​

ConnectorAuthType ​

エージェントコネクタ

イベント一覧

イベント詳細

`agent_connector.create` 準備中

`change`

`extra`

サンプル

共有認証の API コネクタ

個人認証の MCP コネクタ

`agent_connector.rename` 準備中

`change`

サンプル

`agent_connector.change_status` 準備中

`change`

サンプル

有効化

無効化

`agent_connector.change_allowed_urls` 準備中

`change`

サンプル

`agent_connector.change_credential` 準備中

`extra`

サンプル

共有認証情報の差し替え

個人の認証情報の差し替え

`agent_connector.connect` 準備中

`extra`

サンプル

`agent_connector.disconnect` 準備中

`extra`

サンプル

`agent_connector.call_mcp_tool` 準備中

`outbound`

サンプル

AIエージェントからの呼び出し

MCPクライアントからの直接呼び出し

`agent_connector.call_api` 準備中

`outbound`

サンプル

コネクタのアクションの実行

任意の HTTP リクエストの送信

MCPクライアントからの直接呼び出し

`agent_connector.delete` 準備中

サンプル

Enums

`ConnectorType`

`ConnectorAuthScope`

`ConnectorAuthType`