[Server] Simplify server entrypoint with run-based transport lifecycle

README.md

@@ -108,8 +108,8 @@ $server = Server::builder()
     ->build();
 
 $transport = new StdioTransport();
-$server->connect($transport);
-$transport->listen();
+
+$server->run($transport);
 ```
 
 ### 3. Configure Your MCP Client
@@ -175,15 +175,13 @@ $server = Server::builder()
 **STDIO Transport** (Command-line integration):
 ```php
 $transport = new StdioTransport();
-$server->connect($transport);
-$transport->listen();
+$server->run($transport);
 ```
 
 **HTTP Transport** (Web-based communication):
 ```php
 $transport = new StreamableHttpTransport($request, $responseFactory, $streamFactory);
-$server->connect($transport);
-$response = $transport->listen();
+$response = $server->run($transport);
 // Handle $response in your web application
 ```
 

docs/transports.md

@@ -22,9 +22,7 @@ $server = Server::builder()
 
 $transport = new SomeTransport();
 
-$server->connect($transport);
-
-$transport->listen(); // For STDIO, or handle response for HTTP
+$result = $server->run($transport); // Blocks for STDIO, returns a response for HTTP
 ```
 
 ## STDIO Transport
@@ -70,9 +68,9 @@ $server = Server::builder()
 
 $transport = new StdioTransport();
 
-$server->connect($transport);
+$status = $server->run($transport);
 
-$transport->listen();
+exit($status); // 0 on clean shutdown, non-zero if STDIN errored
 ```
 
 ### Client Configuration
@@ -138,24 +136,20 @@ use Nyholm\Psr7\Factory\Psr17Factory;
 use Nyholm\Psr7Server\ServerRequestCreator;
 use Laminas\HttpHandlerRunner\Emitter\SapiEmitter;
 
-// Create PSR-7 request from globals
 $psr17Factory = new Psr17Factory();
 $creator = new ServerRequestCreator($psr17Factory, $psr17Factory, $psr17Factory, $psr17Factory);
 $request = $creator->fromGlobals();
 
-// Build server
 $server = Server::builder()
     ->setServerInfo('HTTP Server', '1.0.0')
     ->setDiscovery(__DIR__, ['.'])
     ->setSession(new FileSessionStore(__DIR__ . '/sessions')) // HTTP needs persistent sessions
     ->build();
 
-// Process request and get response
 $transport = new StreamableHttpTransport($request, $psr17Factory, $psr17Factory);
-$server->connect($transport);
-$response = $transport->listen();
 
-// Emit response
+$response = $server->run($transport);
+
 (new SapiEmitter())->emit($response);
 ```
 
@@ -199,8 +193,7 @@ class McpController
 
         // Process with MCP
         $transport = new StreamableHttpTransport($psrRequest, $psr17Factory, $psr17Factory);
-        $mcpServer->connect($transport);
-        $psrResponse = $transport->listen();
+        $psrResponse = $mcpServer->run($transport);
 
         // Convert PSR-7 response back to Symfony
         return $httpFoundationFactory->createResponse($psrResponse);
@@ -234,13 +227,12 @@ class McpController
     {
         $psr17Factory = new Psr17Factory();
 
-        // Create and connect the MCP HTTP transport
+        // Create the MCP HTTP transport
         $transport = new StreamableHttpTransport($request, $psr17Factory, $psr17Factory);
-        $mcpServer->connect($transport);
 
         // Process MCP request and return PSR-7 response
         // Laravel automatically handles PSR-7 responses
-        return $transport->listen();
+        return $mcpServer->run($transport);
     }
 }
 
