Transporte MCP stdio para sgcWebSockets

1 de junio de 2026 · Componentes

Los componentes Model Context Protocol (MCP) de sgcWebSockets ya te permiten crear servidores y clientes MCP en Delphi sobre HTTP y Streamable HTTP. Esta versión añade un tercer transporte a ambos lados: stdio. Tu servidor MCP ya puede ejecutarse sobre la entrada y salida estándar, y tu cliente MCP puede lanzar un ejecutable de servidor y comunicarse con él a través de esa frontera entre procesos. Sin escucha HTTP, sin puerto, sin configuración de TLS para uso local.

Esto importa porque stdio es la forma nativa en que los agentes modernos de programación con IA se conectan a los servidores MCP. Herramientas como Claude Code, Cursor y otros clientes MCP lanzan un servidor como proceso hijo e intercambian JSON-RPC a través de su stdin y stdout. Con este transporte, un servidor MCP en Delphi encaja directamente en ese ecosistema.

Qué es el transporte stdio

En el transporte stdio, el proceso servidor lee mensajes JSON-RPC delimitados por saltos de línea desde stdin y escribe respuestas JSON-RPC en stdout, un objeto JSON compacto por línea, codificado como UTF-8. El cliente es el dueño de la relación: arranca el ejecutable del servidor, escribe las peticiones en la tubería de entrada del hijo y lee las respuestas de su tubería de salida, emparejando cada respuesta con su petición mediante el id de JSON-RPC. Las notificaciones iniciadas por el servidor viajan por el mismo canal.

En comparación con HTTP, no hay socket ni superficie de red en absoluto. Todo ocurre a través de tuberías heredadas entre un proceso padre y un proceso hijo en la misma máquina.

Ejecutar un servidor MCP sobre stdio

El nuevo host TsgcAI_MCP_Server_Stdio envuelve el mismo núcleo MCP que utiliza el servidor HTTP, así que registras herramientas, prompts y recursos exactamente igual que antes. Compílalo como una aplicación de consola, registra tus herramientas y luego llama a Run para empezar a bombear mensajes.

uses
  SysUtils, sgcAI_MCP_Server, sgcAI_MCP_Classes, sgcAI_MCP_Types;

type
  TServerHandler = class
    procedure OnRequestTool(Sender: TObject; const aSession: TsgcAI_MCP_Session;
      const aRequest: TsgcAI_MCP_Request_ToolsCall;
      const aResponse: TsgcAI_MCP_Response_ToolsCall);
  end;

procedure TServerHandler.OnRequestTool(Sender: TObject;
  const aSession: TsgcAI_MCP_Session;
  const aRequest: TsgcAI_MCP_Request_ToolsCall;
  const aResponse: TsgcAI_MCP_Response_ToolsCall);
var
  vA, vB: Double;
begin
  if aRequest.Params.Name = 'add' then
  begin
    vA := aRequest.Params.Arguments.Node['a'].Value;
    vB := aRequest.Params.Arguments.Node['b'].Value;
    aResponse.Result.Content.AddText(FloatToStr(vA + vB));
  end;
end;

var
  oServer: TsgcAI_MCP_Server_Stdio;
  oTool: TsgcAI_MCP_Tool;
  oHandler: TServerHandler;
begin
  oHandler := TServerHandler.Create;
  oServer := TsgcAI_MCP_Server_Stdio.Create(nil);
  try
    oServer.ServerInfo.Name := 'MyDelphiServer';
    oServer.ServerInfo.Version := '1.0';

    // register a tool, exactly like the HTTP server
    oTool := oServer.MCPServer.Tools.AddTool('add', 'Adds two numbers');
    oTool.InputSchema.Properties.AddProperty('a', True, aimcpjtNumber);
    oTool.InputSchema.Properties.AddProperty('b', True, aimcpjtNumber);

    oServer.MCPServer.OnMCPRequestTool := oHandler.OnRequestTool;

    // read JSON-RPC from stdin, write responses to stdout, blocks until EOF
    oServer.Run;
  finally
    oServer.Free;
    oHandler.Free;
  end;
end.

