Postal DevelopersCompact mode
How responses are trimmed by default, and how to get the full payload.
Assistants pay for every token a tool returns. The Postal MCP server therefore returns compact objects by default and lets you opt into the raw API payload per call.
The detail parameter
Eight read tools accept detail: "compact" | "full":
list_tracks, get_track, search_tracks, list_playlists, get_playlist,
get_tag_taxonomy, list_composers, get_composer.
There is no server-wide switch. Pass detail: "full" on the call that needs
it.
What every response looks like
Each tool returns a one-line human summary followed by pretty-printed JSON. The summary is computed from the original payload, so counts and paging cursors stay accurate even when the body is trimmed.
Found 42 tracks (showing 20, next cursor: ck_…)
[
{ "id": "…", "title": "Night Drive", "artist": "…", "bpm": 92, … }
]What compact keeps
| Object | Kept | Dropped |
|---|---|---|
| Track | id, title, artist, durationSec, bpm, key, createdAt, link, cid, tag names per category | audio file URLs, shareholders, share-link internals, per-tag confidence |
| Playlist | metadata, publicLink, per-track { id, title, artist, durationSec, order } | download links, full audio profiles |
| Composer | composer fields, linked tracks as { id, name } (max 25, tracksTruncated: true beyond that) | full track objects |
| Taxonomy | plain name arrays per category | ids, codes, ordering |
| Search hit | id, title, artist, bpm, key, durationSec, genres, moods, score, first two reasons, plus the interpretation block | remaining reasons, raw feature vectors |
| Dashboard | everything except entityImage on activity items (always trimmed) |
list_tracks also asks the API for a sparse field set, so trimming happens
server-side as well as in the MCP layer.
Mutations
Write tools do not echo the object back. They return a confirmation such as:
{ "ok": true, "playlistId": "…", "added": 3 }Exceptions that return the full created object: upload_track_by_url,
create_playlist, and the tagging read and poll tools.
Soft failures
When the API answers with { ok: false, … } the server converts it into a
tool error so the assistant sees Error: <message> (missing: …) rather than a
successful-looking payload.