* mcp: free memory and disk in the status line
* mcp: free memory and disk in the end line of answers
* mcp: ❗️ after a low part of the end line, RAM below 5%
SimpleX MCP server: specification
Technical specification of
@simplex-chat/mcp0.3.0 inpackages/simplex-chat-mcp. It coverssimplex-mcp serveand the Claude Code plugin. Statements are checked against the source of the same commit, and each section links to the code.Related: README (the plugin's installation and use) | REFERENCE (
serveandregister, shared settings, options, commands, files, recovery) | PLAN (design record ofserve) | plugin plan (decisions of the plugin) | TESTING (local build and test) | ROADMAP (what comes next)
Table of contents
Executive summary
@simplex-chat/mcp is a local server that gives an MCP host one SimpleX profile per process. The host reaches it with Streamable HTTP on 127.0.0.1 and a bearer token. The server exposes six tools: connect, send, receive, download, list and leave.
The SimpleX core (libsimplex, release core-7.1.3.0) runs inside the same Node.js process, loaded by the simplex-chat library 7.1.3. The core keeps the profile, chats and connections in two SQLite databases of the data folder, and sends and receives files through XFTP servers. The MCP protocol is served by the MCP TypeScript SDK (@modelcontextprotocol/server 2.3.1 and @modelcontextprotocol/node 2.1.1).
connect, send, download and leave are actions. In mode requests the server posts each action as a card in the agent control chat, a SimpleX group created and owned by the agent's profile. An owner approves or rejects the card with a command in that chat, and the server performs the action after the approval. An owner can also approve all messages to one chat, or all downloads of files on known servers from one chat, in advance. On a download card, the owner lets the agent receive the file, or has it forwarded only to the owner. In mode host the server performs actions at once and marks the four tools for the host's own confirmation.
A tool call is held open by the server until the owner decides and, for connect and send, until the replies arrive, and for download, until the file is received or wait passes. A repeated call with the same arguments is attached to the same action, so a call that the host ends early is resumed.
The server keeps actions and downloads in memory, and they are lost when the process exits. The action counter and the standing approvals are stored as custom data in the chat database. The token, the headers file for the host, the server record and the lock are files in the data folder; downloaded files are in its files folder, one folder per chat.
The package is also a Claude Code plugin. Each Claude Code session runs simplex-mcp session, a stdio MCP server. The session server forwards tool calls over a local socket to simplex-mcp service, one service per data root. Requests on the socket are HTTP/1.1 with a bearer token. The service runs two cores:
Claudeis the profile that peers see. It holds the Main group, one group per session and the chats with peers. In a session's group it posts Claude's texts and answers, one line for each step, for each of Claude Code's own prompts and for each summary of the session's context. The last message of each answer ends with the end line of its turn.Useris a member of every session group. It posts the prompts typed in the terminal.
Each session has the six tools and reply, and its group has its own Actions and Control. A chat belongs to the session that connected it. Admins and owners of the session group move a chat to another session with /give.
Every member of the Main group is trusted with all sessions. The Main group's owners are invited to each session group as owners. Another member of the Main group joins a session group as an admin with /join N there.
Rights in a session group follow the member's role there, however the member joined:
- Admins and owners send prompts and the group's
/commands, and approve actions. - Moderators, members and authors send prompts. Claude answers each of their
/commands with one refusal. - Admins and owners make other members observers with
/observer #G ID.
Claude posts a member's rights at each join and each role change. Claude posts the files of reply in a session group at once. The core sends them only while files and media are allowed in the group's preferences.
The session server is also a Claude Code channel. The plugin passes each message in the session group to the running session as a prompt, except the messages of User and one-line / texts. It passes a reaction with one of the apps' eight emoji, of a member whose role sends, other than User, as the emoji after the quote line of the reacted message. It replies This reaction is not supported. to any other reaction, once for each member and reacted message. Claude Code runs no command from such a prompt. The plugin posts Claude Code's permission prompts in the group as cards. An admin or owner can approve a tool for the rest of the session there, and a PreToolUse hook of the plugin then allows its uses, while Claude Code's own rules still apply. The plugin's hooks post the terminal prompts and Claude's text as Claude writes it in the group, and end each answer with the end line of its turn, with its usage. The hooks keep the model and the effort level in the group's short description, and post their switches. An optional status line command adds the plan's usage to the end line.
Dependency graph
Solid edges are runtime imports. Dotted edges are type-only imports, removed by the compiler. Node.js built-in modules are left out.
graph TD
cli["cli.ts"] --> serve["serve.ts"]
cli --> register["register.ts"]
cli --> session["session.ts"]
cli --> service["service.ts"]
cli --> hook["hook.ts"]
cli --> owner["owner.ts"]
cli --> messages["messages.ts"]
cli --> log["log.ts"]
cli -.-> actions["actions.ts"]
serve --> control["control.ts"]
serve --> tools["tools.ts"]
serve --> actions
serve --> core["core.ts"]
serve --> http["http.ts"]
serve --> files["files.ts"]
serve --> messages
serve --> log
serve --> version["version.ts"]
session --> client["client.ts"]
session --> config["config.ts"]
session --> tools
session --> socket["socket.ts"]
session --> files
session --> log
session --> version
session -.-> protocol["protocol.ts"]
session -.-> messages
service --> hub["hub.ts"]
service --> config
service --> socket
service --> files
service --> protocol
service --> log
service --> version
service -.-> actions
service -.-> tools
service -.-> messages
hub --> mainGroup["main-group.ts"]
hub --> user["user.ts"]
hub --> control
hub --> tools
hub --> actions
hub --> core
hub --> serve
hub --> files
hub --> messages
hub --> log
hub --> config
hub -.-> protocol
mainGroup --> control
mainGroup --> tools
mainGroup --> log
user --> core
user --> tools
user --> log
hook --> client
hook --> config
hook --> qr["qr.ts"]
hook --> socket
hook --> files
hook --> log
hook --> version
hook --> messages
hook --> serviceRequest["service-request.ts"]
hook -.-> protocol
display["display.ts"] --> paths["paths.ts"]
display --> serviceRequest
statusLine["status-line.ts"] --> paths
statusLine --> serviceRequest
hub --> statusLine
serviceRequest --> paths
files --> paths
owner --> client
owner --> qr
owner --> files
owner --> version
owner -.-> protocol
client --> socket
client --> files
client --> protocol
client --> log
core --> files
core --> log
control --> tools
control --> actions
control --> messages
control --> qr
control --> log
control -.-> serve
tools --> actions
tools --> messages
tools --> log
actions --> messages
actions --> log
actions -.-> tools
config --> messages
config -.-> actions
protocol -.-> config
protocol -.-> tools
register --> files
register --> log
files --> log
files -.-> actions
http --> log
socket --> log
messages --> log
serve --> sc["simplex-chat"]
tools --> sc
control --> sc
core --> sc
hub --> sc
mainGroup --> sc
user --> sc
messages -.-> sc
log --> sc
tools --> mcps["@modelcontextprotocol/server"]
serve --> mcps
session --> mcps
http --> mcps
http --> mcpn["@modelcontextprotocol/node"]
qr --> qrcode["qrcode"]
version --> pkg["package.json"]
| Module | Role |
|---|---|
cli.ts |
simplex-mcp entry point: commands, options, exit codes |
serve.ts |
serve: start sequence, event dispatch, stop sequence |
http.ts |
serve: HTTP listener, token check, /mcp route, SDK handler |
register.ts |
register command: Claude Code entry of a serve agent |
tools.ts |
tool schemas, descriptions, handlers, connect plans, perform steps, downloads, files to send, chat owners |
actions.ts |
action records, state machine, expiry timers, per-session limits, stop |
control.ts |
agent control chat and session groups: link, owners, owner commands, cards, counter |
messages.ts |
message items and their files, item watch, waits, unread paging, display names, durations |
core.ts |
one SimpleX core: init, user, network config, temp folder, event buffer, profile update |
files.ts |
data folders, lock, token, headers.json, server.json, session folders, socket path, service log |
log.ts |
log lines, error texts, shell quoting |
qr.ts |
QR code text: small and large for terminals, plain for the hook message |
version.ts |
package version from package.json |
session.ts |
plugin: stdio MCP server of one Claude Code session, its channel, the forward of calls to the service |
client.ts |
plugin: service client, version check, spawn |
socket.ts |
plugin: HTTP over the local socket, token check, JSON and NDJSON |
protocol.ts |
plugin: request and reply types of the socket routes, protocol version |
service.ts |
plugin: routes, session registry, session IDs of one Claude Code process, attachments, idle close and stop, ready line |
hub.ts |
plugin: the profile Claude, the sessions, their groups, prompts, opening messages, live texts, answers, end lines, steps and tool-use cards |
main-group.ts |
plugin: the Main group, its owners, the list of sessions, /sessions, /join, owner reset |
user.ts |
plugin: the profile User |
hook.ts |
plugin: hook session-start and hook turn |
display.ts |
plugin: the MessageDisplay hook, dist/display.js |
status-line.ts |
plugin: the status line command, dist/status-line.js, and the plan's usage parts of the end line |
service-request.ts |
plugin: one request to the running service within a time limit; CLAUDE_PID |
paths.ts |
plugin: the data root, the socket path and the token file's name, with Node modules only |
owner.ts |
plugin: link and reset-owners |
config.ts |
plugin: option variables to Config, validation |
Claude Code uses these files of the plugin, described in API 4.8:
.claude-plugin/plugin.json.mcp.jsonhooks/hooks.jsonplugin/allow.js- the production packages bundled in the package's
node_modules(bundleDependencies) - the marketplace
/.claude-plugin/marketplace.json
Specification documents
| Document | Contents |
|---|---|
| Architecture | system diagram, modules and types, state, process lifecycle, approval model, security boundaries, limits. Section 8 covers the plugin. |
| Flows | sequence diagrams of the main flows with source locations. Flows 17-38 cover the plugin. |
| API | the six tools, the control chat commands, replies and cards, the CLI. Section 4 covers the plugin's tools, groups, channel, socket protocol, commands and files. |
Source entry points
| Component | File | Key symbol |
|---|---|---|
Binary simplex-mcp |
src/cli.ts |
main |
| Argument parser | src/cli.ts |
parseCommand |
| Server start | src/serve.ts |
startServer |
| Agent wiring and event dispatch | src/serve.ts |
startAgent |
| HTTP listener | src/http.ts |
startHttp |
| Tool registration | src/tools.ts |
registerTools |
| Downloads | src/tools.ts |
AgentTools.downloadFile |
| Action store | src/actions.ts |
Actions |
| Agent control chat and session groups | src/control.ts |
Control |
| Card text | src/control.ts |
cardText |
| Item watch | src/messages.ts |
ChatItemsWatch |
Claude Code entry of serve |
src/register.ts |
register |
| Data folder files | src/files.ts |
createDataFolder, acquireLock |
| Session server | src/session.ts |
startSession |
| Session to service link | src/session.ts |
ServiceLink |
| Service start by a client | src/client.ts |
ServiceClient.ensureService |
| Service process | src/service.ts |
runService |
| Service routes | src/service.ts |
Service.routes |
| Hub | src/hub.ts |
Hub.open |
| Session and its group | src/hub.ts |
Session |
| Main group | src/main-group.ts |
MainGroup |
Profile User |
src/user.ts |
User |
| Hooks | src/hook.ts |
sessionStart, turn |
| Display hook | src/display.ts |
display |
| Status line command | src/status-line.ts |
runStatusLine |
link, reset-owners |
src/owner.ts |
showLink, resetOwners |
| SimpleX core | src/core.ts |
openCore |
| Package manifest | package.json |
bin.simplex-mcp |
Code references
Functions, types and constants are named in the specs, and their files are linked without line numbers. A comment // spec: spec/FILE.md#ANCHOR is placed above each function, method, class, type or constant listed in a module table of Architecture or linked from an API section, where ANCHOR is the <a id> of a row or a section. Class fields, such as Session.turns, are given no comment. For a declaration whose output is specified field by field in an API section, such as a tool handler, a result object, a card, a command reply, a group profile or a socket route, the anchor of that section is given. For any other declaration, the anchor of its row is given, or, without a row, the anchor of the API section with a link to it. Line-number links in the package's documents, anchors defined twice, and // spec comments that differ from this form, point to a missing anchor or are not directly above a declaration are reported by the unit test spec.test.ts.