MCP Client | Protocol Versions

TsgcWSAPIClient_MCP talks to servers of both MCP eras. Servers that implement 2025-11-25 or older start with initialize and keep a session (Mcp-Session-Id). Servers that implement 2026-07-28 are stateless: there is no initialize and no session, every request carries the protocol version, the client information and the client capabilities in _meta, and the client learns the server features with server/discover.

 

Choosing the era

The property MCPOptions.ProtocolEra selects how the client connects when you call Initialize.

• aimcpeAuto (default): the client sends a server/discover probe. If the server answers, the modern era is used, otherwise the client falls back to the legacy initialize handshake.
• aimcpeModern: always uses the protocol version 2026-07-28.
• aimcpeLegacy: always uses initialize and a session, exactly as in previous releases.

 

Fallback rules (Auto)

• HTTP transports: the client falls back to legacy when the probe returns HTTP 400, 404 or 405, or one of the JSON-RPC errors -32020, -32021, -32022 or -32601.
• stdio transport: the client falls back to legacy on -32020, -32021 or -32022, and when a legacy server answers -32601. If the process does not answer the probe in time (the lower of 5 seconds and StdioOptions.Timeout) the client uses legacy too.
• -32022 Unsupported protocol version: the client reads the versions supported by the server from the error data and picks the highest version both sides support. It retries once in the modern era or falls back to legacy.
• Other failures, like HTTP 401, 403 or 5xx, never trigger a fallback. They are reported through OnError with the text MCP: HTTP <code> (followed by up to 200 characters of the body) and Initialize returns False.

 

The era detected for an endpoint is cached, so the next Initialize against the same URL or command does not repeat the probe.

Negotiated values

After Initialize the following public properties describe the connection:

• NegotiatedEra: aimcpeModern or aimcpeLegacy.
• NegotiatedProtocolVersion: the protocol version in use, for example 2026-07-28 or 2025-11-25.
• ServerDiscover: the server/discover result (supported versions, capabilities and instructions). It is nil in the legacy era.

 

Discovery

In the modern era the component raises OnMCPDiscover with the server/discover result during Initialize. Set Accept to False to reject the server, then Initialize returns False. OnMCPInitialize is only raised in the legacy era. Call the method Discover at any time to read the server features again.

What changes in the modern era

• Every request includes _meta with protocolVersion, clientInfo and clientCapabilities.
• HTTP requests carry the headers MCP-Protocol-Version, Mcp-Method and Mcp-Name (base64 encoded when the value has characters that are not allowed in a header).
• There is no session id, no notifications/initialized and no GET stream. The heartbeat ping is not used.
• If a request fails with -32022 the client retries it once with a version the server supports.
• Responses sent as text/event-stream are parsed, so log and progress notifications that come before the result are processed.
• Notifications are received through subscriptions instead of the session stream.

 

x-mcp-header parameters

A modern server can mark tool arguments with x-mcp-header in the input schema. The client reads these declarations when it receives the tools/list result and, on every tools/call of that tool, sends the argument value in a Mcp-Param-<Name> HTTP header. Integers are sent as numbers and booleans in lowercase. Tools with an invalid declaration are removed from the list and reported through OnError with the text MCP tool "<name>" ignored: <reason>.

Sample code

Connect with automatic era detection, log the negotiated version and reject servers that do not publish tools.

procedure TForm1.Connect;
begin
  MCP.MCPOptions.HttpOptions.URL := 'https://localhost:8080/mcp';
  MCP.MCPOptions.ProtocolEra := aimcpeAuto;
  MCP.OnMCPDiscover := MCPDiscover;
  MCP.OnError := MCPError;
  if MCP.Initialize then
  begin
    if MCP.NegotiatedEra = aimcpeModern then
      Log('modern: ' + MCP.NegotiatedProtocolVersion)
    else
      Log('legacy: ' + MCP.NegotiatedProtocolVersion);
  end;
end;

procedure TForm1.MCPDiscover(Sender: TObject;
  const aRequest: TsgcAI_MCP_Request_ServerDiscover;
  const aResponse: TsgcAI_MCP_Response_ServerDiscover; var Accept: Boolean);
begin
  Log('versions: ' + aResponse.SupportedVersions.CommaText);
  Log('instructions: ' + aResponse.Instructions);
end;

procedure TForm1.MCPError(Connection: TsgcWSConnection; const Error: string);
begin
  Log('error: ' + Error);
end;