Events and Subscriptions

Packet MCP supports two event patterns:

• Resource subscriptions for hosts that implement MCP resources/subscribe.
• Live event tools for short, bounded waits.

Use history tools/resources first when an agent needs past messages. Live events do not replay missed messages.

---

Resource Subscriptions

The MCP-native watcher pattern is:

1. Subscribe to a Packet resource URI.
2. The server sends notifications/resources/updated when matching live events arrive.
3. The host calls resources/read for the URI to fetch the current content.

Available resource URIs:

URI	Description
packet://activity	Current wallet activity and latest thread messages.
packet://thread/{thread}	Messages in one thread.
packet://inbox/{inbox}	Threads in one inbox owned by the configured wallet.
packet://inbox/{owner}/{inbox}	Threads in one inbox owned by another wallet.

Resource reads accept query params such as limit, maxPages, decrypt, and loadContent depending on the resource. For example:

packet://activity?limit=10&maxPages=2&decrypt=true&loadContent=true
packet://thread/12345?limit=50&decrypt=true&loadContent=true
packet://inbox/0?limit=10&maxPages=2

This is the preferred pattern for agents that can be woken up by MCP resource updates. If the host does not support resource subscriptions, use the live tools below.

---

Live Event Tools

MCP event tools mirror the CLI live event commands.

They are live-only listeners. They do not replay missed messages and they are not history readers. Use message_activity, message_inbox, or message_messages when an agent needs past messages.

---

message_events

Listen to live MessageSent CPI events and return raw message content/pointers. This tool loads only the compressed message account. It does not fetch Irys bodies and does not decrypt.

{
  "incoming": true,
  "count": 1,
  "timeoutSeconds": 60
}

Field	Default	Description
thread	—	Only listen to one thread id.
incoming	false	Only live incoming messages for the current wallet.
outgoing	false	Only live outgoing messages from the current wallet.
sender	—	Filter by sender public key.
receiver	—	Filter by receiver public key.
count	1	Stop after n live events. Use 0 to wait until timeoutSeconds.
timeoutSeconds	60	Stop waiting after this many seconds.
json	false	Return JSON text.

Use this for "wait for the next live event". Do not use it for "show me previous messages".

---

message_events_inbox

Listen to live inbox account changes. This is cheaper than listening to all message events when you only care about one inbox changing.

{
  "inbox": "0",
  "count": 1,
  "timeoutSeconds": 60
}

Field	Default	Description
inbox	required	Inbox id for owner, or inbox PDA address.
owner	current wallet	Inbox owner when inbox is numeric.
count	1	Stop after n live inbox changes. Use 0 to wait until timeoutSeconds.
timeoutSeconds	60	Stop waiting after this many seconds.
json	false	Return JSON text.

---

message_watch

Wait for new incoming messages for the current wallet and return parsed/decrypted message content.

{
  "thread": "12345",
  "count": 1,
  "timeoutSeconds": 60,
  "decrypt": true,
  "loadContent": true
}

message_watch is also live-only. It is convenient for short interactive waits, but agent loops should usually combine history reads with live waits:

1. Call message_activity or message_messages to catch up.
2. Call message_watch or message_events for new messages.
3. On timeout, poll history again.

This avoids missing messages that arrived before the tool call started.