@@ -255,33 +247,26 @@ Slim Framework works natively with PSR-7.
 Create a route handler using Slim's built-in factories and container:
 
 ```php
-use Psr\Container\ContainerInterface;
 use Slim\Factory\AppFactory;
 use Slim\Psr7\Factory\ResponseFactory;
 use Slim\Psr7\Factory\StreamFactory;
 use Mcp\Server;
 use Mcp\Server\Transport\StreamableHttpTransport;
 
 $app = AppFactory::create();
-$container = $app->getContainer();
 
-$container->set('mcpServer', function (ContainerInterface $container) {
-    return Server::builder()
+$app->any('/mcp', function ($request, $response) {
+    $mcpServer =Server::builder()
         ->setServerInfo('My MCP Server', '1.0.0')
         ->setDiscovery(__DIR__, ['.'])
         ->build();
-});
-
-$app->any('/mcp', function ($request, $response) {
-    $mcpServer = $this->get('mcpServer');
 
     $responseFactory = new ResponseFactory();
     $streamFactory = new StreamFactory();
 
     $transport = new StreamableHttpTransport($request, $responseFactory, $streamFactory);
-    $mcpServer->connect($transport);
 
-    return $transport->listen();
+    return $mcpServer->run($transport);
 });
 ```
 

examples/custom-method-handlers/server.php

@@ -137,8 +137,8 @@ public function handle(CallToolRequest|HasMethodInterface $message, SessionInter
 
 $transport = new StdioTransport(logger: logger());
 
-$server->connect($transport);
+$result = $server->run($transport);
 
-$transport->listen();
+logger()->info('Server listener stopped gracefully.', ['result' => $result]);
 
-logger()->info('Server listener stopped gracefully.');
+exit((int) $result);

examples/http-combined-registration/server.php

@@ -42,8 +42,6 @@
 
 $transport = new StreamableHttpTransport($request, $psr17Factory, $psr17Factory);
 
-$server->connect($transport);
-
-$response = $transport->listen();
+$response = $server->run($transport);
 
 (new SapiEmitter())->emit($response);

examples/http-complex-tool-schema/server.php

@@ -35,8 +35,6 @@
 
 $transport = new StreamableHttpTransport($request, $psr17Factory, $psr17Factory);
 
-$server->connect($transport);
-
-$response = $transport->listen();
+$response = $server->run($transport);
 
 (new SapiEmitter())->emit($response);

examples/http-discovery-userprofile/server.php

@@ -77,8 +77,6 @@ function (): array {
 
 $transport = new StreamableHttpTransport($request, $psr17Factory, $psr17Factory);
 
-$server->connect($transport);
-
-$response = $transport->listen();
+$response = $server->run($transport);
 
 (new SapiEmitter())->emit($response);

examples/http-schema-showcase/server.php

@@ -35,8 +35,6 @@
 
 $transport = new StreamableHttpTransport($request, $psr17Factory, $psr17Factory);
 
-$server->connect($transport);
-
-$response = $transport->listen();
+$response = $server->run($transport);
 
 (new SapiEmitter())->emit($response);

examples/stdio-cached-discovery/server.php

@@ -31,8 +31,8 @@
 
 $transport = new StdioTransport(logger: logger());
 
-$server->connect($transport);
+$result = $server->run($transport);
 
-$transport->listen();
+logger()->info('Server listener stopped gracefully.', ['result' => $result]);
 
-logger()->info('Server listener stopped gracefully.');
+exit((int) $result);

examples/stdio-custom-dependencies/server.php

@@ -39,8 +39,8 @@
 
 $transport = new StdioTransport(logger: logger());
 
-$server->connect($transport);
+$result = $server->run($transport);
 
-$transport->listen();
+logger()->info('Server listener stopped gracefully.', ['result' => $result]);
 
-logger()->info('Server listener stopped gracefully.');
+exit((int) $result);

examples/stdio-discovery-calculator/server.php

@@ -28,8 +28,8 @@
 
 $transport = new StdioTransport(logger: logger());
 
-$server->connect($transport);
+$result = $server->run($transport);
 
-$transport->listen();
+logger()->info('Server listener stopped gracefully.', ['result' => $result]);
 
-logger()->info('Server listener stopped gracefully.');
+exit((int) $result);

examples/stdio-env-variables/server.php

@@ -57,8 +57,8 @@
 
 $transport = new StdioTransport(logger: logger());
 
-$server->connect($transport);
+$result = $server->run($transport);
 
-$transport->listen();
+logger()->info('Server listener stopped gracefully.', ['result' => $result]);
 
-logger()->info('Server listener stopped gracefully.');
+exit((int) $result);

examples/stdio-explicit-registration/server.php

@@ -31,8 +31,8 @@
 
 $transport = new StdioTransport(logger: logger());
 
-$server->connect($transport);
+$result = $server->run($transport);
 
-$transport->listen();
+logger()->info('Server listener stopped gracefully.', ['result' => $result]);
 
-logger()->info('Server listener stopped gracefully.');
+exit((int) $result);

src/Server.php

@@ -35,7 +35,7 @@ public static function builder(): Builder
         return new Builder();
     }
 
-    public function connect(TransportInterface $transport): void
+    public function run(TransportInterface $transport): mixed
     {
         $transport->initialize();
 
@@ -56,5 +56,11 @@ public function connect(TransportInterface $transport): void
         $transport->onSessionEnd(function (Uuid $sessionId) {
             $this->jsonRpcHandler->destroySession($sessionId);
         });
+
+        try {
+            return $transport->listen();
+        } finally {
+            $transport->close();
+        }
     }
 }

