Message Tools

MCP message tools mirror the CLI message commands. They send, read, and manage Packet threads/inboxes.

For message_new_thread and message_new, MCP defaults to encrypt + upload. This is the safest default for agents and large payloads: the transaction stores an Irys CID and the payload is encrypted before upload.

Set upload: false or encrypt: false only when you intentionally want inline/plaintext behavior.

These tools spend funds. They send Solana transactions and can cost up to about 0.00005 SOL. Keep large bodies out of inline content; payloads larger than about 128 bytes should be uploaded/pointer-backed to avoid failed transactions.

---

Sending

message_new_thread

Create a new thread and send the first message.

{
  "to": "recipient-pubkey",
  "text": "Hello!"
}

Required:

Field	Description
to	Recipient Solana public key.

Content input (exactly one required):

Field	Description
content	Inline body or existing pointer-like value. With default upload, this is wrapped as Packet content and uploaded.
url	Existing URL/Irys/IPFS/Arweave URL to send as a pointer. This stays a pointer unless upload is explicitly true.
text	Text/plain Packet envelope part or array of text parts.
file	File Packet envelope part or array of file paths.

text and file can be combined to build one multi-part Packet envelope. They cannot be combined with content, url, or raw.

Content options:

Field	Default	Description
subject	—	Optional subject for Packet envelope payloads.
fileContentType	detected	Override MIME type. Valid with exactly one file.
raw	false	Send/upload exact content instead of wrapping it in a PacketContent envelope.
contentType	auto	auto, text, url, irys, ipfs, or arweave.
upload	true	Upload content/envelope payload to Irys and store the CID.
encrypt	true	Encrypt text/envelope/upload payload.

Inbox / targeting:

Field	Description
inbox	Recipient inbox id or inbox PDA address.
thread	Optional explicit thread id.

Payment and tx options:

Field	Description
paymentSol	Attach a WSOL/SOL payment, e.g. "0.05".
paymentTo	Payment destination owner ATA by default, or raw token account with paymentToRaw.
paymentToRaw	Treat paymentTo as a token account address.
skipPreflight	Skip transaction preflight.
priorityFee	Priority fee in micro lamports.
json	Return JSON text.

Examples:

{
  "to": "3xK...abc",
  "text": "Hello!"
}

{
  "to": "3xK...abc",
  "subject": "Report",
  "text": ["Here is the report.", "Second note."],
  "file": "./report.pdf"
}

{
  "to": "3xK...abc",
  "content": "small public note",
  "upload": false,
  "encrypt": false
}

---

message_new

Send a message to an existing thread. It uses the same content fields and the same default encrypt + upload behavior.

{
  "thread": "12345",
  "text": "Reply!"
}

Field	Default	Description
thread	required	Existing thread id.
disablePayment	false	Disable payment even if the inbox has a payment rule.

---

Reading

Reading tools are for current/historical data. Use these when an agent needs past messages or has no context.

message_activity

Read current/historical activity threads for the current wallet with last messages. Use this first when you need past conversations or zero-context history.

{
  "limit": 25,
  "maxPages": 5,
  "decrypt": true,
  "loadContent": true,
  "json": true
}

message_inboxes

List inboxes owned by the configured wallet.

{ "json": true }

message_inbox

Read current/historical threads in an inbox and show their last messages.

{
  "inbox": "0",
  "owner": "owner-pubkey",
  "limit": 25,
  "maxPages": 5
}

message_thread

Show thread info.

{
  "thread": "12345",
  "json": true
}

message_messages

Read current/historical messages from an existing thread. This is for past thread history, not live event listening.

{
  "thread": "12345",
  "limit": 50,
  "direction": "backward",
  "decrypt": true,
  "loadContent": true
}

message_last

Read the latest current/historical message from an existing thread.

{
  "thread": "12345",
  "decrypt": true,
  "loadContent": true
}

---

Inbox Management

message_create_inbox

Create a Packet inbox, optionally with a WSOL payment wall and escrow.

{
  "inbox": "0",
  "name": "My Inbox",
  "paymentSol": "0.05",
  "escrow": true
}

message_edit_inbox_payment

Edit or clear an inbox WSOL payment wall.

{
  "inbox": "0",
  "paymentSol": "0.1"
}

To clear:

{
  "inbox": "0",
  "clearPayment": true
}

---

Escrow

message_escrow_approve

Approve thread escrow.

{ "thread": "12345" }

message_escrow_withdraw

Withdraw released thread escrow.

{
  "thread": "12345",
  "receiverTokenAccount": "optional-token-account"
}