feat: allow securing SSE transport with secret

README.md

@@ -76,6 +76,7 @@ The Playwright MCP server supports the following command-line options:
 - `--user-data-dir <path>`: Path to the user data directory
 - `--port <port>`: Port to listen on for SSE transport
 - `--host <host>`: Host to bind server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.
+- `--secret`: Secret used to secure the SSE transport. 
 - `--allowed-origins <origins>`: Semicolon-separated list of origins to allow the browser to request. Default is to allow all. Origins matching both `--allowed-origins` and `--blocked-origins` will be blocked.
 - `--blocked-origins <origins>`: Semicolon-separated list of origins to block the browser to request. Origins matching both `--allowed-origins` and `--blocked-origins` will be blocked.
 - `--vision`: Run server that uses screenshots (Aria snapshots are used by default)

config.d.ts

@@ -89,6 +89,11 @@ export type Config = {
    */
   vision?: boolean;
 
+  /**
+   * Secret used to secure the SSE transport.
+   */
+  secret?: string;
+
   /**
    * The directory to save output files.
    */

src/config.ts

@@ -40,6 +40,7 @@ export type CLIOptions = {
   blockedOrigins?: string[];
   outputDir?: string;
   noImageResponses?: boolean;
+  secret?: string;
 };
 
 const defaultConfig: Config = {
@@ -122,6 +123,7 @@ export async function configFromCLIOptions(cliOptions: CLIOptions): Promise<Conf
       blockedOrigins: cliOptions.blockedOrigins,
     },
     outputDir: cliOptions.outputDir,
+    secret: cliOptions.secret,
   };
 }
 

src/program.ts

@@ -34,6 +34,7 @@ program
     .option('--user-data-dir <path>', 'Path to the user data directory')
     .option('--port <port>', 'Port to listen on for SSE transport.')
     .option('--host <host>', 'Host to bind server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.')
+    .option('--secret <secret>', 'Secret used to secure the SSE transport.')
     .option('--allowed-origins <origins>', 'Semicolon-separated list of origins to allow the browser to request. Default is to allow all.', semicolonSeparatedList)
     .option('--blocked-origins <origins>', 'Semicolon-separated list of origins to block the browser from requesting. Blocklist is evaluated before allowlist. If used without the allowlist, requests not matching the blocklist are still allowed.', semicolonSeparatedList)
     .option('--vision', 'Run server that uses screenshots (Aria snapshots are used by default)')

src/transport.ts

@@ -49,7 +49,11 @@ async function handleSSE(config: Config, req: http.IncomingMessage, res: http.Se
 
     return await transport.handlePostMessage(req, res);
   } else if (req.method === 'GET') {
-    const transport = new SSEServerTransport('/sse', res);
+    let url = '/sse';
+    if (config.secret)
+      url += '?' + new URLSearchParams({ secret: config.secret });
+
+    const transport = new SSEServerTransport(url, res);
     sessions.set(transport.sessionId, transport);
     const connection = await createConnection(config);
     await connection.connect(transport);
@@ -109,6 +113,11 @@ export function startHttpTransport(config: Config, port: number, hostname: strin
   const streamableSessions = new Map<string, StreamableHTTPServerTransport>();
   const httpServer = http.createServer(async (req, res) => {
     const url = new URL(`http://localhost${req.url}`);
+    if (config.secret && url.searchParams.get('secret') !== config.secret) {
+      res.statusCode = 403;
+      return res.end('Forbidden');
+    }
+
     if (url.pathname.startsWith('/mcp'))
       await handleStreamable(config, req, res, streamableSessions, connectionList);
     else
@@ -117,23 +126,28 @@ export function startHttpTransport(config: Config, port: number, hostname: strin
   httpServer.listen(port, hostname, () => {
     const address = httpServer.address();
     assert(address, 'Could not bind server socket');
-    let url: string;
+    let baseUrl: string;
     if (typeof address === 'string') {
-      url = address;
+      baseUrl = address;
     } else {
       const resolvedPort = address.port;
       let resolvedHost = address.family === 'IPv4' ? address.address : `[${address.address}]`;
       if (resolvedHost === '0.0.0.0' || resolvedHost === '[::]')
         resolvedHost = 'localhost';
-      url = `http://${resolvedHost}:${resolvedPort}`;
+      baseUrl = `http://${resolvedHost}:${resolvedPort}`;
     }
+
+    const sseUrl = new URL('/sse', baseUrl);
+    if (config.secret)
+      sseUrl.searchParams.set('secret', config.secret);
+
     const message = [
-      `Listening on ${url}`,
+      `Listening on ${baseUrl}`,
       'Put this in your client config:',
       JSON.stringify({
         'mcpServers': {
           'playwright': {
-            'url': `${url}/sse`
+            'url': `${sseUrl}`
           }
         }
       }, undefined, 2),

tests/sse.spec.ts

@@ -19,22 +19,31 @@ import { spawn } from 'node:child_process';
 import path from 'node:path';
 import { test as baseTest } from './fixtures.js';
 import { expect } from 'playwright/test';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
 
 // NOTE: Can be removed when we drop Node.js 18 support and changed to import.meta.filename.
 const __filename = url.fileURLToPath(import.meta.url);
 
-const test = baseTest.extend<{ serverEndpoint: string }>({
+const test = baseTest.extend<{ serverEndpoint: URL }>({
   serverEndpoint: async ({}, use) => {
-    const cp = spawn('node', [path.join(path.dirname(__filename), '../cli.js'), '--port', '0'], { stdio: 'pipe' });
+    const cp = spawn('node', [path.join(path.dirname(__filename), '../cli.js'), '--port', '0', '--secret', 'mySecretValue'], { stdio: 'pipe' });
     try {
       let stdout = '';
-      const url = await new Promise<string>(resolve => cp.stdout?.on('data', data => {
+      const url = await new Promise<URL>(resolve => cp.stdout?.on('data', data => {
         stdout += data.toString();
         const match = stdout.match(/Listening on (http:\/\/.*)/);
-        if (match)
-          resolve(match[1]);
+        if (match) {
+          const baseURL = new URL(match[1]);
+          baseURL.searchParams.set('secret', 'mySecretValue');
+          resolve(baseURL);
+        }
       }));
 
+      cp.stderr.pipe(process.stderr);
+      cp.stdout.pipe(process.stdout);
+
       await use(url);
     } finally {
       cp.kill();
@@ -43,22 +52,32 @@ const test = baseTest.extend<{ serverEndpoint: string }>({
 });
 
 test('sse transport', async ({ serverEndpoint }) => {
-  // need dynamic import b/c of some ESM nonsense
-  const { SSEClientTransport } = await import('@modelcontextprotocol/sdk/client/sse.js');
-  const { Client } = await import('@modelcontextprotocol/sdk/client/index.js');
-  const transport = new SSEClientTransport(new URL(serverEndpoint));
+  const transport = new SSEClientTransport(serverEndpoint);
   const client = new Client({ name: 'test', version: '1.0.0' });
   await client.connect(transport);
   await client.ping();
 });
 
+test('sse transport auth', async ({ serverEndpoint }) => {
+  serverEndpoint.searchParams.delete('secret');
+  const transport = new SSEClientTransport(serverEndpoint);
+  const client = new Client({ name: 'test', version: '1.0.0' });
+  await expect(() => client.connect(transport)).rejects.toThrow(/403/);
+});
+
 test('streamable http transport', async ({ serverEndpoint }) => {
-  // need dynamic import b/c of some ESM nonsense
-  const { StreamableHTTPClientTransport } = await import('@modelcontextprotocol/sdk/client/streamableHttp.js');
-  const { Client } = await import('@modelcontextprotocol/sdk/client/index.js');
-  const transport = new StreamableHTTPClientTransport(new URL('/mcp', serverEndpoint));
+  serverEndpoint.pathname = '/mcp';
+  const transport = new StreamableHTTPClientTransport(serverEndpoint);
   const client = new Client({ name: 'test', version: '1.0.0' });
   await client.connect(transport);
   await client.ping();
   expect(transport.sessionId, 'has session support').toBeDefined();
 });
+
+test('streamable http transport auth', async ({ serverEndpoint }) => {
+  serverEndpoint.pathname = '/mcp';
+  serverEndpoint.searchParams.delete('secret');
+  const transport = new StreamableHTTPClientTransport(serverEndpoint);
+  const client = new Client({ name: 'test', version: '1.0.0' });
+  await expect(() => client.connect(transport)).rejects.toThrow(/403/);
+});