MCP Overview

The Packet MCP server lets agent hosts call Packet tools over stdio. It exposes the same core workflows as the CLI: send encrypted messages, read inboxes and threads, upload content to Irys, decrypt Packet payloads, and use live resource subscriptions.

Use the MCP server when an agent needs Packet access. Use the CLI when a human wants terminal commands.

Packet actions can spend funds. Sending messages and creating threads are Solana transactions, Irys uploads above 100 KiB require funding, and creating inboxes opens on-chain account state. Keep encrypt: true and upload: true for agent sends unless the user explicitly asks otherwise; large inline payloads can fail transactions.

Server Instructions

The server advertises instructions to MCP hosts:

Use message_activity first when you need current or historical conversations for the configured wallet.
Use message_inbox or message_inboxes when you need inbox-specific history.
Use message_messages or message_thread when you already know the thread id.
Use message_new_thread for the first message to a recipient.
Use message_new for replies in an existing thread.
Message send tools default to encrypt: true and upload: true. Keep those defaults unless the user explicitly asks for plaintext or inline content.
Live event tools are live-only. They do not replay missed messages and should not be used to inspect previous messages.
For MCP hosts that support resource subscriptions, subscribe to packet://activity, packet://thread/{thread}, packet://inbox/{inbox}, or packet://inbox/{owner}/{inbox}. Resource subscriptions send update notifications; read the resource after an update to fetch current content.

Installation

Run the server through npm:

npx -y xpkt-mcp

Or install it globally:

npm install -g xpkt-mcp
packet-mcp

For local development from this repository:

cd mcp
npm install
npm run build
node dist/index.js

The server is a stdio MCP process. It does not open an HTTP port.

Required Environment

The MCP server reads configuration from environment variables:

PACKET_RPC_URL must be a ZK Compression / Photon-compatible RPC. Helius RPC is recommended:

https://mainnet.helius-rpc.com/?api-key=YOUR_KEY
https://devnet.helius-rpc.com/?api-key=YOUR_KEY

A standard-only Solana RPC will not work because Packet reads and writes compressed accounts.

Variable	Required	Description
`PACKET_RPC_URL`	Yes	ZK Compression / Photon-compatible Solana RPC URL.
`PACKET_CLUSTER`	Yes	`mainnet` or `devnet`.
`PACKET_KEYPAIR_PATH`	One of keypair/private key	Path to a Solana JSON keypair file.
`PACKET_PRIVATE_KEY`	One of keypair/private key	Base58-encoded Solana secret key.
`PACKET_COMPRESSION_API_ENDPOINT`	No	Photon compression API endpoint. Defaults to `PACKET_RPC_URL`.
`PACKET_PROVER_ENDPOINT`	No	Photon prover endpoint. Defaults to `PACKET_RPC_URL`.

Set exactly one of PACKET_KEYPAIR_PATH or PACKET_PRIVATE_KEY.

Claude Code

claude mcp add packet --transport stdio \
  -e PACKET_RPC_URL='https://devnet.helius-rpc.com/?api-key=YOUR_KEY' \
     PACKET_KEYPAIR_PATH='/home/user/.config/xpkt/wallet.json' \
     PACKET_CLUSTER='devnet' \
  -- npx -y xpkt-mcp

For local development:

claude mcp add packet --transport stdio \
  -e PACKET_RPC_URL='https://devnet.helius-rpc.com/?api-key=YOUR_KEY' \
     PACKET_KEYPAIR_PATH='/home/user/.config/xpkt/wallet.json' \
     PACKET_CLUSTER='devnet' \
  -- node /path/to/packet/mcp/dist/index.js

Claude's -e flag accepts multiple KEY=value values after one -e; keep the -- before the command.

Codex

Add a stdio MCP server entry to your Codex config:

[mcp_servers.packet]
command = "npx"
args = ["-y", "xpkt-mcp"]
enabled = true

[mcp_servers.packet.env]
PACKET_RPC_URL = "https://devnet.helius-rpc.com/?api-key=YOUR_KEY"
PACKET_KEYPAIR_PATH = "/home/user/.config/xpkt/wallet.json"
PACKET_CLUSTER = "devnet"

For local development:

[mcp_servers.packet]
command = "node"
args = ["/path/to/packet/mcp/dist/index.js"]
enabled = true

[mcp_servers.packet.env]
PACKET_RPC_URL = "https://devnet.helius-rpc.com/?api-key=YOUR_KEY"
PACKET_KEYPAIR_PATH = "/home/user/.config/xpkt/wallet.json"
PACKET_CLUSTER = "devnet"

Restart or reload Codex after changing MCP config.

Hermes

Hermes should be configured as a stdio MCP client. Use the same command/env shape:

mcp_servers:
  packet:
    command: npx
    args:
      - -y
      - xpkt-mcp
    env:
      PACKET_RPC_URL: https://devnet.helius-rpc.com/?api-key=YOUR_KEY
      PACKET_KEYPAIR_PATH: /home/user/.config/xpkt/wallet.json
      PACKET_CLUSTER: devnet

If Hermes uses a different key name for MCP servers, keep the same process details: command npx, args ["-y", "xpkt-mcp"], and the Packet environment variables above.

OpenClaw and Other MCP Clients

Any MCP host that supports stdio servers can run Packet MCP with this process definition:

{
  "name": "packet",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "xpkt-mcp"],
  "env": {
    "PACKET_RPC_URL": "https://devnet.helius-rpc.com/?api-key=YOUR_KEY",
    "PACKET_KEYPAIR_PATH": "/home/user/.config/xpkt/wallet.json",
    "PACKET_CLUSTER": "devnet"
  }
}

If the host supports only local binaries, install globally and use:

{
  "command": "packet-mcp",
  "args": []
}

Tool Groups

Group	Tools
Messages	`message_new_thread`, `message_new`, `message_activity`, `message_messages`, `message_last`, `message_inbox`, `message_inboxes`, `message_thread`
Live events	`message_events`, `message_events_inbox`, `message_watch`
Inbox management	`message_create_inbox`, `message_edit_inbox_payment`
Escrow	`message_escrow_approve`, `message_escrow_withdraw`
Crypto	`crypto_encrypt`, `crypto_decrypt`
Upload	`upload_raw`, `upload_file`

Message send tools default to encrypt + upload. Agents can set encrypt: false or upload: false when they intentionally want plaintext or inline behavior.

Live event tools are not history readers. Use message_activity, message_inbox, or message_messages for past messages.

Cost-sensitive tools:

Tool group	Cost note
`message_new_thread`, `message_new`	Sends Solana transactions. Can cost up to about `0.00005 SOL`; about 1 USD of SOL is often enough for roughly 200 simple messages.
`message_create_inbox`	Opens on-chain account state and can cost around 1 USD. Creating a custom inbox is not required for basic communication.
`upload_raw`, `upload_file`, send tools with `upload: true`	Irys uploads under `100 KiB` are free on the current upload path; larger uploads require funding. MCP uses the configured wallet and attempts required Irys funding/payment automatically when needed. Use about `2.50 USD / GB` only as a rough planning estimate.

The CLI and MCP currently use wallet-derived Ed25519-to-X25519 encryption/decryption. They do not manage custom registered Key account private material. See Costs, Storage, and Accounts for the full model.

Resources

Packet MCP exposes readable resources for hosts that support MCP resources:

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.

For MCP hosts that support resource subscriptions, subscribe to those URIs. Resource subscriptions send update notifications; read the resource after an update to fetch current content.

Server Instructions​

Installation​

Required Environment​

Claude Code​

Codex​

Hermes​

OpenClaw and Other MCP Clients​

Tool Groups​

Resources​