e2a — email for AI agents について
e2a は AI エージェント向けのメールゲートウェイで、エージェントごとに独立した受信箱を提供し、送信前のメールに対する人によるレビューも任意で行えます。SPF/DKIM で検証された送信に対応しており、エージェントに直接メールを扱わせたい開発者を想定したホスト型 MCP サーバーです。
主な機能
- 01エージェントごとの独立したメールボックス
- 02メールの送信、受信、返信
- 03送信メールに対する任意の人によるレビュー(HITL)
- 04OAuth 2.1 と Bearer API キーによる認証
- 05認証情報のスコープに応じたツールの表示
- 06署名付き Webhook 配信
活用シーン
- 01AI エージェントが専用の受信箱でメールを送受信
- 02エージェントが作成したメールを送信前に確認
- 03Claude Desktop や Cursor にメール機能を追加
MCP 対応
https://api.e2a.dev/mcp で提供されるホスト型のリモート MCP サーバーとして、Streamable HTTP 経由でメール、レビュー、ドメイン、コンタクトに関するツールを MCP クライアントに公開します。認証情報のスコープによって利用可能なツールが決まります。
設定
リモートサーバーはインストール不要です。クライアントを選んで設定をコピーするか、ワンクリックで導入できます。
https://api.e2a.dev/mcpclaude mcp add --transport http dev-e2a https://api.e2a.dev/mcp{"mcpServers":{"dev-e2a":{"type":"http","url":"https://api.e2a.dev/mcp"}}}Cursor で開く{"servers":{"dev-e2a":{"type":"http","url":"https://api.e2a.dev/mcp"}}}VS Code で開く{"mcpServers":{"dev-e2a":{"type":"http","url":"https://api.e2a.dev/mcp"}}}{"mcpServers":{"dev-e2a":{"serverUrl":"https://api.e2a.dev/mcp"}}}コマンドはターミナルで実行し、JSON は各クライアントの MCP 設定に貼り付けて再起動します。認可が必要なサーバーは初回接続時にログインを求めます。
https://api.e2a.dev/mcp認証が必要ツール
詳細
@e2a/mcp-server
e2a 用の Model Context Protocol サーバーです。MCP 対応の AI エージェントがそれぞれ独自のメール受信トレイを持ち、送信、受信、返信できるほか、(任意で)送信前に保留中のメールを確認できます。
Google ADK、LangChain、OpenAI Agents SDK、Claude Desktop、Cursor、Cline、その他あらゆる MCP ホストで動作します。
接続
e2a の MCP サーバーはホストされています。MCP ホストを Streamable HTTP エンドポイントに接続します。
https://api.e2a.dev/mcp
認証方法は 2 つあります。
- OAuth 2.1(対話型ホストに推奨) — e2a をコネクターとして追加し、ブラウザーで認証します。設定にキーを貼り付ける必要はありません。
- Bearer API キー(プログラムによる利用/セルフホスト) — e2a ダッシュボードの API キーを
Authorization: Bearer <e2a API key>ヘッダーで送信します。
エージェントスコープの認証情報では、エージェントがサーバー側で解決されます。アカウントスコープの呼び出し元は、各ツール呼び出しでエージェントの email を渡します。
クイックスタート
Google ADK(Python)
import os
from google.adk.agents import Agent
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
root_agent = Agent(
model="gemini-flash-latest",
name="e2a_agent",
instruction="Help the user manage their email. Reply to threads with `reply_to_message` to preserve threading headers.",
tools=[
McpToolset(
connection_params=StreamableHTTPConnectionParams(
url="https://api.e2a.dev/mcp",
headers={
"Authorization": f"Bearer {os.environ['E2A_API_KEY']}",
},
timeout=30,
),
),
],
)
LangChain(Python)
langchain-mcp-adapters を使用します。
import os
from langchain.agents import create_agent
from langchain_mcp_adapters.client import MultiServerMCPClient
client = MultiServerMCPClient({
"e2a": {
"transport": "http",
"url": os.getenv("E2A_MCP_URL", "https://api.e2a.dev/mcp"),
"headers": {
"Authorization": f"Bearer {os.environ['E2A_API_KEY']}",
},
},
})
tools = await client.get_tools()
agent = create_agent(
"anthropic:claude-sonnet-4-6",
tools=tools,
system_prompt="Reply with reply_to_message; pending_review is accepted, so do not retry it.",
)
OpenAI Agents SDK(Python)
import os
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp
async with MCPServerStreamableHttp(
name="e2a",
params={
"url": os.getenv("E2A_MCP_URL", "https://api.e2a.dev/mcp"),
"headers": {
"Authorization": f"Bearer {os.environ['E2A_API_KEY']}",
},
"timeout": 30,
},
cache_tools_list=True,
max_retry_attempts=3,
) as e2a:
agent = Agent(name="e2a_agent", mcp_servers=[e2a])
result = await Runner.run(agent, "Reply to the latest unread email politely.")
Claude Desktop/Cline/Cursor
ホストの設定ファイル(claude_desktop_config.json、cline_mcp_settings.json など)に、e2a をリモート MCP サーバーとして追加します。
{
"mcpServers": {
"e2a": {
"url": "https://api.e2a.dev/mcp",
"headers": {
"Authorization": "Bearer YOUR_E2A_API_KEY"
}
}
}
}
OAuth コネクターに対応しているホストでは、代わりに https://api.e2a.dev/mcp をコネクターとして追加し、ブラウザーで認証できます。キーを貼り付ける必要はありません。
ツール
このサーバーは、エージェント、メッセージ、Human-in-the-Loop 承認、添付ファイル、ドメイン、イベント、Webhook、API キー、連絡先/アウトリーチ、メールテンプレート(ベータ版)、抑止リスト、外部送信アクセスリクエスト(ベータ版)にわたる最大 80 個のツールを公開します。
利用できるツールは認証情報のスコープによって異なります。 エージェントスコープの認証情報では、実行時/受信トレイ用の 21 個のツール(メッセージの読み取り、送信、返信、復元、エージェントごとのアウトリーチ)を利用できます。アカウントスコープの認証情報では、さらに 59 個の管理/設定ツール(エージェント、ドメイン、Webhook、イベント、テンプレート、API キー、連絡先、抑止リスト、送信アクセスの管理に加え、HITL レビューの検出と承認/拒否。これはアカウント所有者の操作であり、エージェント自身による承認はできません)も利用でき、合計 80 個になります。
すべてのツールには MCP アノテーション(readOnlyHint/destructiveHint/idempotentHint)が付いているため、ホストは読み取りを自動承認し、破壊的な操作にフラグを立てられます。
以下の表では、よく使われるツールを紹介しています。MCP ホストのツール一覧には、スコープで許可されたツールと各ツールの説明が表示されます。
ID
| ツール | 説明 |
|---|---|
whoami | 認証済みアカウントの ID(ユーザー、スコープ、プラン/上限)を取得します。エージェントスコープの認証情報の場合は、紐付けられたエージェントのアドレスも取得します。この情報を返すデプロイ環境では、追加のベータ版 sending_access オブジェクトも含まれます(「外部送信アクセス」を参照)。 |
list_agents | エージェントの受信トレイを一覧表示します。deleted:true を渡すと、30 日間のゴミ箱を一覧表示します。(管理者/アカウントスコープ。) |
get_agent | 完全なメールアドレスを指定して、1 つのエージェント受信トレイを取得します。 |
create_agent | 所有する認証済みドメイン、またはデプロイ環境の共有ドメインに、完全なメールアドレスを指定して新しいエージェントを登録します。配信「モード」はありません。受信メールは常に list_messages(ポーリング)または create_webhook のサブスクリプションで利用できます。(管理者/アカウントスコープ。) |
restore_agent | ソフト削除されたエージェントとその設定を復元します。(管理者/アカウントスコープ。) |
Webhook の配信には署名が付いています。必ず検証してください。 プッシュ配信はトップレベルのリソース(
create_webhook)であり、エージェントごとのモードではありません。e2a は Webhook の署名シークレット(create_webhook/rotate_webhook_secretから一度だけ返されます)を使って、すべての Webhook 配信に HMAC 署名します。ハンドラーでは、すべてのリクエストの署名を検証する必要があります。e2a SDK のconstructEvent(rawBody, signatureHeader, secret)は署名を検証し、型付きイベントを 1 回の呼び出しで返します(署名が不正な場合は例外をスローします)。Webhook を使わずにlist_messagesでポーリングすることもできます。
メッセージ
send_at / scheduled_at による予約送信はベータ版であり、安定版として宣言される前に変更される可能性があります。
外部送信アクセス(ベータ版)。 外部送信が制限されているデプロイ環境では、アカウントは共有 ID を使用して、認証済みのアカウントメールアドレスと同じアカウント内のエージェントの受信トレイにのみ送信できる場合があります。その他の To/Cc/Bcc 受信者を指定した
send_message/reply_to_message/forward_message(または非推奨のsend_email)呼び出しは、送信全体をexternal_sending_not_enabled(403)で拒否します。キューには何も追加されず、同一の呼び出しを再試行しても成功しません。whoamiのsending_accessオブジェクトには現在の状態(enforcement_applies、shared_external_approved、paid_external_sending_entitled、owner_recipient_verified)と、デプロイ環境で制限を解除できる方法を示すavailable_unlocksが報告されます。operator_approvalは常に利用できます。verified_domain(自分の認証済みドメインから送信)とpaid_entitlement(有料プラン)は、一覧にある場合のみ利用できます。ホステッドサービスで表示されるのはoperator_approvalのみです。承認を申請するには、request_sending_accessを一度だけ呼び出してください(アカウントスコープ。エラーのrecovery_urlにあるダッシュボードからも利用できます)。申請が保留中に再送信すると同じ申請が返され、rate_limited(30 日あたり 3 件)になった場合は再試行しないでください。オペレーターが判断し、その結果はアカウント所有者にメールで通知されます。get_sending_access_requestで現在の状態を確認できます。承認を付与できる MCP ツールはありません。
ツール 説明 request_sending_accessベータ版。外部送信アクセスについてオペレーターの審査を受けるため、申請を 1 件提出します( use_case、recipients、expected_daily_volume)。状態を変更する操作です。凍結されたアカウントではaccount_read_onlyで拒否されます。(管理者/アカウントスコープ)get_sending_access_requestベータ版。アカウントの最新の申請とその state(pending/approved/declined)を返します。読み取り専用です。(管理者/アカウントスコープ)
| ツール | 説明 |
|---|---|
send_message | 新しいメールを送信します。即時のキュー追加では status: accepted が返され、将来の時刻を指定した send_at では status: scheduled と scheduled_at が返されます。審査保留の場合は status: pending_review が返されます。いずれも永続的に成功した結果のため、再送信しないでください。 |
reply_to_message | メッセージに返信します。エージェントが受信したメッセージには送信者へ返信し、エージェントが送信したメッセージには元の受信者へのスレッドを続けます。スレッドの連続性を保つために In-Reply-To / References を維持し、send_message と同じ省略可能な send_at を受け付けます。 |
forward_message | メッセージを新しいスレッドに転送し、既存の添付ファイルもデフォルトで引き継ぎます。send_message と同じ省略可能な send_at を受け付けます。 |
list_messages | メールの一覧を取得します。ゴミ箱を一覧表示するには deleted:true を指定します。read_status(unread / read / all)と、予約語と競合しない from_ で送信者を絞り込みます。カーソルでページネーションします(入力:cursor + limit、出力:next_cursor)。 |
delete_message | メッセージをゴミ箱に移動します(約 30 日間は復元可能です)。confirm: true が必要です。メッセージ単位の完全削除は、意図的に MCP 経由では公開されていません。REST API/SDK を使用してください。(受信トレイ全体の消去は、アカウントスコープで delete_agent の permanent: true を指定すると利用できます。) |
restore_message | 論理削除されたメッセージを復元し、保持期間のカウントを再開します。 |
get_message | 1 件のメッセージの完全な本文、ヘッダー、添付ファイルのメタデータを取得します。 |
get_attachment | 1 件の添付ファイルのメタデータと有効期間の短い download_url を取得します(バイトデータは別途取得します)。小さなファイル(≤256 KB)では、inline: true を指定すると base64 の data が返されます。 |
update_message_labels | メッセージのラベルを追加または削除します。 |
MCP のメッセージ出力では、REST のメッセージ読み取りベータ版にある thread_id フィールドは意図的に省略され、スレッドのフィルターやエンドポイントも追加されません。list_conversations / get_conversation は引き続き呼び出し元が所有する conversation_id のアプリケーションビューであり、RFC のメールスレッドの列挙ではありません。メールのワイヤー上のトポロジーを維持するには、元のメッセージ ID を指定して reply_to_message を使用してください。
Human-in-the-loop による承認
list_reviews/get_review は、アカウント単位のすべての保留を表示します。送信承認を待つ送信メールの下書きと、スクリーニングゲートによって保留されている受信メッセージが対象です。
email.review_requested webhook は、どちらの方向にも追加のプッシュ通知を送信し、同じ message_id を含みます。
approve_review/reject_review ツールは方向に応じて処理を分岐します。受信メッセージの保留を承認すると、エージェントの受信トレイに解放されます(送信は行われず、下書きも作成されず、上書きフィールドは無視されます)。拒否すると破棄され、エージェントに届くことはありません。
| ツール | 説明 |
|---|---|
list_reviews | アカウント全体で人間によるレビューを待っている受信・送信メッセージを、有効期限が早い順に一覧表示します。 |
get_review | 保留中のメッセージ全体(本文、宛先、該当する場合はスクリーニングのコンテキスト)を取得します。 |
approve_review | 送信:保留中のメッセージを送信します。必要に応じてレビュー担当者による編集(件名/本文/宛先)を反映できます。受信:スクリーニングの保留をエージェントの受信トレイに解放します(上書きは無視されます)。アカウント単位であり、エージェントによる自己承認はできません。 |
reject_review | 送信:保留中のメッセージを破棄します。受信:スクリーニングの保留を解除し、エージェントに届かないようにします。任意の reason は監査用に保存されます。アカウント単位です。 |
ドメイン
| ツール | 説明 |
|---|---|
register_domain | カスタム送信ドメインを登録し、公開する MX + TXT DNS レコードを返します。(管理者/アカウント単位。) |
API キー
すべて管理者/アカウント単位です。create_api_key で作成できるのはエージェント単位のキーのみです。このキーは1つの受信トレイに紐付けられ、そのエージェントとしてのみ操作できます。アカウント単位(ワークスペース管理者)のキーは MCP 経由では作成できません。人間が介在するダッシュボードまたは生の API から作成してください。
| ツール | 説明 |
|---|---|
list_api_keys | アカウントの API キーを一覧表示します。メタデータのみが対象です(シークレットは作成時に一度だけ表示されます)。 |
create_api_key | 受信トレイに紐付けられた新しいエージェント単位のキーを作成します。キーのプレーンテキストは一度だけ返されるため、すぐに保存してください。 |
delete_api_key | キーを永久に失効させます(confirm: true が必要です)。 |
連絡先(ベータ版)
アカウントがやり取りする相手(list_contacts/get_contact/
create_contact/update_contact/delete_contact、管理者/アカウント単位)と、エージェントごとの連絡先へのアプローチ状況(ステージ、次のアクション、返信/抑制に関する情報。list_outreach_contacts/get_outreach_contact/
set_outreach_contact/delete_outreach_contact。アカウント単位、または紐付けられた受信トレイに対するエージェント単位の認証情報で利用できます)を扱います。インポートでは何も送信されません。連絡先の ID を記録し、送信せずにアプローチ対象へ登録します。
| ツール | 説明 |
|---|---|
list_contacts/get_contact | アカウントの連絡先を一覧表示(出所/インポートバッチ/作成期間で絞り込み可能)するか、アドレスを指定して1件を取得します。 |
create_contact/update_contact/delete_contact | 連絡先の ID を作成、一部更新(if_match を使った etag による保護)、または削除します。削除すると、その連絡先のすべてのエージェント別アプローチ行も削除されます。連絡先を削除しても抑制情報は削除されません。 |
import_contacts | 行から連絡先を一括インポートし、必要に応じてエージェントのアプローチ対象に登録します。 |
delete_contact_import | インポートバッチを取り消し、変更されていない連絡先と、そのバッチで作成された登録を削除します。 |
list_outreach_contacts/get_outreach_contact | エージェントが対応している連絡先を一覧表示または取得し、サーバーが導出した返信/配信情報も表示します。 |
set_outreach_contact | エージェントのアプローチ対象に連絡先を登録するか、エージェントが所有するフィールド(ステージ、次のアクション)を更新します。 |
delete_outreach_contact | エージェントのアプローチ対象から連絡先を解除します。連絡先とその抑制情報は保持されます。 |
抑制リスト
2 つのスコープにおける受信者のブロックリストで、どちらも管理者/アカウントスコープです(サーバーはすべてのリストでエージェントスコープの認証情報を拒否します。エージェントはブロックリストを読み取ったり編集したりしてはなりません)。アカウントリストにはハードバウンスと苦情が自動的に登録され、すべてのエージェントからの送信に適用されます。エージェントリスト(ベータ版)には、特定の送信エージェント 1 つに対する配信停止/手動ブロックが登録されます。
| ツール | 説明 |
|---|---|
list_suppressions | アカウント全体の抑制リストを表示します(アドレス、ソース bounce/complaint/manual、理由、ソースメッセージ ID)。 |
delete_suppression | アカウント全体で受信者の抑制を解除します。confirm: true が必要です。配信可能であると確認済みのアドレスにのみ使用してください。実際にバウンスしたアドレスを削除すると、送信者の評価が損なわれます。 |
list_agent_suppressions | 1 つのエージェントでブロックされている受信者(unsubscribe/manual)を表示します。 |
create_agent_suppression | 1 つのエージェントに対する手動ブロックを冪等に追加します。他のエージェントは引き続きそのアドレスにメールを送信できます。 |
delete_agent_suppression | 特定のエージェントスコープのブロックのみを削除します。ブロックが配信停止を表している可能性があるため、confirm: true が必要です。 |
テンプレート(ベータ版)
{{variable}} の補間に対応した再利用可能なメールテンプレート(Mustache のフラットなサブセットで、ループ/セクションはありません。不足している変数は空文字列としてレンダリングされます)と、読み取り専用の組み込みスターターテンプレートカタログ(welcome、verify-code、password-reset、receipt、agent-status、daily-digest、approval-request)を提供します。テンプレートを使って送信するには、send_message の template_id/template_alias と template_data を指定します(リテラルの subject/body とは相互に排他的です)。すべてのテンプレート管理ツールは管理者/アカウントスコープです。ベータ版のため、テンプレートが安定版と宣言される前に仕様が変更される場合があります。
| ツール | 説明 |
|---|---|
list_templates / get_template | アカウントに保存されているテンプレートを一覧表示します(概要行)。get_template は本文のソース全体を返します。 |
create_template | リテラルのソースからテンプレートを作成します。または、from_starter を指定してスターターをそのままコピーします。 |
update_template / delete_template | テンプレートを編集(変更された部分を再解析)または削除します。 |
validate_template | ソースをドライランします。解析エラー、test_data に基づくレンダリング済みプレビュー、suggestedData のプレースホルダーを返します。 |
list_starter_templates / get_starter_template | スターターカタログを参照します。詳細表示には本文のソース全体と変数ごとのメタデータが含まれます。 |
エラー
ツール呼び出しが失敗すると、すべて isError: true の MCP 結果が返され、エラーが 2 つの形式で表現されます。
-
structuredContent— 機械的に分岐処理できる形式です。テキストではなく、こちらを基に分岐してください。{ "code": "domain_not_verified", "retryable": false, "status": 403, "request_id": "req_abc123", "retry_after_seconds": 30, "details": { "field": "…" } }フィールド 有無 意味 code常にあり API エラーエンベロープに含まれる、安定した snake_case トークンです(例: domain_not_verified、rate_limited、message_not_pending)。MCP レイヤー自体が発生させたエラー(引数の不正/不足、confirm:trueガード)にはinvalid_requestが含まれます。retryable常にあり 再試行によって成功する可能性が十分にある場合(レート制限、5xx、接続失敗)は trueです。statusAPI エラーのみ API レスポンスの HTTP ステータスです( 0は接続レベルの失敗)。リクエストが行われなかった場合(MCP レイヤーでの検証エラー)はありません。request_id利用可能な場合 サーバーのリクエスト ID です。サポートへの問い合わせに記載してください。 retry_after_seconds利用可能な場合 再試行可能なエラーに対するバックオフの目安です。 details利用可能な場合 エンベロープから得られる、フィールド単位の構造化された詳細です(サイズ超過時は省略されます)。 -
content(テキスト) — 人間が読み取れる形式で、変更されず安定しています。API エラーの場合はe2a error [<code>] (retryable)?: <message>、MCP レイヤーのエラーの場合はe2a error: <message>です。このテキストを解析する既存のエージェントは引き続き動作しますが、新しい連携ではstructuredContentを読み取ることを推奨します。
成功した結果には影響ありません(テキストブロック内の JSON です。リスト取得ツールは、次のページがある場合、ドメイン名の付いた配列と next_cursor を返します)。
HTTP サーバーの運用
セルフホストする場合は、mcp/Dockerfile またはリポジトリの docker-compose.yaml にある mcp サービスを使って HTTP トランスポートを実行します。日々の運用(SLO、障害クラス、相関関係)については
docs/runbooks/mcp-server.md を参照してください。このセクションでは、設定とインターフェースについて説明します。
環境変数
| 変数 | デフォルト | 説明 |
|---|---|---|
PORT | 3000 | リッスンするポートです。 |
E2A_API_URL | 必須 | このトランスポートがベアラートークンを転送する(およびレディネスを確認する)e2a API サーバーのベース URL です。正式名称です。E2A_URL と E2A_BASE_URL は従来の別名で、非推奨警告付きで引き続き受け付けます。デフォルト値はありません。3 つのいずれも設定されていない場合、ユーザーのベアラートークンをオペレーターの api.e2a.dev に黙って転送するのではなく、プロセスの起動を拒否します(ConfigError、終了コード 2)。 |
MCP_ALLOWED_HOSTS | MCP_PUBLIC_URL から導出、未設定の場合は 必須 | 許可する Host のカンマ区切りリストです(DNS リバインディング対策)。リストにない Host を指定したリクエストが /mcp またはディスカバリー文書に送信されると、421 を返します。比較前にポートを除去します。固定のデフォルト値はありません。未設定の場合は MCP_PUBLIC_URL のホストを使用し、どちらも設定されていない場合は起動を拒否します。 |
MCP_PUBLIC_URL | 未設定 | この MCP サーバーに外部から到達するための URL です。RFC 9728 の保護リソースメタデータと 401 の WWW-Authenticate チャレンジで、そのまま使用します。また、設定されている場合は MCP_ALLOWED_HOSTS のデフォルト値としても使用します。フロントプロキシから見た URL が受信 Host と異なる場合に設定します(ローカル開発の場合は http://localhost:8765)。 |
MCP_AUTHORIZATION_SERVER_URL | $E2A_API_URL | 保護リソースメタデータで通知する認可サーバーの URL です。ベアラー転送先がコンテナー内部向けで、OAuth クライアントがホストから AS にアクセスする必要がある場合に上書きします。 |
E2A_TRUST_PROXY | loopback | Express の trust proxy 設定です。ディスカバリー URL でどのホップの X-Forwarded-* ヘッダーを信頼するかを指定します。true/false、ホップ数、またはプリセット/サブネットのリストを指定できます。 |
MCP_RESOLVE_TIMEOUT_MS | 5000 | ベアラーをプリンシパルに解決する whoami プローブのタイムアウト上限(ミリ秒)です。正の整数で指定し、再試行は最大 1 回です。タイムアウトまたはバックエンドの 5xx が発生した場合、最小権限のエージェントスコープでフェイルクローズしてリクエストを処理します。この結果はキャッシュされず、auth_resolution result=fallback としてログに記録されます。 |
MCP_SESSION_IDLE_MS | 300000 | 従来の名称です。セッションではなく、解決キャッシュのサイズを指定します。 キャッシュ済みのベアラー→プリンシパル解決の TTL(ミリ秒)です。このトランスポートはステートレスで、タイムアウトするセッションはありません。 |
MCP_MAX_SESSIONS | 500 | 従来の名称です。セッションではなく、解決キャッシュのサイズを指定します。 キャッシュするベアラー→プリンシパルの最大エントリ数です。上限を超えると最も古いエントリが削除されます。キャッシュミス時に発生するのは whoami の呼び出し 1 回であり、切断ではありません。 |
ヘルスエンドポイント
以下の 3 つはすべて認証不要です。
-
GET /healthz— バックエンドには一切アクセスせず、プロセスの生存状態のみを確認します:{ "ok": true }。生存確認プローブに設定します。 -
GET /readyz— レディネスを確認します:{E2A_API_URL}/api/healthに対してプローブを実行します(タイムアウトは 2 秒、結果は 10 秒間キャッシュされるため、スクレイピングするインスタンス群がプローブの集中を引き起こすことはありません)。到達可能な場合は 200{ "ok": true, "checks": { "api": "ok" } }を返します。到達できない場合は 503{ "ok": false, "checks": { "api": "unreachable" }, "request_id": "…" }とRetry-After: 10(失敗キャッシュの TTL)を返します。レディネス確認プローブに設定します。 -
GET /metrics— Prometheus のテキスト形式で出力します。出力例:mcp_http_requests_total{route="mcp",status_class="2xx"} 1523 mcp_http_request_duration_seconds_bucket{route="mcp",le="0.5"} 1480 mcp_auth_resolutions_total{result="cache_hit"} 1490 mcp_tool_executions_total{tool="list_messages",outcome="ok"} 412 mcp_readyz_checks_total{result="ok"} 60 mcp_resolve_cache_entries 7ルートラベルは次の範囲に制限されています:
mcp | healthz | readyz | metrics | discovery | other。
構造化ログ
stderr に出力される 1 行の JSON(GCE 形式の severity/event/message と各種フィールド)です。リクエスト単位のイベントには request_id(レスポンスの X-Request-Id)が含まれます。auth_resolution(result、duration_ms、scope?。invalid/fallback は WARNING)、http_request(route、method、status、duration_ms。healthz/readyz/metrics への成功したプローブ/スクレイピングのトラフィックは計測されますが、ログには記録されません)、tool_execution(tool、outcome、duration_ms、error_code?)、terminal_error です。Bearer トークンはログに記録されません。解決キャッシュのキーには SHA-256 フィンガープリントが使われます。^[A-Za-z0-9_-]{1,64}$ に一致する受信 X-Request-Id はそのまま使用され、それ以外の場合、サーバーは mcpreq_<12hex> を生成します。この ID はすべてのレスポンスに含まれますが、バックエンド API には転送されません。
クライアントの再試行ポリシー
失敗したツール呼び出しは structuredContent を返します(エラーを参照)。code/retryable/retry_after_seconds に基づいて処理を分岐します。retryable: true のエラーのみ、指数バックオフとジッターを使って最大約 3 回まで再試行してください。4xx は再試行しないでください(401 → 再認証、421 → URL を修正)。送信ツールでの accepted、scheduled、pending_review は成功の結果です。再試行しないでください。送信エージェント自身のアドレスへの未来の send_at は、直接ループバックが適用される場合、400 invalid_request を返します。レビュー保留が優先され、スケジュールは破棄されます。トランスポートはステートレスなので、中断後の「再接続」は単に再 POST するだけです。MCP クライアントはこれを自動的に行います。
リンク
ライセンス
Apache-2.0
コメント
AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。