AIARTICLE

MCP 2025-06-18: elicitation and structured output require migrating production servers

The Model Context Protocol specification published in June 2025 brought structured output and elicitation to tools. Anyone already running an MCP server in production needs to decide how to migrate without breaking clients that still speak the older version.

MCP 2025-06-18: elicitation and structured output require migrating production servers
Image: Alan Andrade
Article · AI
Reading
7 min
Code
5

MCP 2025-06-18: elicitation and structured output require migrating production servers

The Model Context Protocol specification published in June 2025 brought structured output and elicitation to tools. Anyone already running an MCP server in production needs to decide how to migrate without breaking clients that still speak the older version.

The Model Context Protocol (MCP) specification underwent a revision on June 18, 2025, replacing the version from March 26 of that year. The official changelog, published at modelcontextprotocol.io, lists changes that are not cosmetic: removal of JSON-RPC batching support, classification of servers as OAuth Resource Servers, a requirement for Resource Indicators (RFC 8707), and, most importantly for tool authors, two new features: structured output and elicitation.

More than a year and a half after the specification's publication, MCP servers written before June 2025 did not have access to these two features by default: they still return results only as free text and have no way to ask the user for extra information in the middle of a call, unless they've been updated since then. This works fine until the client (Claude Desktop, an IDE, a custom agent) starts negotiating the new protocol version and expects this behavior. This piece covers how to adapt existing tools to both features without breaking clients that still speak the older version.

Structured output: from free string to schema

Editor's note: the field, method and action names cited in this and the next section (outputSchema, structuredContent, elicitation/create, accept/decline/cancel, elicitation capability) describe the detailed implementation in the full MCP specification, which is not covered by the summarized changelog used as the source for this piece. Confirm these details in the official documentation before implementing.

Before June 2025, the result of an MCP tool was just a content array with text, image or resource blocks. There was no way for the client to know, up front, the format of the returned data: it was left to parse free text, which is fragile for automation. PR #371 corresponds to structured output support; in the full specification, this translates into outputSchema in the tool definition and structuredContent in the result, describing the shape of the data in JSON Schema.

The official MCP 2025-06-18 changelog lists structured tool output support as the main change
The official MCP 2025-06-18 changelog lists structured tool output support as the main change. Reproduction: modelcontextprotocol.io.

The old format (without outputSchema) remains valid: the change is additive, not mandatory. But anyone who declares outputSchema on a tool now needs to return structuredContent compatible with that schema on every call. An example of a weather tool before migration:

ts
server.tool(
  "get_weather",
  "Retorna o clima atual de uma cidade",
  { city: z.string() },
  async ({ city }) => {
    const data = await fetchWeather(city);
    return {
      content: [{ type: "text", text: `${data.temp}°C em ${city}` }],
    };
  }
);

After migration, with the output schema declared:

ts
const WeatherOutput = z.object({
  city: z.string(),
  tempC: z.number(),
  condition: z.string(),
});

server.registerTool(
  "get_weather",
  {
    description: "Retorna o clima atual de uma cidade",
    inputSchema: { city: z.string() },
    outputSchema: WeatherOutput.shape,
  },
  async ({ city }) => {
    const data = await fetchWeather(city);
    const structured = { city, tempC: data.temp, condition: data.condition };
    return {
      content: [{ type: "text", text: `${data.temp}°C em ${city}, ${data.condition}` }],
      structuredContent: structured,
    };
  }
);

The point that usually causes bugs: keeping the text content block alongside structuredContent isn't redundancy, it's backward compatibility. A client that still negotiates protocol version 2025-03-26 simply ignores structuredContent and reads only the text. Removing the text content to "clean up" the tool breaks these clients with no warning at all at deploy time.

Elicitation: requesting data mid-execution

PR #382 adds elicitation, a mechanism for the server to request additional information from the user during a tool call, instead of requiring everything in the initial inputSchema. It's useful when the data depends on a decision that only becomes clear after the tool has already started running, such as confirming a value or requesting a specific document.

In practice, the flow reverses the normal message direction: the server sends an elicitation/create request to the client, in the middle of processing the tool, asking for a form described in JSON Schema:

json
{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "elicitation/create",
  "params": {
    "message": "Preciso do CPF para concluir a reserva",
    "requestedSchema": {
      "type": "object",
      "properties": { "cpf": { "type": "string", "title": "CPF" } },
      "required": ["cpf"]
    }
  }
}

The client responds with one of three actions: accept (with the filled-in content), decline or cancel. The tool needs to handle all three, not just the happy path:

json
{
  "jsonrpc": "2.0",
  "id": 7,
  "result": { "action": "accept", "content": { "cpf": "000.000.000-00" } }
}

If the tool's code assumes every elicitation/create comes back with accept, a user who clicks cancel brings down the execution with an unhandled error. The handler needs an explicit switch across the three actions, with a reasonable response for decline and cancel (for example, ending the tool with a clear message instead of throwing an exception).

Capability negotiation: what doesn't break older clients

Elicitation only works if the client declares the elicitation capability in initialize. A well-migrated server checks this capability before calling elicitation/create; if the client doesn't support it, it falls back to the old behavior (asking for everything in inputSchema at once, or returning an error telling the user to provide the missing data on the next call). Calling elicitation/create without checking the capability is the quickest way to freeze an older client in the middle of a tool.

The changelog also changes SHOULD to MUST in the Lifecycle Operation section, formalizing this negotiation as mandatory, not optional. Two other points in the same changelog directly affect anyone hosting servers over HTTP: the MCP-Protocol-Version header is now required on subsequent requests after the initial handshake (PR #548), and JSON-RPC batching support was removed (PR #416). If the client in your stack still sends batched requests, they stop working against a server that implements 2025-06-18 to the letter.

Testing the migration locally

Before pointing a production client at the migrated server, it's worth running the MCP Inspector locally against the server's binary or script:

bash
npx @modelcontextprotocol/inspector node build/index.js

The Inspector opens a local interface where you can call each tool manually, inspect the structuredContent returned against the declared outputSchema, and simulate the three elicitation responses (accept, decline, cancel) without depending on an already-updated production client. It's the most direct way to catch the case where the text content was accidentally removed, or where the elicitation handler doesn't handle decline.

When migration can wait

If the server only talks to an internal client you control and both sides deliberately keep negotiating version 2025-03-26, there's no immediate pressure: the change is additive to the protocol, and older servers keep responding. The risk appears when that client gets updated (a new version of Claude Desktop, an SDK, or an IDE) and starts negotiating 2025-06-18 by default, assuming features like Resource Indicators (RFC 8707) and OAuth Resource Server metadata that an older server simply doesn't implement. At that point, migration stops being optional and becomes a requirement for the server to keep authenticating and responding to calls.

Editor's note: the official changelog used as the source attributes the requirement to implement Resource Indicators (RFC 8707) to the MCP client, not the server, as protection against malicious servers improperly obtaining access tokens. The passage above inverts this attribution by suggesting it's the server that needs to implement this feature. Take this inaccuracy into account when assessing each side's obligation in the authentication flow.

Other changes in the same changelog, such as resource links in tool results (PR #603), the title field for friendly names (PR #663), and the context field in completion requests (PR #598), are additive and of lesser immediate impact: they're worth a look, but they don't block anyone who has already handled structured output and elicitation.

Translated from the Brazilian Portuguese original · Read the original

View profile →