MCPメール受信箱でAIエージェントに確認コードを読ませる（APIキー不要・無料）

REST APIでは満たせない、エージェントに必要なもの

このサイトにはREST APIがあり、それを組み込むプログラマーであれば何の問題もありません。しかしエージェントはそうはいきません。リファレンスを開いて3つのエンドポイントのどれが必要かを判断し、正しいクエリ文字列を持つリクエストを手作業で組み立てる、ということができないのです。エージェントはサーバーに何ができるかを尋ね、機械可読なスキーマを受け取り、その一つを呼び出します。

そのため、このサービスができることはすべて、ツールとしてもう一度公開されています。全部で6つあり、呼び出しの間で管理すべき状態もありません。

サーバーはinitializeに対しても、短い説明文を返します。ほとんどのクライアントはこれをそのままモデルに渡します。そのため、誰かがプロンプトに書き込むまでもなく、エージェントはこのサービスの目的とただ一つの注意点をあらかじめ知った状態で動き出せます。

クライアントを1行で接続する

エンドポイントはURL一つだけで、公開ドメインを使う分には登録も何も必要ありません。Claude Desktop、Claude Code、Cursor、Continue、OpenAI Agents SDK、その他このプロトコルを話せるものなら、どのMCPクライアントでも設定の形は同じです。

{"mcpServers":{"grabmail":{"url":"https://grabmail.io/mcp"}}}

トランスポートはStreamable HTTPです。JSON-RPC 2.0を運ぶPOSTが1回、返ってくるJSONが1回、開いたままのストリームはありません。そのため、エージェントを一切介さずに、ターミナルだけで全体を確認できます。

curl -sX POST https://grabmail.io/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

人に尋ねる前にサーバーを自動的に探しにいくクライアントは、そのドメインの/.well-known/mcp.jsonを見つけます。そこには同じエンドポイントとそのトランスポートが記載されています。

サインアップの一連の流れを、4回のツール呼び出しで

ほとんどのエージェントに必要なのはこの手順だけで、それ以上のものはありません。

1. create_inboxを呼ぶ。アドレス、エイリアス、ドメイン、そしてどちらを渡すべきかを伝える注記が返ってきます。この時点では何も作成されていません。メールボックスは、最初のメッセージが届いた瞬間に存在し始めます。
2. フォームにエイリアスを入力する。サインアップ先のサービスは、メールボックスに届くけれども中を読むことはできない、有効なアドレスを手に入れます。
3. そのアドレスでwait_for_messageを呼ぶ。タイマーを仕込むのではなく、送信した直後に呼びます。これはブロッキング呼び出しであり、エージェント自身がループを書いてポーリングする必要はありません。
4. メッセージからコードを読み取る。待機の応答に本文全体が含まれているため、通常は2回目の呼び出しは不要です。read_messageが必要になるのは、以前に届いたものを読み返すときだけです。

wait_for_messageがメールより先に返ってくる理由

エージェントを実用的にしているのはこのツールであり、同時に挙動が意外に思われがちなツールでもあるので、少し時間をかけて説明します。呼び出しはこのような形です。

curl -sX POST https://grabmail.io/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":
        {"name":"wait_for_message",
         "arguments":{"address":"demo.5kuqarzuch@grabmail.io",
                       "subject_contains":"code"}}}'

最大25秒間ブロックします。その間に何も届かなくても失敗にはなりません。ありのままの応答を返し、もう一度呼び出すよう求めてきます。

{
  "timed_out": true,
  "waited_seconds": 25,
  "message": null,
  "note": "Nothing arrived yet. Call wait_for_message again ..."
}

なぜ上限を設けているのか

待機している1秒ごとに、サーバー側のワーカーは眠っているだけの状態になり、しかもその数には上限があります。5分も続きうる待機を許せば、1つのエージェントが、他の100件が必要としている枠を占有し続けることになります。25秒という長さは、どのクライアントのデフォルトタイムアウトにも収まる範囲でもあるため、クライアント側が諦めるより前に呼び出しが返ります。

同時に待機できるのは8件まで

それを超えると、ツールは即座にtimed_outとその旨の注記を返します。知らないまま他の7件のエージェントの後ろに並ばされるより、出直すよう伝えられるほうがましです。

フィルタリングで、無関係なメールに待機を終わらせない

from_containsとsubject_containsを指定すると、その間に届く他のメールを待機は無視するようになります。メールボックスに既に何か入っている場合はsince_idを渡してください。既に見た最新のidを渡せば、本当に新しいメールだけが呼び出しを満たします。

渡すのはエイリアス、確認するのはアドレス

ここにあるすべてのメールボックスには、12文字からなる2つ目のアドレスがあります。同じメールボックスに配信はできますが、そこから読み出すことはできません。この違いは、人よりもエージェントにとってはるかに重要です。エージェントは、渡されたものを見つけたフィールドに深く考えずに貼り付けてしまうからです。

