Pidgeon

npx add-mcp 'https://pidgeon.ai/api/mcp'

Một agent có thể trực tiếp quản lý hộp thư đến Pidgeon: đọc thư, trả lời từ đó, tạo địa chỉ trong đó. Pidgeon giao tiếp bằng Model Context Protocol qua cùng API được mô tả trong tài liệu này — chỉ là một bộ chuyển đổi giao thức, không hơn.

Có hai cách kết nối, nhưng chúng dùng cùng một máy chủ. Bản hosted không cần cài đặt; gói sẽ chạy máy chủ trên máy của bạn.

Bản hosted, tức là một URL

claude mcp add --transport http pidgeon https://pidgeon.ai/api/mcp

Lời gọi đầu tiên trả về 401, rồi client đưa bạn đến Pidgeon để đăng nhập. Bạn chọn những gì client có thể làm — đọc, đọc và gửi, hoặc toàn quyền — và những gì client có thể truy cập: một địa chỉ, hoặc mọi địa chỉ nếu bạn sở hữu tài khoản. Lựa chọn đó trở thành một API key, và client giữ token tương ứng. API key xuất hiện trong Developers → API keys → Connected apps; ngắt kết nối tại đó sẽ có hiệu lực ở lần gọi tiếp theo của client.

Claude's custom connectors, ChatGPT, Grok, Cursor, Codex và VS Code đều dùng cùng URL và đăng nhập theo cùng cách. Mỗi yêu cầu được xử lý độc lập: máy chủ không giữ phiên vì bản thân nó không có trạng thái nào cần lưu.

Với agent không có người ở đó để đăng nhập, hãy gửi key thay thế:

claude mcp add --transport http pidgeon https://pidgeon.ai/api/mcp \
--header "Authorization: Bearer $PIDGEON_API_KEY"

x-api-key cũng hoạt động. Hướng dẫn từng bước cho Cursor, Codex (đọc TOML, không phải JSON) và VS Code; Windsurf và Gemini CLI dùng cùng URL và header.

Trong Grok

Trong Grok, vào Connectors → Custom, dán https://pidgeon.ai/api/mcp rồi đăng nhập ở màn hình chấp thuận; không cần key (hướng dẫn từng bước). Muse của Meta đang được Meta xem xét.

Trong Cursor

Thêm Pidgeon vào Cursor từ danh sách trên cursor.directory, trong đó có máy chủ hosted và skill.

Hoặc tự thêm máy chủ vào ~/.cursor/mcp.json (hoặc .cursor/mcp.json cho một dự án). Chỉ cần URL; Cursor sẽ yêu cầu bạn đăng nhập ở lần gọi đầu tiên:

{
"mcpServers": {
  "pidgeon": {
    "url": "https://pidgeon.ai/api/mcp"
  }
}
}

Với agent không có người ở đó để đăng nhập, hãy thêm "headers": { "Authorization": "Bearer ${env:PIDGEON_API_KEY}" } bên cạnh URL, rồi Cursor sẽ lấy giá trị từ môi trường của bạn.

Codex, VS Code và Gemini CLI

Với Codex, VS Code và Gemini CLI, một lệnh sẽ ghi máy chủ vào tệp riêng của client:

npx -y @pidgeon-ai/mcp init --client codex    # ~/.codex/config.toml
npx -y @pidgeon-ai/mcp init --client vscode   # .vscode/mcp.json
npx -y @pidgeon-ai/mcp init --client gemini   # .gemini/settings.json

Nếu chưa đặt key, lệnh chỉ ghi URL và client sẽ yêu cầu bạn đăng nhập. Nếu đã đặt PIDGEON_API_KEY, lệnh sẽ kiểm tra key trước, rồi yêu cầu client đọc key từ biến đó (Codex, Gemini CLI) hoặc hỏi bạn một lần (VS Code), để key không bao giờ được ghi vào tệp. Lệnh bổ sung vào nội dung hiện có, kể cả chú thích, sao chép tệp bị thay đổi sang <file>.bak, không làm gì ở lần chạy thứ hai và chỉ thay thế mục pidgeon khác khi có --force. --scope user hoặc --scope project chọn tệp còn lại; --print không ghi gì.

