MCP response format and stability
Glean builds MCP tools for an LLM to call and read. Glean changes tool definitions and tool output as the tools improve, in any release, without a deprecation period. When your code needs a stable request and response schema, use the Glean REST APIs where equivalent functionality is available. They follow Glean's API evolution and deprecation policy.
What's stable and what can change
Glean separates the MCP protocol, which stays stable, from the content of each tool, which can change.
Stable: the MCP protocol
- The message structure in the MCP specification for tools, including
tools/list,tools/call, and the tool result envelope - Any MCP client that follows the specification can list tools, call them, and read results
Can change in any release: tool content
- Tool names, descriptions, and input parameters
- The format of response text: Token-Oriented Object Notation (TOON), plain text, Markdown, or JSON
- Field names, field order, and which fields appear
- The number, order, and type of content blocks in a result
- Output from tools that Glean proxies from external MCP servers and connectors
MCP tools compared with REST APIs
| Glean MCP tools | Glean REST APIs | |
|---|---|---|
| Built for | An LLM that discovers and calls tools | Your code |
| Response schema | None. Glean tools don't publish an output schema or return structuredContent. | Documented JSON schemas |
| Breaking changes | Can ship in any release | Follow a deprecation process with a migration period of at least six months |
| Notice of changes | No advance notice or deprecation period | X-Glean-Deprecated response headers, inline docs warnings, and a published schedule |
| Testing upcoming change | Not available | The X-Glean-Exclude-Deprecated-After request header |
For details on the REST API process, see API evolution and deprecations.
How Glean formats responses today
This section lists the formats Glean uses today, with examples of where each one appears, so you can recognize what a host shows you. It isn't a list of every tool, and it isn't a contract. Any tool can move to a different format in any release.
| Format | What the result contains | Where you see it today |
|---|---|---|
| TOON | One text block in TOON | Most Glean tools |
| Text and TOON metadata | One text block: readable text, usually Markdown, then a --- line, then metadata in TOON | search, chat, read_document, get_agent, and tools that run agents |
| JSON | One JSON text block in the shape ChatGPT requires | ChatGPT search and fetch |
| Images and resources | Image blocks or resource links, with text metadata | Image tools, and read_document in hosts that support embedded resources |
The TOON format holds the same data as JSON in fewer tokens, so the model gets more context from each tool call. A search result in TOON can look like this:
results[2]{title,url,datasource}:
Q3 planning notes,https://example.com/docs/q3-plan,gdrive
Launch checklist,https://example.com/docs/launch,confluence
A result can also contain extra content blocks. For example, a response can end with a block that holds an invocation ID. See Find invocation IDs in MCP tool responses.
Choose an interface
| What you're building | Use |
|---|---|
| An AI host or agent where the model calls Glean tools | Glean MCP server |
| Search results in your own UI or data pipeline | Platform API: Search |
| A chat experience that renders Glean answers in your own UI | Platform API: Chat |
| An app or workflow that runs a Glean agent and uses its output | Platform API: Agents |
| A capability that isn't in the Platform API yet | Client API |
For more guidance, see Choose a retrieval interface.
If your integration parses MCP responses
Move the integration to the matching REST API. Until you do, any Glean release can break it.
While you migrate, make the parser tolerant of change:
- Read every text block in a result, not one block at a fixed position.
- Don't parse response text as a JSON document, and don't extract fields from model-facing text.
- Don't depend on the number or order of content blocks, or on the TOON layout.
- Ignore a text block that starts with
glean_invocation_id:. If you need the ID, read it from_meta["glean/invocationId"].
See also
- About Glean MCP server — what the Glean MCP server does and which capabilities it exposes
- MCP server best practices — how to choose tools for a server
- API evolution and deprecations — how Glean changes the REST APIs