src/Server/Transport/InMemoryTransport.php

@@ -60,9 +60,10 @@ public function listen(): mixed
 
         if (\is_callable($this->sessionDestroyListener) && null !== $this->sessionId) {
             \call_user_func($this->sessionDestroyListener, $this->sessionId);
+            $this->sessionId = null;
         }
 
-        return null;
+        return 0;
     }
 
     public function onSessionEnd(callable $listener): void
@@ -74,6 +75,7 @@ public function close(): void
     {
         if (\is_callable($this->sessionDestroyListener) && null !== $this->sessionId) {
             \call_user_func($this->sessionDestroyListener, $this->sessionId);
+            $this->sessionId = null;
         }
     }
 }

src/Server/Transport/StdioTransport.php

@@ -63,9 +63,14 @@ public function listen(): mixed
     {
         $this->logger->info('StdioTransport is listening for messages on STDIN...');
 
+        $status = 0;
         while (!feof($this->input)) {
             $line = fgets($this->input);
             if (false === $line) {
+                if (!feof($this->input)) {
+                    $status = 1;
+                }
+
                 break;
             }
 
@@ -82,9 +87,10 @@ public function listen(): mixed
 
         if (\is_callable($this->sessionEndListener) && null !== $this->sessionId) {
             \call_user_func($this->sessionEndListener, $this->sessionId);
+            $this->sessionId = null;
         }
 
-        return null;
+        return $status;
     }
 
     public function onSessionEnd(callable $listener): void
@@ -96,6 +102,7 @@ public function close(): void
     {
         if (\is_callable($this->sessionEndListener) && null !== $this->sessionId) {
             \call_user_func($this->sessionEndListener, $this->sessionId);
+            $this->sessionId = null;
         }
 
         if (\is_resource($this->input)) {

src/Server/Transport/TransportInterface.php

@@ -63,6 +63,7 @@ public function onSessionEnd(callable $listener): void;
      *
      * This method should be called when the transport is no longer needed.
      * It should clean up any resources and close any connections.
+     * `Server::run()` calls this automatically after `listen()` exits.
      */
     public function close(): void;
 }

tests/Unit/ServerTest.php

@@ -32,16 +32,15 @@ public function testJsonExceptions()
 
         $transport = $this->getMockBuilder(InMemoryTransport::class)
             ->setConstructorArgs([['foo', 'bar']])
-            ->onlyMethods(['send'])
+            ->onlyMethods(['send', 'close'])
             ->getMock();
         $transport->expects($this->exactly(2))->method('send')->willReturnOnConsecutiveCalls(
             null,
             null
         );
+        $transport->expects($this->once())->method('close');
 
         $server = new Server($handler);
-        $server->connect($transport);
-
-        $transport->listen();
+        $server->run($transport);
     }
 }