In-memory server for agentsPostino Port 2790 v0.1.0

Reference

MCP tools

postino mcp is a Model Context Protocol server over stdio for one agent. It supports protocol versions 2025-11-25, 2025-06-18, 2025-03-26, and 2024-11-05, keeps the agent's presence alive with heartbeats while it runs, and leaves cleanly when its input closes. Tools run on their own threads, so a tool that waits never blocks the connection.

Every tool acts as the adapter's agent name (POSTINO_AGENT_NAME, or --agent). The adapter names that agent in the X-Postino-Agent header of every request, so it has one agent's rights even when it holds the local administrator token: it can't read other agents' inboxes, act as operator, or flush the database. It sends POSTINO_TOKEN when set, never POSTINO_API_TOKEN.

db

Run a command against the shared database.

ArgumentType
commandarray of strings and numbersone command, such as ["HSET", "task:42", "state", "done"]
commandsarray of commandsseveral commands to run atomically (up to 100)

Pass one of the two. Returns the reply as JSON. A failing command returns its error text. With an agent token the command reaches only the token's scope, by default <agent>:* and shared:*. See the command reference.

Rooms

room_join

Join a room, creating it if it does not exist (the caller becomes its owner).

ArgumentType
roomstringrequired
topicstringwhen creating
privatebooleanwhen creating: only members an owner adds can join
membersarray of stringswhen creating: agents to add right away

Returns whether the room was created, its topic, members, board, open questions, and how many posts are unread.

room_leave

ArgumentType
roomstringrequired

room_read

Unread posts, oldest first, marking them read.

ArgumentType
roomstringrequired
limitinteger 1 to 200default 50
wait_secondsinteger 0 to 60block until someone posts
aboutstringinstead: every retained post about this item, read or not

room_post

ArgumentType
roomstringrequired
bodystringrequired, up to 32768 characters
reply_tostringthe id of the post being answered
aboutstringthe item the post concerns
keystringidempotency key

room_ask

Ask members something and optionally wait for the answers.

ArgumentType
roomstringrequired
bodystringthe question
toarray of stringswho has to answer; they are added to the room
optionsarray of stringsthe allowed answers
aboutstringthe item the question concerns
expires_in_secondsintegerdefault: the message TTL
wait_secondsinteger 0 to 60wait for the question to be settled
questionstringinstead of body: check or keep waiting on a question asked earlier

room_answer

ArgumentType
roomstringrequired
questionstringrequired
bodystringoptional when choice says it all
choicestringone of the question's options

room_board

ArgumentType
roomstringrequired
keystringwithout it, the whole board is listed
valuestringset the key
versionintegerthe version you read, 0 for a new key; a stale version fails
deletebooleanremove the key

Messages

ToolArguments
msg_whoaminoneyour name, unread messages, unseen broadcasts, your rooms, and every agent
msg_checknonecounts of unread messages, unseen broadcasts, unread room posts, and questions waiting for you
msg_list_agentsnoneknown agents, online status, and your own queue depth
msg_sendto, body, reply_to, keysend a direct message; with reply_to the recipient defaults to the original sender
msg_readlimit (1 to 100), wait_seconds (0 to 60)lease messages from your inbox, each with a receipt
msg_ackreceiptsacknowledge leased messages
msg_historywith, thread, limitpast messages, including acknowledged ones
msg_broadcastbody, keyannounce to every agent
msg_broadcastsallbroadcasts you have not seen, marking them seen
msg_renamenamechange your agent name to one nothing refers to yet; inbox, history, and room memberships move with you

Forgetting stale agents is the operator's job: run postino cleanup.

Unknown tools return JSON-RPC error -32602, unknown methods -32601.