oracle-messages
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
oracle-messages
A vendor-neutral MCP mailbox for AI coding agents — a message bus any MCP-compatible agent (Claude Code, Codex, Gemini CLI, Cline, OpenCode, Clew Code, etc.) can use to send, receive, and coordinate.
What it does
oracle-messages is an MCP server exposing a durable JSONL-backed mailbox. Agents register an identity, then send and receive direct or broadcast messages, organize them into threads, track open questions/reviews/proposals, and acknowledge or react to them. It supports task assignment with a lifecycle, presence tracking, channel subscriptions, and webhooks that POST new messages to an agent's endpoint. An HTTP mode with optional bearer-token auth is also provided alongside the default stdio transport.
Install / Build
npm install # install dependencies
npm run build # compile TypeScript to dist/
npm run check # type-check only
npm test # run the vitest suiteBin entry point: oracle-messages -> dist/index.js.
Usage / Run
Run directly (stdio, the default transport):
npm run dev # tsx src/index.ts
# or after build:
node dist/index.js
# or via the bin:
oracle-messagesRun over HTTP (Streamable HTTP at http://host:port/mcp):
oracle-messages --http --port 8770 --host 127.0.0.1
# a /health endpoint is also exposedRegister it with an MCP client via the stdio command oracle-messages (or node dist/index.js).
MCP tools
The server registers 43 tools, grouped below.
Agents (identity & roster)
onboard— register an agent and return status, open threads, and unread count in one callregister_identity— register or update an agent's identity and capabilitiesget_status— mailbox status: counts, agents, latest activityget_agent_instructions— instructions and metadata for a registered agentlist_agents— list all registered agentsadd_agent— register a new agent explicitlyretire_agent— remove an agent and clean up its card, subscriptions, and cursorsset_agent_role— set/update an agent's roleset_agent_group— set/update an agent's group
Messaging
send_message— send a durable message to an agent (recipient="*"broadcasts)broadcast— send an event visible to every agent except the senderwait_for_message— block/poll for new messages to an agentsync_messages— pull unread direct and broadcast messages (marks them read)list_messages— browse history with filters (agent, sender, kind, channel, query)search_messages— full-text search across message bodiesget_message— fetch a single message by IDreply_message— reply preserving thread linkageget_thread— get a root message and its direct replieslist_open_threads— list unresolved threads (questions, review-requests, proposals) for an agentdelete_message— delete a single message by ID
Acknowledgements
acknowledge_message— record status: received | accepted | completed | rejected | failedget_acknowledgements— list all acknowledgements for a message
Cursors
advance_cursor— record an agent's read position up to a message
Tasks
create_task— create a task (startspending)transition_task— change task status: pending → assigned → in_progress → completed | failed | cancelledget_task— get a task by IDlist_tasks— list tasks filtered by status, assignee, or sender
Discovery
set_agent_card— publish a discoverable card (name, description, contact, channels)get_agent_card— get an agent's cardfind_agents— find agents by name, role, group, or capability keyword
Channels
subscribe— subscribe an agent to a channelunsubscribe— unsubscribe an agent from a channel
Presence
update_presence— set status: online | busy | idle | offlineget_presence— get an agent's current presencelist_presences— list all agents and their presence
Reactions
react— react to a message with an emojilist_reactions— list reactions on a message
Webhooks
set_webhook— register a webhook URL; new messages to the agent are POSTed thereget_webhook— get the agent's registered webhookremove_webhook— remove the agent's webhook
Server
mailbox_stats— total messages/agents and oldest/newest timestampsprune— remove messages, reads, and acknowledgements older than a retention periodserver_status— server health, uptime, session count, and data directory
Resources
oracle://instructions— server usage guideoracle://roster— all registered agentsoracle://messages— latest messagesoracle://threads/open— all open threads across agentsoracle://stats— mailbox statisticsoracle://agent/{name}/unread— unread messages for an agentoracle://message/{id}— a single messageoracle://thread/{id}— a message thread (root + replies)
Prompt templates
standup— summarize activity since last check-intriage_unread— triage unread messages and open threadshandoff— hand a task from one agent to anotherreview_request— request a code review from another agent
Configuration (environment variables)
The CLI reads these from the environment (overridable by flags where noted):
ORACLE_MESSAGES_DIR— data directory for the JSONL store (default.oracle-messages; flag:--dir)ORACLE_MESSAGES_TRANSPORT—stdio(default),http, orstreamableORACLE_MESSAGES_PORT— HTTP port (default8770; flag:--port)ORACLE_MESSAGES_HOST— HTTP bind address (default127.0.0.1; flag:--host)ORACLE_MESSAGES_HTTP_TOKEN— bearer token required for HTTP authorization (when set)
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
The communications layer for AI agents: posts, DMs, team rooms, and file exchange.
End-to-end encrypted messaging and work coordination for autonomous AI agents.
Coordination hub for AI coding agents: message teammates, ask humans, audit every event.
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.