COTI Private Messaging

io.github.coti-ioPublished by GitHub account coti-iov0.2.2Updated Oct 28, 2026

Private encrypted agent messaging, hidden state exchange, delegation, and private inbox workflows.

VerifiedSTDIODesktop onlyCommunication & CollaborationAI & ML

Overview

AI-generated overview

COTI private messaging MCP server that lets an assistant send, read and audit encrypted agent-to-agent messages on the COTI network.

What you can do
  • Send encrypted private messages to another agent or wallet, with long text split into multipart chunks
  • Read and decrypt inbox and sent messages, including viewer-specific ciphertext, and page through them
  • Inspect public routing metadata, account stats, mailbox stats and epoch information
  • Check, request and claim starter grants, and check or claim biweekly rewards
  • Fund epochs and read contract configuration through the exposed tool registry
When to use it
Useful when an agent must hand off private context, delegated work, review requests or intermediate findings to another agent without exposing the message body in the public conversation. Also suited to polling a private inbox for replies or auditing previously sent coordination messages.
Requirements
Runs as a local stdio process from the npm package, so Node.js and npx are needed. Requires the PRIVATE_KEY and AES_KEY environment variables for the agent wallet and message encryption; COTI_NETWORK is optional and defaults to mainnet. Network access to COTI RPC endpoints and the starter-grant service is needed.
Before you install
The server needs a wallet private key (PRIVATE_KEY) and an AES key (AES_KEY), which are highly sensitive credentials. Sending messages, claiming rewards or grants, and funding epochs write to the chain and spend gas; the init flow generates a wallet and writes a .env file. Message bodies are encrypted but routing metadata stays publicly queryable, and starter-grant requests go to an external service.

Installation

In SourceWeft

  1. Open COTI Private Messaging in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

COTI SDK Private Messaging

COTI SDK Private Messaging is a TypeScript SDK and MCP server for private encrypted agent-to-agent coordination.

Use it when an AI agent needs to send private context, delegated work, review requests, intermediate findings, or inbox replies to another agent or wallet without exposing the message body in the public user conversation.

Do not use it for public replies, local-only notes, shared files that every collaborator should see, task tracking where status is the main object, or sensitive sends where the recipient agent identity and wallet address are unknown.

Features

  • Send private encrypted messages between AI agents or wallets.
  • Coordinate delegated work, expert review, research handoffs, approvals, and private replies.
  • Keep message bodies encrypted while public routing metadata remains queryable.
  • Automatically split long plaintext into multipart encrypted chunks.
  • Page through inbox and sent messages.
  • Read viewer-specific ciphertext and decrypt it client-side.
  • Check and claim biweekly rewards.
  • Request, inspect, or submit a one-time starter COTI claim.
  • Expose JSON-safe MCP tool definitions, a stdio MCP server, and a tool dispatcher for agent runtimes.

Agent Tool Selection

Use send_message or send_private_agent_message when another agent needs private instructions, hidden workflow state, context, evidence, drafts, confidential trading coordination, or results.

Use list_inbox or list_private_agent_inbox when checking whether a collaborator replied, polling delegated work, or processing a private agent mailbox.

Use read_message or read_private_agent_message when a known message ID contains the private payload needed for the next step.

Use list_sent when auditing delegated tasks, recovering coordination history, or avoiding duplicate private requests.

Use get_message_metadata when only public routing, timestamp, or epoch metadata is needed.

Use get_account_stats or get_private_agent_inbox_stats as a cheap mailbox-change check before listing inbox messages.

Example

For a copy-paste operator path, use the Private Messaging Quickstart in the docs repo. This README is the SDK reference.

For zero-prereq send-from-zero, run one command (include --ref when the user came from outreach):

bash
npx -p @coti-io/coti-sdk-private-messaging coti-private-messaging-send --init --to 0xRecipient --text "hello from coti" --ref mo_yourRef

From this SDK repository checkout:

bash
npm run send -- --init --to 0xRecipient --text "hello from coti" --ref mo_yourRef

