feat: support custom HTTP response headers

src/Response.php

@@ -20,6 +20,11 @@ class Response
     use Conditionable;
     use Macroable;
 
+    /**
+     * @var array<string, string>
+     */
+    protected array $headers = [];
+
     protected function __construct(
         protected Content $content,
         protected Role $role = Role::User,
@@ -109,6 +114,24 @@ public function withMeta(array|string $meta, mixed $value = null): static
         return $this;
     }
 
+    /**
+     * @param  array<string, string>  $headers
+     */
+    public function withHeaders(array $headers): static
+    {
+        $this->headers = array_merge($this->headers, $headers);
+
+        return $this;
+    }
+
+    /**
+     * @return array<string, string>
+     */
+    public function headers(): array
+    {
+        return $this->headers;
+    }
+
     /**
      * @throws NotImplementedException
      */

src/ResponseFactory.php

@@ -85,4 +85,16 @@ public function getStructuredContent(): ?array
     {
         return $this->structuredContent;
     }
+
+    /**
+     * Get all HTTP headers from all responses.
+     *
+     * @return array<string, string>
+     */
+    public function headers(): array
+    {
+        return $this->responses
+            ->flatMap(fn (Response $response) => $response->headers())
+            ->all();
+    }
 }

src/Server.php

@@ -24,6 +24,7 @@
 use Laravel\Mcp\Server\Testing\PendingTestResponse;
 use Laravel\Mcp\Server\Testing\TestResponse;
 use Laravel\Mcp\Server\Tool;
+use Laravel\Mcp\Server\Transport\HttpTransport;
 use Laravel\Mcp\Server\Transport\JsonRpcNotification;
 use Laravel\Mcp\Server\Transport\JsonRpcRequest;
 use Laravel\Mcp\Server\Transport\JsonRpcResponse;
@@ -233,6 +234,8 @@ protected function handleMessage(JsonRpcRequest $request, ServerContext $context
     {
         $response = $this->runMethodHandle($request, $context);
 
+        $this->applyResponseHeaders();
+
         if (! is_iterable($response)) {
             $this->transport->send($response->toJson());
 
@@ -283,6 +286,33 @@ protected function generateSessionId(): string
         return Str::uuid()->toString();
     }
 
+    protected function applyResponseHeaders(): void
+    {
+        $container = Container::getInstance();
+
+        if (! $container->bound('mcp.response.factory')) {
+            return;
+        }
+
+        $responseFactory = $container->make('mcp.response.factory');
+
+        if (! $responseFactory instanceof ResponseFactory) {
+            return;
+        }
+
+        $headers = $responseFactory->headers();
+
+        if ($headers === []) {
+            return;
+        }
+
+        if ($this->transport instanceof HttpTransport) {
+            $this->transport->withHeaders($headers);
+        }
+
+        $container->forgetInstance('mcp.response.factory');
+    }
+
     /**
      * @param  array<array-key, mixed>  $arguments
      */

src/Server/Methods/Concerns/InteractsWithResponses.php

@@ -34,6 +34,8 @@ protected function toJsonRpcResponse(JsonRpcRequest $request, Response|ResponseF
             }
         });
 
+        \Illuminate\Container\Container::getInstance()->instance('mcp.response.factory', $responseFactory);
+
         return JsonRpcResponse::result($request->id, $serializable($responseFactory));
     }
 

src/Server/Transport/HttpTransport.php

@@ -12,6 +12,11 @@
 
 class HttpTransport implements Transport
 {
+    /**
+     * @var array<string, string>
+     */
+    protected array $customHeaders = [];
+
     /**
      * @param  (Closure(string): void)|null  $handler
      */
@@ -70,6 +75,16 @@ public function stream(Closure $stream): void
         $this->stream = $stream;
     }
 
+    /**
+     * @param  array<string, string>  $headers
+     */
+    public function withHeaders(array $headers): static
+    {
+        $this->customHeaders = array_merge($this->customHeaders, $headers);
+
+        return $this;
+    }
+
     protected function sendStreamMessage(string $message): void
     {
         echo 'data: '.$message."\n\n";
@@ -98,6 +113,6 @@ protected function getHeaders(): array
             $headers['X-Accel-Buffering'] = 'no';
         }
 
-        return $headers;
+        return array_merge($headers, $this->customHeaders);
     }
 }