接続

接続を使うと、エージェントが実行中に HTTP API や MCP サーバーを呼び出せます。認証情報は Ephemeral が保持し、呼び出しも Ephemeral が行います。ワーカーがトークン、パスワード、URL 内のシークレットを目にすることはありません。

呼び出しの仕組み

実行に許可した接続ごとに、エージェントが呼び出せるツールが追加されます。エージェントがツールを呼び出すと、ワーカーは、その実行でのみ有効な有効期間の短いトークンを付けて、リクエストを Ephemeral に送ります。Ephemeral は、その実行に接続が許可されていること、およびメソッドまたはツールが許可されていることを確認し、認証情報を付けてリクエストを送信します。レスポンスから認証情報の値を取り除いたうえで、エージェントに返します。呼び出しはそれぞれ connection イベントとして記録されます。

HTTP 接続では、エージェントがメソッド、接続の URL からの相対パス、そして必要に応じてボディを指定します。ボディは、エージェントがフォームや XML など別のコンテンツタイプを指定してテキストとして送る場合を除き、JSON として送信されます。MCP 接続では、エージェントにサーバーのツールが見えており、それらを直接呼び出します。

使い方をエージェントに伝える

HTTP 接続でエージェントに渡されるのはベース URL だけです。そのため、instructions に API の説明を書いてください。タスクに必要なエンドポイント、リクエストの形式、ID の形、守るべきルールなどです。エージェントは、これを接続のツールと常時の指示の中で参照します。実行では、保存済みの接続の instructions を独自のものに置き換えることもできます。

"instructions": "Find a customer with GET /v1/customers?email=... Create a refund with POST /v1/refunds as a form body (payment, amount in cents). Never refund more than the payment amount."

保存済みの接続とインラインの接続

保存済みの接続は、組織に一度保存しておき、名前で参照します。オーナーと管理者が、ダッシュボードの接続または PUT /v1/connections/{name} で作成します。実行とワークフローからは ref で参照します。

"connections": {
  "payments": { "ref": "payments-api", "allowed_methods": ["GET"] },
  "docs": { "ref": "docs-mcp", "allowed_tools": ["search"] }
}

payments などのキーは、その実行でエージェントに見える名前です。実行リクエストの中で、URL と認証情報を指定して接続をインラインで定義することもできます。インラインの認証情報は、その実行とともに暗号化して保存され、読み取り時には定義から取り除かれます。そのため、再実行するときは認証情報を改めて指定する必要があります。保存済みの接続を使えば、その手間はありません。

アクセスを絞り込む

allowed_methods は、HTTP 接続が受け付ける HTTP メソッドを制限します。allowed_tools は、MCP サーバーのどのツールを呼び出せるかを制限します。リストが空、または指定されていない場合は、すべてが許可されます。

実行では、保存済みの接続をさらに絞り込めます。実行が使えるのは、両方のリストに含まれるメソッドまたはツールだけです。2 つのリストに共通するものがない場合、実行リクエストは拒否されます。そのため、実行が保存済みの接続で許可された範囲を超えるアクセスを得ることはありません。

認証

OAuth では、オーナーまたは管理者が、プロバイダーのクライアント ID、認可 URL、トークン URL を指定して接続を保存し、ブラウザーで 1 度だけ認可します。Ephemeral はトークンを保管し、プロバイダーがリフレッシュトークンを発行している限り、有効期限が切れる前にアクセストークンを更新します。プロバイダーには、リダイレクト URI として https://app.ephemer.al/oauth/callback を登録してください。セルフホストのインストールでは、独自のドメインを使用します。

ネットワークのルール

• 接続の URL は HTTPS を使用し、パブリックなインターネットのアドレスに解決される必要があります。
• リダイレクトには従いません。
• HTTP 接続は GET、POST、PUT、PATCH、DELETE、HEAD を受け付け、レスポンスは 1 件あたり最大 1 MiB を返します。エージェントにはレスポンス全体が渡されます。実行の記録には最大 256 KiB までが保持され、短縮した位置に印が付きます。
• MCP サーバーには Streamable HTTP で接続します。エージェントはツールの一覧取得と呼び出しができ、そのほかの MCP の機能は拒否されます。
• ホスト型サービスでは、ワーカーのネットワークから到達できるのは Ephemeral のみです。外部へのリクエストはすべて、接続を通すか、実行に Web アクセスがある場合はそれを通して行われます。