そのためcreate_inboxは、アドレスを一つ返して終わり、という作りにはなっていません。両方を返し、どちらがどちらかを示すnext_stepも一緒に返します。エージェントは自分自身のツール結果を読むので、その指示は、ループの中の誰も読めないドキュメントページに置かれるのではなく、必要な場所に届きます。

エージェント自身の指示文に何を書くか

ツール自体の説明が十分に整っているため、能力の高いモデルなら指示がなくても正しく振る舞います。次の5行を加えれば、「たいてい正しい」が「確実に正しい」に変わります。

• サインアップ1件につきアドレス1つ。あらゆる場所で同じアドレスを使い回さないでください。1つのメールボックスに6つのサービス分のメールが集まれば、エージェントは6件の確認メールを区別しなければならなくなり、しかも1回の漏えいで全部が露出します。
• 渡すのは常にエイリアスで、アドレスは決して渡さない。ツールの返り値にも書かれてはいますが、明示的に伝えておく価値があります。
• 送信した直後にwait_for_messageを呼ぶこと。timed_outが返っても失敗とはみなさず、もう一度呼びます。2〜3回は普通のことです。
• メールボックスが新規でない場合はsince_idを渡すこと。渡さないと、古いメッセージが待機の条件を満たしてしまい、エージェントが1時間前に期限切れになったコードを読んでしまいます。
• コードを使い終えたら、メッセージを削除する。必須ではありません。どのみち5日ですべて消えるからです。ただし、これで窓口を早く閉じられますし、呼び出しが1回増えるだけで、副作用もありません。

指示文としてまとめると、だいたいこのくらいの長さになります。

メールアドレスが必要になったら、create_inboxを呼び、返ってきたエイリアスを渡してください。
アドレスそのものは渡さないでください。フォームを送信した直後に、そのアドレスで
wait_for_messageを呼んでください。timed_outが返ってきても、それは正常な動作です。
何も失われていないので、もう一度呼んでください。メールボックスに既に何か入っていた場合は
since_idを渡してください。コードを使い終えたら、メッセージを削除してください。

作り込む前に知っておくべき上限

どれも隠されたものではなく公開されており、上位プランで緩和されるものもありません。

送信用のエンドポイントもツールもありません。このサービスは受信専用であり、そのおかげで認証なしのメールボックスがスパムリレーになることを防いでいます。そのため、人に返信する必要があるエージェントには、どこか別の場所に本物のメールボックスが必要です。

フォームが公開ドメインを拒否するとき

多くのサービスは使い捨てメールドメインのリストを保持しており、ここにある3つの公開ドメインもそこに含まれています。エージェントから見ると、これは渡されたばかりのアドレスをフォームが拒否する、あるいはもっと悪いことに、受け付けたのに何も送られてこない、という形で現れます。

根本的な答えは、自分が所有するドメインを使うことです。MXレコードを1件追加するだけで、そのドメイン上のすべてのアドレスがここのメールボックスになります。このサイトのどこにも表示されないため誰のリストにも載らず、しかも同じ6つのツールがそのまま使えます。唯一の例外はcreate_inboxで、これは公開ドメイン上でアドレスを生成するためのツールだからです。エージェントは単にyou-pick-it@your-domainを使い、そのアドレスでwait_for_messageを呼ぶだけです。

あなたのドメイン用のMXレコード10 smtp.grabmail.ioコピー

詳しい手順はこちら。レコードの内容、それを公開することで何が証明されるか、そしてパスワードのないメールボックスの正直な限界について解説しています。

エージェントにさせてはいけないこと

ここは正直に言っておくべき部分であり、半日を無駄にしないための部分でもあります。

• 復元が必要になるようなものには使わないこと。お金、本人確認、仕事に関わるものはすべて対象です。メールボックスは5日後には空になり、アドレスを知っている人なら誰でも読めます。来年そこに送られたパスワード再設定メールは、誰にも届かないか、あるいは自分以外の誰かに届きます。
• 第二要素として使わないこと。パスワードのないメールボックスは、要素にはなり得ません。
• プライベートな用途には使わないこと。私たちがそれを読んでいるからではなく、そこで唯一の秘密であるはずのアドレスを、エージェントがログや会話履歴、コミットメッセージにそのまま書き残してしまうことが十分にあり得るからです。
• 大量利用には使わないこと。エージェントが何百ものアカウントを開く行為は、まさにあらゆるブロックリストが存在する理由そのものであり、公開ドメインが他の全員のために拒否されるようになる、最も早い道でもあります。

本来の用途どおりに使えば——エージェントと、本当に頼まれた作業との間に立ちはだかる確認ステップとして——これは、エージェントを確実に止めてしまうその一段階を取り除いてくれます。

質問