Una regla al crear un servidor stdio: stdout es el canal del protocolo, así que nunca escribas banners ni registros en él. Envía cualquier diagnóstico a stderr o a un archivo en su lugar.

Conectar un cliente MCP sobre stdio

En el cliente, conservas la misma API pública. Selecciona el transporte stdio e indícale al cliente qué ejecutable lanzar mediante las nuevas StdioOptions. El cliente lanza el proceso, realiza el handshake de inicialización y luego expone herramientas, prompts y recursos igual que el cliente HTTP.

uses
  sgcAI_MCP_Client, sgcAI_MCP_Types;

var
  oClient: TsgcWSAPI_Client_MCP;
begin
  oClient := TsgcWSAPI_Client_MCP.Create(nil);
  try
    // select the stdio transport and point it at the server executable
    oClient.MCPOptions.Transport := aimcptrStdio;
    oClient.MCPOptions.StdioOptions.Command := 'C:\MyServer\MyDelphiServer.exe';
    oClient.MCPOptions.StdioOptions.Arguments := '--stdio';
    oClient.MCPOptions.StdioOptions.WorkingDir := 'C:\MyServer';
    oClient.MCPOptions.StdioOptions.Timeout := 20000;

    // the client launches the server and runs the MCP handshake
    oClient.Initialize;

    // discover tools and call one, the result arrives in OnMCPResponseTool
    oClient.ListTools;
    oClient.RequestTool('add', BuildArguments(2, 3));
  finally
    oClient.Free;
  end;
end;

La respuesta se entrega a través del evento habitual OnMCPResponseTool, y las notificaciones del servidor llegan a través de OnMCPLoggingMessage, OnMCPProgress y los demás eventos de notificación, idéntico al transporte HTTP. StdioOptions también acepta entradas Environment cuando el proceso hijo necesita variables de entorno específicas.

Úsalo con Claude Code y otros agentes de IA

Como el transporte sigue la convención MCP stdio, cualquier cliente MCP compatible puede lanzar tu servidor en Delphi. Para registrarlo con Claude Code, añade una entrada a la configuración MCP que apunte a tu ejecutable.

{
  "mcpServers": {
    "my-delphi-server": {
      "command": "C:\\MyServer\\MyDelphiServer.exe",
      "args": ["--stdio"]
    }
  }
}

El agente lanza el servidor bajo demanda, lista las herramientas que registraste y las invoca mientras trabaja. Tu código Delphi se convierte en un proveedor de herramientas de primera clase para asistentes de IA, sin servidor web que desplegar ni proteger.

Ventajas

Sin superficie de red. No hay puerto que abrir, ni escucha HTTP, ni TLS o autenticación que configurar para uso local. La comunicación es puro stdin y stdout.
El patrón local nativo. Las herramientas de programación con IA como Claude Code y Cursor lanzan servidores MCP sobre stdio, así que tu servidor se integra sin adaptador.
Ciclo de vida limpio y aislamiento. El servidor vive y muere con el proceso cliente. Un servidor por cliente, sin estado compartido y sin escuchas residuales.
La misma API de MCP. Las herramientas, los prompts y los recursos se registran de la misma manera que en el servidor HTTP. Cambiar el transporte en el cliente es una sola propiedad.
Ideal para uso de escritorio y sin conexión. Cuando exponer un endpoint HTTP es innecesario o no deseable, stdio mantiene todo dentro de la máquina local.
Trama robusta. JSON-RPC delimitado por saltos de línea sobre UTF-8, con tolerancia a una marca de orden de bytes inicial en los mensajes entrantes para una amplia compatibilidad con los clientes.

Actualización

El transporte stdio es una incorporación lista para usar. Los servidores y clientes HTTP y Streamable HTTP existentes no cambian, y el nuevo transporte reutiliza el mismo modelo de herramientas, prompts y recursos, así que no hay nada que migrar. Para adoptarlo, compila tu servidor como una aplicación de consola en torno a TsgcAI_MCP_Server_Stdio, o establece Transport en aimcptrStdio en el cliente. Puedes descargar la última versión desde la página de descarga de sgcWebSockets.

¿Tienes preguntas, comentarios o necesitas ayuda con la migración? Ponte en contacto, recibirás respuesta de las personas que escribieron el código.