Hoặc cài đặt, tức là một gói

PIDGEON_API_KEY=pgn_live_… npx -y @pidgeon-ai/mcp init

Lệnh này kiểm tra key với API trước khi ghi bất cứ thứ gì, đồng thời cho bạn biết key truy cập được những địa chỉ nào — câu hỏi duy nhất mà một khối JSON không thể trả lời, và nếu không thì vấn đề chỉ lộ ra khi model âm thầm gặp lỗi mà bạn không bao giờ thấy. Sau đó, lệnh ghi .mcp.json vào thư mục hiện tại và in ra nội dung đã ghi. Lệnh không bao giờ thay thế mục đã có sẵn: --force sẽ làm việc đó, còn --print hiển thị cấu hình mà không ghi gì; hãy dùng lệnh này nếu client lưu cấu hình ở một nơi khác.

Key được tham chiếu từ môi trường thay vì ghi vào tệp, nên bạn có thể commit cấu hình mà không để lộ thông tin xác thực:

{
"mcpServers": {
  "pidgeon": {
    "command": "npx",
    "args": ["-y", "@pidgeon-ai/mcp"],
    "env": { "PIDGEON_API_KEY": "${PIDGEON_API_KEY}" }
  }
}
}

Claude Desktop hoặc bất kỳ MCP client nào khác đều dùng cùng khối cấu hình. Để chạy trực tiếp máy chủ, chủ yếu hữu ích khi muốn theo dõi quá trình khởi động:

PIDGEON_API_KEY=pgn_live_… npx -y @pidgeon-ai/mcp

PIDGEON_BASE_URL trỏ máy chủ đến nơi khác ngoài production; tùy chọn này chỉ hữu ích nếu bạn tự chạy Pidgeon.

Key là toàn bộ cơ chế kiểm soát quyền truy cập

Cách này trao cho model một API key — do bạn tạo hoặc được cấp khi đăng nhập. Không có gì trong gói quyết định những gì có thể truy cập: giới hạn quyền của chính key và các địa chỉ được cấp quyền cho key sẽ quyết định toàn bộ, ở phía máy chủ, chính xác như với mọi bên gọi khác. Ở đây không có bộ quy tắc thứ hai để bạn cấu hình sai.

Vì vậy, hãy cấp cho agent key có phạm vi quyền hẹp nhất mà nó cần. Key được tạo tại read không bao giờ có thể gửi thư, dù được cấp quyền truy cập hộp thư rộng đến đâu — xem Authentication để biết phạm vi quyền của key có nghĩa là gì và cách thu hẹp phạm vi đó. Agent chỉ làm nhiệm vụ phân loại thư nên chỉ có key cho phép đọc; khi đó, việc agent có thể gửi nhầm thứ gì đáng xấu hổ hay không sẽ không còn phụ thuộc vào prompt.

Phạm vi quyền của key là ảnh chụp tại thời điểm cấp các địa chỉ cho key, nên địa chỉ được tạo sau đó sẽ không nằm trong phạm vi này.

Những gì máy chủ cung cấp

Đủ cả 42 công cụ, được đọc từ danh sách của chính máy chủ để trang này luôn cập nhật:

