What is AudioContent?
AudioContent is a discriminated-union content block that carries raw audio as a base64-encoded string alongside a MIME type. It sits in the same family as TextContent and ImageContent — all three share the same structural pattern of a literal `type` discriminator, a payload field, and an optional `annotations` object. AudioContent specifically uses `"type": "audio"` as its discriminator, making it unambiguous when a host deserializes a heterogeneous ContentBlock array.\n\nIn the MCP message flow, AudioContent can appear wherever a ContentBlock is accepted: inside a `CallToolResult`'s `content` array (tool results), inside a `PromptMessage`'s `content` field (prompt templates), and as the `content` of a `CreateMessageResult` returned by a sampling-capable host. This broad placement means a TTS server can return spoken audio directly from a tool call, and a sampling host can return audio as part of an assistant turn — no special audio-specific API surface is needed.\n\nAudioContent was added in the 2025-11-25 revision of the MCP specification, the same revision that introduced Tasks and refined several lifecycle primitives. Before that version, audio had no first-class representation in the protocol. Because `mimeType` is a free-form string, the spec does not enumerate valid values — in practice `audio/mpeg`, `audio/wav`, `audio/ogg`, and `audio/webm` are the most interoperable choices. Hosts that do not recognise a given MIME type are expected to ignore or pass through the block rather than error.
When to use
Tools that produce audio (TTS, transcription playback).
When NOT to use
Long recordings — use ResourceLink instead.
Notes
Base64 payload size constraints
Base64 encoding inflates binary size by roughly 33 %. For audio files this can push a single content block into the hundreds of kilobytes for even a short clip. JSON parsers in some SDK environments impose message-size limits, so keep inline AudioContent payloads to short utterances (a few seconds). For anything longer, return a ResourceLink pointing at a hosted URL instead of embedding the bytes directly.
MIME type is not validated by the spec
The specification treats `mimeType` as an opaque string. A server can send `audio/flac` or a vendor type, and a conformant host must not reject the block on that basis alone. In practice, whether the client can actually play the audio depends entirely on the host application's media stack. Stick to `audio/mpeg` or `audio/wav` for maximum compatibility across Claude Desktop, web clients, and third-party hosts.
Version compatibility with pre-2025-11-25 servers
AudioContent did not exist before the 2025-11-25 protocol revision. If your server negotiates an older `protocolVersion` during initialization, sending an `audio` block will likely cause the client to drop or error on the unknown type. Always check the negotiated version in `InitializeResult` before emitting AudioContent, or document the minimum required version in your server's capability metadata.
Annotations carry display hints, not playback config
The optional `annotations` field on AudioContent follows the same Annotations schema as all other content blocks — it carries `audience`, `priority`, and `lastModified`. These are rendering hints, not audio-playback directives: there is no duration, volume, or autoplay field in the spec. If a host needs playback metadata, embed it in a companion TextContent block or in custom `_meta` fields on the enclosing message.
Discriminator must be the string literal 'audio'
When constructing AudioContent manually, the `type` field must be exactly the string `"audio"` — not `"AudioContent"`, not `"AUDIO"`. Hosts use strict string matching on the discriminator to decide which branch of the union to parse. Sending a wrong or missing `type` will cause most SDK deserializers to fall through to an unknown-type handler and silently discard the block, which can be difficult to debug because no error is raised.
Fields
| Field | Type | Required | Purpose |
|---|---|---|---|
| type | 'audio' | yes | Discriminator. |
| data | string | yes | Base64-encoded audio bytes. |
| mimeType | string | yes | audio/mpeg, audio/wav, etc. |
| annotations | Annotations? | no | Optional annotations. |
Examples
Audio block
{ "type": "audio", "data": "SUQzBA...", "mimeType": "audio/mpeg" }Common mistakes
❌ Sending raw bytes
✅ Always base64-encode before placing in data.