Baryon — Proton Mail via Bridge

Baryon creates the default attachment directory at mode 0700 when it starts, and refuses to start if it cannot. Setting BARYON_ATTACHMENT_ROOTS replaces that default entirely — those directories must already exist. On Windows there is no attachment directory, because both file-touching tools refuse to run there.

BARYON_ALLOWED_FOLDERS names must match Bridge's spelling exactly, except INBOX, which matches case-insensitively. Draft saving is outside this scope, so a reply can still be saved when Drafts is not on the list.

Without an explicit or auto-discovered certificate, Baryon refuses to start unless PROTON_BRIDGE_ALLOW_INSECURE=true. Insecure mode allows another local process to impersonate Bridge and capture its generated password.

BARYON_ALLOW_UNCONFIGURED_INTROSPECTION=true applies only when both credentials are absent, which is how a published image can be started and inspected without a mailbox. Every tool call then fails with a configuration error, and a half-configured server — one credential set, the other missing — still refuses to start.

baryon-mcp setup stores credentials that the server loads whenever the corresponding environment variable is unset; a set environment variable always wins. The layout under ${XDG_CONFIG_HOME:-~/.config}/baryon-mcp (mode 0700):

The keyring item is stored under service baryon-mcp-proton-bridge with the Bridge address as its username, so a keyring browser shows it as Password for '[email protected]' on 'baryon-mcp-proton-bridge' and

secret-tool lookup service baryon-mcp-proton-bridge username [email protected]

retrieves it. Exactly one password store survives a setup run: saving into the keyring removes the file, and falling back to the file removes the keyring item. A keyring that stops answering — or blocks locked for more than ten seconds — reads as "no stored credentials" rather than an error, so containers and headless machines keep working.

For reading mail:

1. Call list_folders.
2. Call list_emails or search_emails.
3. Pass the returned folder, uid, and uidvalidity to get_email or the attachment tools.

Every summary carries the message's message_id, which correlates the same message across folders — the copy in All Mail and the copy in INBOX share it, while their UIDs do not.

list_emails and search_emails accept include_bodies, which adds a shortened body to every summary on the page. That turns triage into a single call — "which of my unread messages need attention" — instead of one get_email per message, and the full message is still one get_email away where the preview shows it matters. Bodies are the plain-text part when the message has one, and otherwise the HTML part reduced to the text a reader would see, flagged by body_from_html. Stripping happens before shortening, so the character budget buys readable text rather than markup, and body_truncated marks a body cut short. get_email still returns both parts as they were sent, HTML included. Because bodies are far larger than envelopes, a page carrying them is capped at 10 messages: a larger limit is refused rather than silently trimmed, and an omitted one defaults to 10. Previews are peeked like every other read, so triaging unread mail leaves it unread.

For the next page, pass the returned next_before_uid back as before_uid, together with uidvalidity. Mail arriving between two calls then cannot shift or repeat a result, which plain offset paging cannot promise. offset still works, but the two cannot be combined, and the call fails rather than paging a mailbox whose uidvalidity changed.

Attachments come back in two ways. get_attachment returns the bytes inline—images as image content and other files as base64—which puts them in the conversation. save_attachment writes the decoded bytes to a path and returns only the path, so a large attachment never reaches the model's context.

output_path may be relative, in which case it resolves inside the attachment directory, or absolute and inside it. The parent directory must already exist and the target file must not. Both attachment tools are bounded at 25 MB decoded, so save_attachment removes the context cost, not the fetch cap.

save_reply_draft answers one message. Pass the folder, uid and uidvalidity you read it with, plus the body; everything else is derived from the message:

• Recipients come from its Reply-To, else its From, else its Sender. Your own addresses are removed and duplicates collapse. A message that names nobody else there — one of your own, or one forging your address — is refused rather than answered at the other recipients it lists; save_draft is where you name recipients yourself.
• reply_all additionally copies its To and Cc. The original Bcc is never carried over; only a bcc you pass yourself is kept.
• from must be one of BARYON_SENDER_IDENTITIES — call list_sender_identities to see them. Omitted, Baryon picks the identity the message was addressed to, then the one it was sent from, then the default.
• Subject keeps an existing Re: prefix, in any case, or gains one.
• Threading sets In-Reply-To to the parent's Message-ID and References to its chain followed by it. A message with no Message-ID is refused: it cannot be threaded correctly, and save_draft remains available for it.

The original is quoted only when you set quote_original. It is then copied whole below your text, under an "On , wrote:" line, with > prefixes in plain text and a <blockquote> in HTML, together with the images its HTML shows inline. Its other attachments are never copied. The response echoes every derived field, so the recipients can be reviewed before you send the draft from Proton Mail. save_reply_draft only ever creates a draft; replacing one stays with save_draft.

save_forward_draft forwards one message. Pass the folder, uid and uidvalidity you read it with, the recipients, and optionally a note in text_body or html_body. Baryon reads the original and writes the draft itself, so neither the message nor its attachments pass through the conversation or touch local disk:

• Body is your note, then a ---------- Forwarded message ---------- block naming the original's From, Date, Subject, To and Cc, then the original text and HTML copied whole. A plain-text original forwarded with a plain note stays plain text.
• Attachments all travel with it. Images the original's HTML shows through cid: links stay inline; everything else is a regular attachment.
• Subject keeps an existing Fwd: or Fw: prefix, in any case, or gains Fwd:.
• from is chosen as for a reply. Recipients are optional and can be added in Proton Mail before sending.

The draft carries no In-Reply-To or References, so it starts a new conversation for its recipients. An original whose body is above 2 MiB, or whose attachments exceed 100 files or 25 MB, is refused rather than cut short. warning reports text that could not be decoded exactly, and attachments whose encoding was damaged, which carry only what was readable.

Things to know about forwards, and about replies that quote:

• A draft carrying more than 50,000 characters cannot be replaced faithfully with save_draft, which reads it back truncated, and a replacement loses its inline images. Edit such a draft in Proton Mail instead.
• Proton Mail keeps a draft's HTML body when it has one, and Bridge does not tell it which message a draft forwards, so the original is not marked as forwarded.
• Nested attachment containers become separate files, and attachments without a filename get generated names such as part-1.2.png. Attachments keep their Content-Type parameters, such as a calendar invitation's method, except a charset other than UTF-8: such a text file keeps its bytes but loses its charset label.
• The original HTML is embedded as it was sent, <head> styles included.

For drafts, omit uid and uidvalidity to create one. To replace an existing draft, pass both values and submit the complete desired state. Read the current draft with get_email and fetch any attachments first so recipients, bodies, and files can be retained.

Each attachment supplies its content in exactly one of two ways:

• content_base64: inline bytes, with filename and content_type required.
• content_path: a path to a regular file on the machine running Baryon, relative to the attachment directory or absolute and inside it. filename defaults to the path's basename and content_type is inferred from the extension.

All attachments are read and validated before anything touches the mailbox, so a missing or unreadable file fails the call without creating or replacing a draft.

save_reply_draft derives a reply's threading for you. To thread one by hand, read the message being answered with get_email, then pass its message_id as in_reply_to, and its references followed by that same message_id as references. When the parent reports no references, use its in_reply_to in their place, as RFC 5322 section 3.6.4 prescribes.

Angle brackets are optional on message identifiers, but each identifier must be a well-formed id-left@id-right. Baryon rejects anything it could not read back and strips the self-reference Bridge adds to References, so the chain it reports can be quoted as-is.

A replacement gets a new UID. Baryon appends it before removing the previous draft and returns a warning if cleanup is incomplete. The replacement keeps the previous draft's Message-ID, plus whichever of its In-Reply-To and References the call omits. Omitting one of those fields keeps the existing header; passing an empty array removes it and detaches the draft from its thread.

Reading limits:

• 50,000 characters each for the plain-text and HTML bodies get_email returns.
• 2,000 characters per shortened body, in both get_thread and the listing tools, counted after markup is stripped.
• 10 messages per page when list_emails or search_emails is called with include_bodies; 100 without it.
• 50 messages per conversation from get_thread, keeping the most recent.

Draft limits:

• 50,000 characters each for the plain-text and HTML bodies you write. A forwarded or quoted original is carried whole, up to 2 MiB per body.
• 100 regular attachments.
• 100 message identifiers each in in_reply_to and references, with 512 bytes per identifier. A longer chain read from a message is trimmed to its most recent identifiers.
• 25 MB decoded per attachment and in total, across both content sources.
• Generated RFC822/MIME message below 70 MiB.
• Standard base64 for inline content. save_draft cannot add inline CID images; forwards and quoted replies keep the original's.
• Attached messages (message/rfc822 and other message/ types) travel unencoded, as MIME requires. One that is not in CRLF form, has a line over 998 bytes, or holds a NUL byte is attached as a generic application/octet-stream file instead, so its bytes, and any signature over them, stay exact. This applies to save_draft as well as forwards.
• content_path and save_attachment are not available on Windows. Use content_base64 and get_attachment there.

Baryon speaks MCP 2026-07-28 and negotiates down to any earlier revision back to 2024-11-05, so older clients keep working.

The draft tools with content_path read local files with the server's privileges. They refuse anything but regular files after resolving symlinks. save_attachment never overwrites and creates no directories. Every read tool, including get_attachment, is annotated read-only.

Both are confined to the same directories. Unset, that is the managed ${XDG_CONFIG_HOME:-~/.config}/baryon-mcp/attachments, created at mode 0700 when the server starts; BARYON_ATTACHMENT_ROOTS replaces it with directories of your own, which must already exist. A relative path resolves inside the first of them, and an absolute path must fall inside one — a path escaping the boundary is refused rather than followed.

Attachment roots are pinned by identity when the server starts. Replacing a root afterwards—renaming it and leaving a symlink in its place, for example—does not move the boundary. If every root becomes unreachable, both tools refuse all paths rather than falling back to unrestricted access.

Upgrading from a release before the managed directory: with BARYON_ATTACHMENT_ROOTS unset, content_path and output_path used to accept any absolute path the server's account could reach. They are now confined to the managed directory. To keep using other locations, set BARYON_ATTACHMENT_ROOTS explicitly; the Docker example above already does, so container users are unaffected.