MCP 2025-06-18 spec brings elicitation, structured output, and OAuth: what to adjust before updating in production

- Reading
- 6 min
- Tables
- 1
- Code
- 3
The June 2025 revision of the MCP protocol changed authentication rules, tool output, and message format. Anyone who has already published a server in production needs to review code before pointing to the new version.
The official Model Context Protocol (MCP) specification documents in its changelog a revision dated June 18, 2025, succeeding the version from March 26, 2025. More than a year later, a good portion of MCP servers in production, whether local ones for Claude Desktop or Cursor, or remote ones behind authentication, still run against the previous spec. The list of changes in 2025-06-18 is not cosmetic: it removes a transport feature, reclassifies how servers handle OAuth, and adds an entire flow (elicitation) that did not exist before.
This piece maps out, change by change, what requires new code versus what is just a configuration adjustment, based on the official MCP changelog.
JSON-RPC batching: removed, not deprecated
The previous spec allowed grouping multiple JSON-RPC calls into a single array, a common practice for reducing round-trips in servers with many small tools. The 2025-06-18 revision removes this support entirely (changelog PR #416). This is not a deprecation with a warning: a server that still expects to receive arrays of requests simply stops understanding part of the traffic from an updated client.
In practice: if your server implements message parsing by hand (instead of using the official SDK), it's worth grepping the code for any logic that handles Array.isArray(body) in the input handler. Those using @modelcontextprotocol/sdk tend to be protected, since parsing is encapsulated, but the point calls for explicit checking before assuming everything is fine.
Structured output: tools no longer just return free text
Before the revision, the return of a tool call was, in practice, a list of content blocks of type text, image, or resource, and any structured data was embedded as JSON inside a text string. A client that wanted to validate or type this return had to do manual parsing, with no format guarantee. Changelog PR #371 adds native support for structured tool output, with a declared outputSchema and a structuredContent field in the response.
The adjustment this requires in an existing server is real, but localized: the tool still receives the same input, only what it returns changes.
// Before (spec 2025-03-26): output always in a free-text block
server.tool("get_weather", { city: z.string() }, async ({ city }) => {
return {
content: [{ type: "text", text: `Em ${city}: 24°C, céu limpo` }],
};
});
// After (spec 2025-06-18): declared outputSchema and structuredContent
server.registerTool(
"get_weather",
{
inputSchema: { city: z.string() },
outputSchema: { temperature: z.number(), condition: z.string() },
},
async ({ city }) => {
const data = { temperature: 24, condition: "céu limpo" };
return {
structuredContent: data,
content: [{ type: "text", text: JSON.stringify(data) }],
};
}
);This is the approach I would follow in a typical server: keep the text content block as a fallback (older clients will still only read that field) and add structuredContent as an extra layer, not a replacement. The changelog also lists support for resource links in tool call results (PR #603), which lets a tool return a reference to an MCP resource instead of embedding the entire content in the response, useful when the result is large or already exists as a resource registered on the server.
OAuth Resource Server: metadata that became mandatory
The change with the widest impact on remote servers is the reclassification of the MCP server as an OAuth Resource Server (PR #338). This sounds abstract, but it has a concrete consequence: the server now needs to expose protected resource metadata pointing to the corresponding Authorization Server, instead of treating authentication as an implicit detail of the HTTP transport.
| Item | Spec 2025-03-26 | Spec 2025-06-18 |
|---|---|---|
| MCP server role | Implicit, no formal metadata | Classified as OAuth Resource Server |
| Authorization Server discovery | Not specified | Via protected resource metadata |
| Access tokens | No mandatory resource scope | Requires Resource Indicators (RFC 8707) |
| HTTP version header | Not required | MCP-Protocol-Version mandatory on subsequent requests |
Added to this is the requirement that clients implement Resource Indicators per RFC 8707 (PR #734), a measure designed to prevent a malicious server from obtaining a valid access token for another resource. Anyone maintaining a server behind OAuth needs, at a minimum, to review whether the protected resource metadata endpoint exists and is correct, because without it an updated client may simply be unable to discover where to authenticate.
Elicitation: the server can pause the flow to ask for more information
Before the revision, if a tool needed a piece of data that wasn't in the original input, the only option was to return an error or a text asking the user to call the tool again with more parameters. PR #382 adds elicitation: a formal mechanism for the server to request additional information from the user in the middle of the interaction, with a schema that describes what is being requested.
const result = await server.elicitInput({
message: "Preciso confirmar o diretório de destino antes de continuar",
requestedSchema: {
type: "object",
properties: { directory: { type: "string" } },
},
});This is not a compatibility adjustment, it is a new feature that only exists in servers that adopt the revision. For those building agents with confirmation steps (deleting a resource, overwriting a file, spending credit), elicitation solves something that previously required a workaround: embedding the question in the return text and hoping the client (or the model) interprets it correctly. With the formal field, the client knows that is a structured question, not just any text.
The protocol version header became mandatory
For HTTP transport, the revision requires that the protocol version negotiated during the handshake be repeated in the MCP-Protocol-Version header on every subsequent request (PR #548). Previously, the version was agreed once and, in practice, several servers simply assumed the client would stay on the same version without reinforcing it on every call.
POST /mcp HTTP/1.1
MCP-Protocol-Version: 2025-06-18
Content-Type: application/jsonA server that ignores this header still works today, because most clients still negotiate a single version per session. But the spec also changed a SHOULD to a MUST in the protocol's lifecycle operations, which means validating the header stopped being a best practice and became a conformance requirement. It's worth adding an explicit check in the input middleware, rejecting with a clear error when the header doesn't match the negotiated version, instead of leaving the behavior undefined.
Checklist before pointing to 2025-06-18
- Remove any parsing logic that still expects batched
JSON-RPCarrays. - Map tools that currently embed JSON as a text string and evaluate migrating to
outputSchema+structuredContent. - If the server runs behind OAuth, expose protected resource metadata pointing to the correct Authorization Server.
- Confirm that the client used in testing implements Resource Indicators (RFC 8707); without this, authentication may fail silently.
- Validate the
MCP-Protocol-Versionheader on every HTTP request after the handshake, not just during the initial handshake. - Review tools that currently ask for confirmation via free text and evaluate whether they make more sense as
elicitation.
The official changelog also lists minor schema changes (a _meta field in more interface types, a context field in completion requests, a title field for friendly names separate from the programmatic identifier). None of them break an existing server on its own, but together they make up the picture of a revision that, despite the modest name "changelog," reorganizes central parts of how authentication, tool output, and transport work in MCP.
Translated from the Brazilian Portuguese original · Read the original
Why we're opening AI House Brasil
Brazil already has people building applications and infrastructure for artificial intelligence around the world. AI House was created so that more Brazilian teams can have access to the conditions to do the same.