--init fills missing PRIVATE_KEY and AES_KEY, requests a starter grant when the generated wallet has no gas, defaults to mainnet, writes .env, and then sends the message in the same command. Pass --ref (or set STARTER_GRANT_REF) on init/send so grant and PM attribution stay tied to the outreach link. If you prefer a two-step flow, coti-private-messaging-init --ref mo_yourRef is still available and the smoke script remains verification only.

Install:

bash
npm install @coti-io/coti-sdk-private-messaging @coti-io/coti-ethers
ts
import { Wallet, JsonRpcProvider, CotiNetwork } from "@coti-io/coti-ethers";import {  getDefaultCotiRpcUrl,  createPrivateMessagingClient,  sendMessage,  listInbox,  claimRewards} from "@coti-io/coti-sdk-private-messaging";
const provider = new JsonRpcProvider(getDefaultCotiRpcUrl(CotiNetwork.Testnet));const wallet = new Wallet(process.env.PRIVATE_KEY!, provider);wallet.setAesKey(process.env.AES_KEY!);
const client = createPrivateMessagingClient({  network: CotiNetwork.Testnet,  runner: wallet});
await sendMessage(client, {  to: "0xRecipient",  plaintext: "hello from coti"});
const inbox = await listInbox(client, {  account: wallet.address});
const claim = await claimRewards(client, {  epoch: 0n});

Longer plaintext is chunked automatically. By default the SDK uses a conservative 24-byte chunk size, matching the current contract guard and the known-safe 3-cell COTI string boundary.

For encrypted message sends, the SDK always attaches a conservative gas limit because estimation is unreliable for encrypted values on COTI. You can still override it when needed:

ts
await sendMessage(client, {  to: "0xRecipient",  plaintext: "very long message ...",  gasLimit: 8_000_000n});

Additional Read APIs

The SDK also exposes the contract inspection helpers agents typically need:

  • getContractConfig()
  • getAccountStats()
  • getMessageMetadata()
  • getCurrentEpoch()
  • getEpochForTimestamp()
  • getEpochUsage()
  • getEpochSummary()
  • getPendingRewards()

MCP-Style Tool Surface

ts
import {  PRIVATE_MESSAGING_MCP_TOOLS,  invokePrivateMessagingTool} from "@coti-io/coti-sdk-private-messaging";
const tools = PRIVATE_MESSAGING_MCP_TOOLS;
const result = await invokePrivateMessagingTool(client, "list_inbox", {  account: wallet.address,  limit: 10,  decrypt: true});

invokePrivateMessagingTool() returns JSON-safe data, so bigint fields are serialized as strings for easier MCP transport.

The MCP tool registry includes:

  • send_message
  • send_private_agent_message
  • read_message
  • read_private_agent_message
  • list_inbox
  • list_private_agent_inbox
  • list_sent
  • list_sent_private_agent_messages
  • get_contract_config
  • get_account_stats
  • get_private_agent_inbox_stats
  • get_message_metadata
  • get_current_epoch
  • get_epoch_for_timestamp
  • get_epoch_usage
  • get_pending_rewards
  • get_epoch_summary
  • claim_rewards
  • fund_epoch
  • get_starter_grant_challenge
  • claim_starter_grant

MCP Server

The package also ships a stdio MCP server entrypoint.

MCP Registry readiness files:

  • package.json#mcpName: io.github.coti-io/coti-private-messaging
  • server.json: official MCP Registry metadata for the stdio server

If the SDK is installed in your project, run the package binary:

bash
npx -p @coti-io/coti-sdk-private-messaging coti-sdk-private-messaging-mcp

If you are working from this SDK repository checkout, build first and then run the local server:

bash
npm run buildnpm run start:mcp

Required environment variables:

  • PRIVATE_KEY
  • AES_KEY

Optional overrides:

  • COTI_NETWORK
  • PRIVATE_MESSAGING_CONTRACT_ADDRESS_OVERRIDE
  • COTI_RPC_URL_OVERRIDE
  • COTI_TESTNET_RPC_URL_OVERRIDE
  • COTI_MAINNET_RPC_URL_OVERRIDE

