Upgrade to 0.17.0
Update custom MCP error handling and HTTP response parsing, and back up the store before upgrading.
Fluxmail 0.17.0 adds MCP OAuth sign-in and MCP 2026-07-28 support. It changes MCP error responses for unavailable tools and the response format for legacy HTTP clients. The SQLite store advances from format 6 to format 7.
Find your migration
| Interface | Required changes |
|---|---|
| MCP over HTTP | Handle JSON-RPC error -32602 for unknown tools and tools omitted by permissions. Accept and parse both SSE and JSON responses. |
| MCP over stdio | Handle JSON-RPC error -32602 for unknown tools and tools omitted by permissions. |
| CLI | No client migration. |
| REST | No client migration. |
All installations must back up their data before the store migration, regardless of which client interface they use.
Handle unavailable tools
A tools/call request for an unknown tool, or a tool omitted because the connection lacks its required permission, now returns a JSON-RPC error with code -32602. Previously, it returned a tool result with isError: true.
If you handle tool errors in custom client code, catch protocol errors as well as checking isError on results. Use tools/list to discover the tools available to the connection. For example, a connection without mail.send cannot call send_email.
Invalid arguments for a registered tool still return a tool result with isError: true. Tool names, argument schemas, and permission requirements stay the same as in 0.16.0.
Parse HTTP responses by content type
Legacy HTTP MCP requests now receive tool and other request results as SSE with content type text/event-stream. Previously, Fluxmail returned these results as application/json. MCP 2026-07-28 requests normally receive JSON.
Custom HTTP clients must send Accept: application/json, text/event-stream, inspect the response content type, and parse either format. For SSE, decode the JSON-RPC message in each event's data field. If you use an MCP SDK transport, confirm it supports both response formats. Stdio framing is unchanged, and CLI and REST clients do not need this change.
Back up before the store migration
Stop every Fluxmail process sharing the data directory, including stdio clients, HTTP servers, and scheduled delivery workers. Back up the complete installation, including the encryption key and external secrets, before starting 0.17.0.
The first upgraded process migrates the store to format 7 to persist MCP OAuth clients, approvals, and tokens. Existing API keys and member sessions remain valid. To roll back, stop the upgraded processes and restore the complete pre-upgrade backup with the matching older release. An older executable cannot open a format 7 store.
OAuth sign-in is optional. Existing API-key and stdio connections keep working with their current authentication. See Connect an MCP client to set up OAuth.
Last updated