API Parity
Mallary exposes a remote MCP server over Streamable HTTP for public API parity. MCP tools route through the existing/api/v1/* handlers. Mallary does not duplicate posting logic in a separate MCP-only layer.
Preflight
mallary_create_post runs preflight first by default with run_preflight=true.
Idempotency
If you sendidempotency_key, Mallary forwards it as an Idempotency-Key header to the underlying API handler.
Do not treat that header as a guarantee that a repeated request will be deduplicated. If a publishing call times out or loses its response, use mallary_list_posts and mallary_get_job to check the saved result before taking any further action. Do not automatically repeat a publishing call.
Error Shape
Mallary returns non-2xx API results as structured MCP errors with:http_statuscodemessagedetailswhen available
Transport Note
The standard/mcp endpoint returns one JSON result for each POST containing a JSON-RPC request. Other Mallary MCP endpoints can return an SSE stream. Clients must support both application/json and text/event-stream and include both in the Accept header.
Keep the returned Mcp-Session-Id and negotiated Mcp-Protocol-Version for later requests. An accepted notification, including notifications/initialized, returns 202 with an empty body. Reuse the session for a workflow instead of initializing before every tool call.
For SSE, read complete events until the response with the matching JSON-RPC ID arrives. Do not wait for a fixed-size buffer or stream closure. Close the response when finished and bound both blocked reads and total elapsed time.
Approval Waits and Timeouts
A host may pause a request for user approval before Mallary receives it. Mallary cannot remove that prompt or tell the client how long the user will take. Use the host’s supported background execution and process-status tools while an approval is pending. A short execution yield is a way to return control; it must not kill the network request. Keep one process active rather than starting another copy. Check every timeout layer. A shell or task timeout must allow enough time for all sequential network requests and cleanup. For example, a 150-second process timeout will kill a client that is allowed to wait 300 seconds for one request. Keep time limits bounded and show an honest timeout message; do not label every delay as a Mallary outage.Recovering from Errors
Keep credentials, signed upload URLs, and raw provider response bodies out of diagnostic logs.