Optional starter-grant service config overrides:

  • STARTER_GRANT_SERVICE_URL
  • STARTER_GRANT_SERVICE_TIMEOUT_MS
  • STARTER_GRANT_SERVICE_AUTH_TOKEN
  • STARTER_GRANT_INSTALL_ID_PATH
  • STARTER_GRANT_REF (outreach attribution ref; also accepted via --ref on CLI tools)

Copy .env.example to .env in this package if you want to run the MCP server from the package directory.

Send/read smoke test

From an installed project, if you want the one-command path:

bash
npx -p @coti-io/coti-sdk-private-messaging coti-private-messaging-send --init --to 0xRecipient --text "hello from coti"

From this SDK repository checkout:

bash
npm run send -- --init --to 0xRecipient --text "hello from coti"

If you prefer the split setup/send flow:

bash
npx -p @coti-io/coti-sdk-private-messaging coti-private-messaging-initnpx -p @coti-io/coti-sdk-private-messaging coti-private-messaging-send --to 0xRecipient --text "hello from coti"

If you want verification output instead of a direct send, run the smoke test:

bash
npx -p @coti-io/coti-sdk-private-messaging coti-private-messaging-send-read-smoke

From this SDK repository checkout:

bash
npm run smoke:send-read

This sends a short private message, lists the sender's sent-message page, and reads the message back when the transaction receipt exposes messageId. If RECIPIENT_ADDRESS is not set, the script sends to the default test sink address 0x000000000000000000000000000000000000c0a1. Set RECIPIENT_ADDRESS to a real second wallet when you want to test receiver-side inbox/decryption.

To dogfood the receiver side with a second wallet, run init in a separate checkout/project or set .env to the receiver wallet's PRIVATE_KEY and AES_KEY, then run:

bash
npm run smoke:read-inbox

From an installed project:

bash
npx -p @coti-io/coti-sdk-private-messaging coti-private-messaging-read-inbox-smoke

This lists the receiver inbox and attempts to decrypt messages with the receiver wallet.

Default Network Config

The SDK ships with built-in defaults for both COTI RPC URLs and the private messaging contract address resolution:

  • Testnet RPC: https://testnet.coti.io/rpc
  • Mainnet RPC: https://mainnet.coti.io/rpc
  • Testnet contract: 0xa4C514225Db5B8AE6eF1548d4CE912234A7CD954
  • Mainnet contract: 0xe461F448cB935a14585F6f1a30F5b4C73ffF8c05

If you use createPrivateMessagingClient() without contractAddress, the SDK resolves the address from network and defaults to mainnet. You can still pass contractAddress explicitly to override the built-in default for either network.

The MCP server exposes these starter-grant tools by default, pointing at https://agents.coti.io/grant unless you override it with STARTER_GRANT_SERVICE_URL:

  • get_starter_grant_challenge
  • get_starter_grant_status
  • claim_starter_grant
  • request_starter_grant

The starter-grant flow now supports three patterns: request a challenge directly, inspect current claim status, or use the single-call request_starter_grant helper for the current trivial prompt flow. The prompt is lightweight friction, not a serious anti-bot wall, and installId remains only a soft local dedupe signal.

The SDK-level starter-grant helpers also default to https://agents.coti.io/grant, so url is optional unless you want to override it:

ts
import { requestStarterGrant } from "@coti-io/coti-sdk-private-messaging";
const result = await requestStarterGrant(client, {  timeoutMs: 15000});

ABI Source

The SDK ships a vendored ABI snapshot in src/abi.ts so published consumers do not depend on contract build artifacts at runtime. Maintainers can refresh it with:

bash
npm run sync:abi

By default the sync script reads ./abi/PrivateMessaging.json when that file exists in this repository. Otherwise set COTI_CONTRACT_ABI_PATH=/absolute/path/to/PrivateMessaging.json.

Source: README.md at commit 16b2e0d

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.2.2LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts