MCP サーバー · Ephemeral ドキュメント

Ephemeral は Model Context Protocol (MCP) サーバーを提供します。Claude や ChatGPT、エディタ内のエージェントなどの AI エージェントが、実行の開始、結果の待機、ワークフローの参照を直接行えます。REST API と同じ API キー、ロール、予算、検証が適用されます。さらに、ワークフローの保存と削除、スケジュールの管理、ファイルの一覧表示もでき、エージェントが定期ジョブを最初から最後まで設定できます。

OAuth でログインする

MCP の認可に対応しているクライアントは、URL https://app.ephemer.al/mcp だけで接続できます。クライアントは、サーバーの 401 応答と保護リソースメタデータから Ephemeral のログイン先を見つけて自身を登録し、ログイン、組織の選択、承認を行うページを開きます。その後は有効期間 1 時間のアクセストークンとリフレッシュトークンを保持するため、取り消すまで再度の承認は求められません。

アクセスは、選択した組織に対して、承認したロール (member または admin) で付与されます。admin を付与できるのは組織のオーナーと管理者だけで、スケジュールの作成・変更・削除を除き、メンバーで足ります (それには admin が必要です)。
トークンが有効なのは Ephemeral の API (https://app.ephemer.al) だけで、他のサービスでは使えません。
接続したアプリは、アカウントページの「承認済みアプリ」でいつでも確認、取り消しできます。
認可サーバーのメタデータは https://ephemer.al/.well-known/oauth-authorization-server にあります。クライアントは PKCE (S256) を使う必要があります。

セルフホストのインストールでは API キーのみ使えます。

API キーで接続する

ダッシュボードの「キー」で API キーを作成します。実行、ワークフロー、ファイルにはメンバーキーで足ります。エージェントにスケジュールの作成・変更・削除もさせる場合は管理者キーを使ってください。サーバーは https://app.ephemer.al/mcp にあり、Streamable HTTP トランスポートで通信します。すべてのリクエストでキーをベアラートークンとして送ります。

Claude Code

サーバーを一度追加すれば、以後のすべてのセッションで使えます。

ターミナル

claude mcp add --transport http ephemeral https://app.ephemer.al/mcp \
  --header "Authorization: Bearer $EPHEMERAL_API_KEY"

Cursor、VS Code など HTTP に対応したクライアント

多くのクライアントは MCP 設定でヘッダー付きのリモートサーバーを受け付けます。

JSON

{
  "mcpServers": {
    "ephemeral": {
      "url": "https://app.ephemer.al/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Claude Desktop

Claude Desktop は設定ファイル (claude_desktop_config.json) からローカルサーバーを起動します。mcp-remote ブリッジを使うとリモートサーバーに接続し、ヘッダーを渡せます。

JSON

{
  "mcpServers": {
    "ephemeral": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.ephemer.al/mcp", "--header", "Authorization:${EPHEMERAL_AUTH}"],
      "env": { "EPHEMERAL_AUTH": "Bearer YOUR_API_KEY" }
    }
  }
}

セルフホスト環境では、同じエンドポイントがエンジンの URL (例: https://ephemeral.example.com/mcp) で提供され、その環境のキーを使います。

ツール

各ツールには、クライアントがモデルに示す入力スキーマがあり、結果はテキストと構造化コンテンツの両方で返ります。REST API がエラーとして返す失敗は、同じメッセージのツールエラーとして返ります。

ツール	内容
`create_run`	プロンプトまたは保存済みワークフローから実行を開始します。入力、モデル、ファイル、接続、Web アクセス、シェル、タイムアウト、コスト上限、ゼロデータ保持を指定できます。キュー済みの実行を返します。idempotency_key を使うと再試行しても安全です。
`get_run`	実行を取得します。ステータス、出力、エラー、コスト、請求の確定待ちかどうかを含みます。請求の確定待ちの間、cost_micros は暫定値で、最終コストより高いことが多く、結果には cost_final: false が付きます。cost_final が true になってからコストを伝えてください。
`wait_for_run`	実行の完了まで最大 60 秒待ち、実行を返します。まだ実行中なら再度呼び出します。実行が終わったあとは請求の確定も待つため、返されるコストは最終値です（cost_final: true）。その前に時間切れになった場合、コストは暫定値です。
`list_runs`	実行を新しい順に一覧します。ステータスの絞り込みとカーソルを使えます。
`cancel_run`	完了していない実行をキャンセルします。
`list_workflows`	保存済みワークフローを、description、input_schema、output_schema とともに一覧します。エージェントはプロンプトを読まずに、各ワークフローの入力と出力を確認できます。
`get_workflow`	ワークフローの定義を 1 件取得します。認証情報は含まれません。
`list_models`	モデルを検索します。コンパクトな一覧（ID、名前、コンテキスト長、100 万トークンあたりの入力・出力価格、ゼロデータ保持）と総数を返します。引数: query（ID または名前の一部、大文字小文字は区別しません）、limit（既定 25、最大 100）、zero_data_retention（対応するモデルのみ）、model（1 つのモデルの詳細）。
`list_connections`	実行で使える保存済みの接続。URL やシークレットは含まれません。
`save_workflow`	ワークフローを作成するか、同名のものを置き換えます。プロンプト、モデル、ファイル、接続、Web アクセス、シェル、タイムアウト、ゼロデータ保持を指定できます。接続は保存済みの接続への参照のみです。説明と、入力・出力の JSON Schema も指定できます。
`delete_workflow`	保存済みのワークフローを削除します。
`list_schedules`	スケジュールを一覧します (ワークフローで絞り込み可)。次回の開始と直近の結果も含まれます。
`get_schedule`	スケジュールを 1 件読み取ります。
`create_schedule`	保存済みワークフローを cron 形式のスケジュールとタイムゾーンで開始します。入力とコスト上限は任意です。管理者キーが必要です。
`update_schedule`	スケジュールを変更するか、enabled で一時停止・再開します。管理者キーが必要です。
`delete_schedule`	スケジュールを削除します。管理者キーが必要です。
`preview_schedule`	cron 式を検証し、保存せずに次の 5 回の開始時刻を返します。
`run_schedule`	スケジュールのワークフローをすぐに開始し、キュー済みの実行を返します。
`list_files`	組織に保存されたファイルを一覧します (読み取り専用)。

試してみる

エンドポイントは JSON-RPC 2.0 メッセージを POST で受け取ります。通常はクライアントが行いますが、curl では次のようになります。

ターミナル

curl -sS https://app.ephemer.al/mcp \
  -H "Authorization: Bearer $EPHEMERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"create_run","arguments":{"prompt":"Summarize https://example.com","web":true,"max_cost_micros":200000}}}'

ワークフローを保存してスケジュールする

エージェントは 2 回の呼び出しで、タスクを定期ジョブにできます。まず次の引数で save_workflow を呼びます。

JSON

{
  "name": "weekly-report",
  "prompt": "Summarize last week's support tickets from the helpdesk connection and list the three biggest themes.",
  "connections": { "helpdesk": { "ref": "helpdesk", "allowed_methods": ["GET"] } },
  "timeout_seconds": 600
}

次に create_schedule (管理者キー) を呼びます。ここでは毎週月曜日の 09:00 (マドリード時間) です。事前に preview_schedule で次の開始時刻を確認できます。

JSON

{
  "workflow": "weekly-report",
  "cron": "0 9 * * 1",
  "timezone": "Europe/Madrid",
  "max_cost_micros": 500000
}

ロール

ほとんどのツールは、メンバーキーが REST API で既にできる操作です。スケジュールのツールも REST API と同じルールに従います。スケジュールの参照、プレビュー、即時実行はメンバーキーで可能ですが、create_schedule、update_schedule、delete_schedule には管理者キーまたはオーナーキーが必要で、それ以外はツールエラー (ステータス 403) になります。キーの作成、接続の変更、請求の管理を行うツールはありません。キーは組織も決めます。実行はその組織に請求され、実行履歴に表示されます。

安全性

キーがなければ何も実行されません。初期化とツール一覧はキーなしでも取得できます（内容は公開済みです）。ツールの呼び出しには必ず有効なキーが必要で、キーがなければ 401 になります。
OAuth のアクセストークンは 1 時間で失効し、1 つの組織と承認されたロールに限定され、アカウントページからいつでも取り消せます。
予算が適用されます。すべての実行にコスト上限があり (max_cost_micros または組織の既定値)、API と同じ残高チェックが行われます。
接続は保存済みの参照です。エージェントは組織が保存した接続を名前で指定するだけで、allowed_methods (たとえば GET のみ) や allowed_tools で絞り込めます。URL や認証情報を渡すことはできません。
実行ごとにゼロデータ保持を指定できます。その出力は最初の取得で解放されます。
受け付けるのは POST のみです。セッションも、サーバーからのメッセージもありません。

プロトコル

プロトコルバージョン 2025-11-25、2025-06-18、2025-03-26 に対応し、クライアントが要求したバージョンで応答します。GET と DELETE は 405 を返します。ディスカバリー文書は /.well-known/mcp/server-card.json で公開されています。