agentmail-mcp

AgentMail MCP

ホスト型の Streamable HTTP サーバーを優先して使用してください。

https://mcp.agentmail.to/mcp

これにより、ローカルの Node.js プロセスや、公開済みのローカル MCP パッケージのリリース頻度の遅さを回避できます。

Claude Code、Codex、Cursor

OAuth を使用してください。設定に空の API キーを入れないでください。

{
  "mcpServers": {
    "agentmail": {
      "type": "http",
      "url": "https://mcp.agentmail.to/mcp"
    }
  }
}

Claude Code には、直接インストールする方法もあります。

claude mcp add --transport http agentmail https://mcp.agentmail.to/mcp

初回接続時に、ブラウザーでのサインインを完了してください。複数の組織を利用する OAuth セッションでは、サーバーの組織選択ツールを使用できます。

Claude.ai、Claude Desktop、ChatGPT コネクター

これらのアプリでは、サーバーをコネクターとして追加し、ブラウザーで OAuth を完了します。API キーは不要です。

• Claude.ai と Claude Desktop： Settings → Connectors → Add custom connector の順に選択します。名前を AgentMail にし、URL に https://mcp.agentmail.to/mcp を設定してから、Connect をクリックし、console.agentmail.to でサインインします。
• ChatGPT： Settings → Security and login → Developer mode をオンにします（ワークスペースプランでは、事前に管理者の許可が必要です）。次に ChatGPT Plugins を開き、+ をクリックして、URL に https://mcp.agentmail.to/mcp を設定し、OAuth を選択して、console.agentmail.to でサインインします。チャットで Developer mode の + メニューから AgentMail を選択します。

Claude.ai で追加したコネクターは Claude Code と同期されません。Claude Code にも別途追加してください。

クライアントごとの設定

クライアントの MCP 設定ファイルに、同じ type: http のサーバーエントリーを追加します。

• Cursor：.cursor/mcp.json
• VS Code：.vscode/mcp.json
• Windsurf：MCP 設定ファイル
• Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%/Claude/claude_desktop_config.json（Windows）

認証オプション

• OAuth — ブラウザーでサインインします。リモート MCP OAuth に対応するクライアント向けです。認証情報を付けず、URL のみを使用してください。
• x-api-key ヘッダー — OAuth に対応していないクライアントに推奨されます（下記を参照）。
• Authorization: Bearer <am_...> ヘッダー — 一部のクライアントで必要となる、別のヘッダー形式です。
• apiKey クエリパラメーター — 対応していますが、推奨しません。キーがログや履歴に残らないよう、ヘッダーを優先してください。

OAuth を完了できない Streamable HTTP クライアントでは、AGENTMAIL_API_KEY をエクスポートして、ヘッダーとして送信してください。

{
  "mcpServers": {
    "agentmail": {
      "type": "http",
      "url": "https://mcp.agentmail.to/mcp",
      "headers": {
        "x-api-key": "${env:AGENTMAIL_API_KEY}"
      }
    }
  }
}

ヘッダー認証が利用できる場合は、クエリー文字列に認証情報を含めないでください。

ツールの検出

MCP クライアントはホスト型ランタイムからツールカタログとスキーマをリアルタイムで取得します。コピーしたツール数を当てにしないでください。同じ生成済みコントラクトが https://github.com/agentmail-to/agentmail-mcp/blob/main/mcp-manifest.json で公開されています。ホスト型ランタイムとこのマニフェストを、正式なカタログとして扱ってください。OAuth セッションでは、基本セットに加えて、組織選択用のツールが表示されることがあります。

カタログにはメール以外の機能も含まれています。コネクターでできることを尋ねられた場合は、次のグループを案内してください。

• 受信トレイ、スレッド、メッセージ、下書き、添付ファイル、許可／ブロックリスト — 関連するアクションスキルのメールワークフローです。
• AgentID アプリとアカウント — list_apps、search_apps、get_app、connect_app、authorize_inbox、list_accounts を使って、サードパーティーのアプリ（たとえば「Firecrawl にアカウントを作成」）でエージェント用のアカウントを作成し、各受信トレイにすでにアカウントがあるかを確認できます。authorize_inbox は、アプリの Sign in with AgentID ページで開始したサインインを、そのページに表示される認証トークンを使って完了します。AgentID に登録されていないアプリでも利用できます。カタログ内のアプリはスラッグ（firecrawl）で指定でき、list_apps ではカテゴリーで絞り込めます。このワークフローには agentmail-agentid スキルを使用してください。
• エージェントのサインアップ — agent_attach_human と agent_verify により、未検証のエージェント組織に設けられた制限を解除できます。

Stdio 互換性

stdio のみ対応するクライアントでは、サポート対象の npm または PyPI の agentmail-mcp パッケージを使用してください。どちらも同じホスト型ランタイムへの軽量な stdio ブリッジです。ツールを動的に検出し、独自の AgentMail ツールロジックは持ちません。

検証

1. プラグインをインストールした後、クライアントを再起動するか、新しいセッションを開きます。
2. クライアントで MCP のステータスを確認し、認証を完了します。
3. 読み取り専用のスモークテストとして list_inboxes を呼び出します。AgentID のツールが公開されていることを確認するには、list_apps を呼び出します。
4. 読み取り、書き込み、破壊的なツールのアノテーションが、想定どおりの承認動作を引き起こすことを確認します。

トラブルシューティング

• 404 が返される場合、通常は URL に /mcp が含まれていません。
• 公開済みマニフェストにあるツールやパラメーターがセッションに表示されない場合（たとえば list_apps に category がない場合）、ホストされたサーバーがカタログの変更を通知しないため、セッションには接続時点のツール一覧が保持されています。新しいセッションを開始するか、コネクターに再接続してください。
• API キー認証で「Invalid API key」または 401 が返される場合、通常はキーが間違っている、取り消されている、必要な権限がない、または AGENTMAIL_API_KEY がクライアントプロセスから利用できないことを意味します。
• OAuth で「Unauthorized」または 401 が返される場合、通常はサインインが未完了か、セッションの有効期限が切れています。apiKey クエリパラメーターを削除し、クライアントでブラウザー経由の OAuth フローを完了してください。
• am_ で始まるキーの値全体を使用し、用途に合う範囲のうち最も限定された組織、ポッド、または受信トレイのスコープを選んでください。
• stdio のみをサポートするクライアントについては、上記の「Stdio Compatibility」を参照してください。