Công cụ	Chức năng	Endpoint
list_addresses	Các địa chỉ mà thông tin xác thực này có thể truy cập.	GET /identities
create_address	Tạo địa chỉ để agent sử dụng.	POST /identities
get_address	Một địa chỉ, theo id.	GET /identities/{id}
list_threads	Các cuộc hội thoại trong một địa chỉ, mới nhất trước.	GET /threads
get_thread	Một cuộc hội thoại, theo id.	GET /threads/{id}
list_messages	Các thư trong một cuộc hội thoại, cũ nhất trước — nội dung cần đọc trước khi trả lời.	GET /messages
search_messages	Tìm kiếm toàn văn trên mọi địa chỉ mà thông tin xác thực này có thể truy cập, xếp hạng theo mức độ liên quan.	GET /messages/search
send_message	Gửi thư từ địa chỉ mà thông tin xác thực này được phép gửi thư.	POST /messages
get_message	Một thư, theo id, kèm nội dung, các header được lưu giữ và những gì bản ghi của miền gửi đã xác minh — authentication.spf\, .dkim\, .dmarc\; giá trị null nghĩa là không có báo cáo, chứ không phải xác minh thất bại.	GET /messages/{id}
await_message	Chờ thư đến một địa chỉ — chẳng hạn sau khi bạn gửi biểu mẫu đăng ký — rồi trả về thư cùng extracted.codes\ và extracted.links\: mã xác minh và liên kết xác nhận được ưu tiên hiển thị trước.	GET /messages/await
reply_to_message	Người nhận, tiêu đề và chuỗi hội thoại được lấy từ thư đang trả lời, nên bạn chỉ cần cung cấp nội dung.	POST /messages/{id}/reply
forward_message	Chuyển tiếp một thư đến người không có tên trong danh sách người nhận, kèm tệp đính kèm, từ địa chỉ đã nhận thư đó.	POST /messages/{id}/forward
create_draft	Soạn thư nhưng không gửi, để người khác đọc và gửi — dùng khi được yêu cầu chuẩn bị thư trả lời để duyệt.	POST /drafts
get_draft_approval	Trạng thái của một thư gửi đang chờ duyệt, theo draft\_id\: pending\ cho đến khi có người chấp thuận hoặc từ chối trên dashboard, sau đó là approved\ (thư đã được gửi và message\_id\ là thư đó), rejected\, hoặc expired\ nếu sau 24 giờ vẫn chưa có quyết định.	GET /drafts/{id}/approval
list_drafts	Mọi bản nháp trong một địa chỉ, mới nhất trước, kèm người nhận và nội dung — để bạn có thể quay lại hoàn tất bản nháp.	GET /drafts
get_draft	Một bản nháp theo id: người gửi, người nhận, tiêu đề, nội dung và tệp đính kèm.	GET /drafts/{id}
update_draft	Thay đổi các trường bạn truyền vào và giữ nguyên phần còn lại; null\ xóa tiêu đề hoặc nội dung.	PATCH /drafts/{id}
delete_draft	Xóa một bản nháp và hủy lịch gửi nếu thư đã được lên lịch.	DELETE /drafts/{id}
read_attachment	Nội dung của một tệp đính kèm — CSV, log, JSON, tệp lịch, PDF, Word .docx\ hoặc Excel .xlsx\.	GET /attachments/{id}/text
update_thread	Ai đang phụ trách cuộc hội thoại và tiến độ hiện tại.	PATCH /threads/{id}
update_message	Đánh dấu sao cho một thư hoặc chuyển thư vào archive\, spam\ hoặc trash\.	PATCH /messages/{id}
list_send_rules	Danh sách cho phép và chặn của một địa chỉ, cùng chính sách gửi áp dụng cho địa chỉ đó.	GET /identities/{id}/send-rules
list_receive_rules	Các quy tắc quyết định thư nào được chuyển đến một địa chỉ — từ chối, đánh dấu spam, chuyển vào thùng rác, lưu trữ hoặc chuyển vào hộp thư đến, theo người gửi hoặc miền — cùng với receive\_policy\ của địa chỉ đó.	GET /identities/{id}/receive-rules
list_folders	Mọi thư mục của một địa chỉ cùng số lượng thư trong từng thư mục.	GET /mailboxes
list_folder	Một thư mục của một địa chỉ, mới nhất trước, mỗi hàng là một cuộc hội thoại — list\_threads\ cho biết những cuộc hội thoại nào tồn tại; công cụ này cho biết chúng được lưu ở đâu và hiển thị thế nào trong danh sách.	GET /mailboxes/{folder}
list_changes	Mọi thay đổi trong một hộp thư đến kể từ sync\_cursor\, bao gồm thư mới, để agent chạy lâu không phải đọc lại cả thư mục chỉ để tìm một thư mới.	GET /mailboxes/changes
list_events	Mọi sự kiện trên tất cả địa chỉ mà thông tin xác thực này có thể truy cập — thư đã nhận, đã gửi, đã chuyển phát, bị trả lại hoặc được phân loại.	GET /events
list_labels	Nhãn thuộc về một địa chỉ, không phải workspace; vì vậy cùng một tên trên ba địa chỉ sẽ là ba nhãn với ba id khác nhau.	GET /labels
create_label	Một nhãn trên một địa chỉ.	POST /labels
apply_label	Nhãn phải thuộc cùng địa chỉ với cuộc hội thoại — dùng list\_labels\ cho địa chỉ đó để lấy đúng id.	POST /threads/{id}/labels
remove_label	Gỡ một nhãn khỏi một cuộc hội thoại.	DELETE /threads/{id}/labels
list_pods	Pod là vùng chứa dành cho một khách hàng của bạn: pod chứa các địa chỉ và miền, và **thư gửi từ pod đó có uy tín gửi thư riêng**, nên một khách hàng không thể làm ảnh hưởng khả năng chuyển phát thư của khách hàng khác.	GET /pods
create_pod	Vùng chứa dành cho một khách hàng, với uy tín gửi thư riêng.	POST /pods
get_metrics	Số thư đã gửi, chuyển phát, bị trả lại, bị từ chối, bị khiếu nại, đã nhận và bị đánh dấu spam trong khoảng thời gian days\ — được tính từ nhật ký sự kiện nên bao gồm cả kết quả mà nhà cung cấp báo cáo sau đó.	GET /metrics
get_calendar	Lịch của một địa chỉ, theo id\ của địa chỉ đó: múi giờ mặc định và số sự kiện trong lịch.	GET /identities/{id}/calendar
update_calendar	Múi giờ được gán cho sự kiện nếu sự kiện không chỉ định múi giờ, dưới dạng tên IANA như Europe/Lisbon\.	PATCH /identities/{id}/calendar
get_agenda	Nội dung trên lịch của một địa chỉ trong khoảng từ after\ đến before\ (ngày giờ ISO 8601), theo thứ tự thời gian bắt đầu; mỗi ngày của sự kiện lặp lại được liệt kê riêng.	GET /identities/{id}/calendar/agenda
get_calendar_event	Một sự kiện theo eventId\ trên lịch của địa chỉ id\: thời gian, mô tả, địa điểm, lịch lặp lại và người tham dự cùng câu trả lời của họ.	GET /identities/{id}/calendar/events/{eventId}
create_calendar_event	Thêm sự kiện vào lịch của địa chỉ id\.	POST /identities/{id}/calendar/events
update_calendar_event	Thay đổi một sự kiện trên lịch: chỉ thay đổi các trường bạn truyền vào, giữ nguyên phần còn lại.	PATCH /identities/{id}/calendar/events/{eventId}
delete_calendar_event	Xóa sự kiện khỏi lịch của địa chỉ id\.	DELETE /identities/{id}/calendar/events/{eventId}
respond_to_invitation	Trả lời lời mời họp nhận được qua thư, theo id\ của thư: accepted\, declined\ hoặc tentative\, kèm comment\ tùy chọn.	POST /messages/{id}/invitation/respond

Mỗi công cụ tương ứng với endpoint bên cạnh trong tài liệu tham khảo, với cùng các trường hợp từ chối. Nếu key không được phép dùng một công cụ, công cụ sẽ thất bại giống như API, với đúng câu thông báo mà API sẽ trả về.

Tìm kiếm bao quát mọi địa chỉ mà key có thể truy cập, trừ khi bạn chỉ định một địa chỉ; mỗi kết quả cho biết địa chỉ tìm thấy kết quả đó.

Những gì công cụ này không làm

Đây không phải môi trường chạy agent và cũng không đưa ra quyết định nào. Pidgeon không có ý kiến về model bạn chạy hay những gì model được phép kết luận — giống như quan điểm trong Threads and hand-off về phần còn lại của sản phẩm. Nếu agent gặp bế tắc, chuyển cuộc hội thoại cho một người là trạng thái của chuỗi hội thoại, không phải tính năng của gói này.