adds optional stateless configuration (#222)

* optional statelessness

* Update config.ts

* Update docker-compose.yml

* Update documentation

---------

Co-authored-by: Harold Spencer Jr. <hspencer@brave.com>

Author: jonathansampson

README.md

@@ -114,11 +114,12 @@ The server supports the following environment variables:
 
 - `BRAVE_API_KEY`: Your Brave Search API key (required)
 - `BRAVE_MCP_TRANSPORT`: Transport mode ("http" or "stdio", default: "stdio")
-- `BRAVE_MCP_PORT`: HTTP server port (default: 8080)
+- `BRAVE_MCP_PORT`: HTTP server port (default: 8000)
 - `BRAVE_MCP_HOST`: HTTP server host (default: "0.0.0.0")
 - `BRAVE_MCP_LOG_LEVEL`: Desired logging level("debug", "info", "notice", "warning", "error", "critical", "alert", or "emergency", default: "info")
 - `BRAVE_MCP_ENABLED_TOOLS`: When used, specifies a whitelist for supported tools
 - `BRAVE_MCP_DISABLED_TOOLS`: When used, specifies a blacklist for supported tools
+- `BRAVE_MCP_STATELESS`: HTTP stateless mode (default: "true").  When running on Amazon Bedrock Agentcore, set to "true".
 
 ### Command Line Options
 
@@ -133,6 +134,7 @@ Options:
   --logging-level <string>    Desired logging level (one of _debug_, _info_, _notice_, _warning_, _error_, _critical_, _alert_, or _emergency_)
   --enabled-tools             Tools whitelist (only the specified tools will be enabled)
   --disabled-tools            Tools blacklist (included tools will be disabled)
+  --stateless  <boolean>      HTTP Stateless flag
 ```
 
 ## Installation

docker-compose.yml

@@ -11,6 +11,7 @@ services:
       - BRAVE_API_KEY
       - BRAVE_MCP_TRANSPORT=http
       - BRAVE_MCP_PORT=8080
+      - BRAVE_MCP_STATELESS
       - BRAVE_MCP_HOST=0.0.0.0
       - BRAVE_MCP_LOG_LEVEL=info
       - BRAVE_MCP_ENABLED_TOOLS

marketplace-revision-release.json

@@ -43,9 +43,9 @@
                                         "Description": "MCP protocol transport mode.  Supported values are \"http\" or \"stdio\", however Bedrock Agentcore only supports \"http\" (reference https://docs.aws.amazon.com/marketplace/latest/userguide/bedrock-agentcore-runtime.html#agentcore-container-requirements)."
                                     },
                                     {
-                                        "DefaultValue": "8080",
+                                        "DefaultValue": "8000",
                                         "Name": "BRAVE_MCP_PORT",
-                                        "Description": "HTTP server port (default: 8080).  Mandatory port for Bedrock Agentcore is 8080 (reference https://docs.aws.amazon.com/marketplace/latest/userguide/bedrock-agentcore-runtime.html#agentcore-container-requirements)."
+                                        "Description": "HTTP server port (default: 8000).  Mandatory port for Bedrock Agentcore is 8000 (reference https://docs.aws.amazon.com/marketplace/latest/userguide/bedrock-agentcore-runtime.html#agentcore-container-requirements)."
                                     },
                                     {
                                         "DefaultValue": "0.0.0.0",
@@ -64,6 +64,11 @@
                                     {
                                         "Name": "BRAVE_MCP_DISABLED_TOOLS",
                                         "Description": "*Optional* When used, specifies a blacklist for supported tools"
+                                    },
+                                    {
+                                        "DefaultValue": "true",
+                                        "Name": "BRAVE_MCP_STATELESS",
+                                        "Description": "Sets HTTP Stateless mode (default: true). When deploying on Bedrock Agentcore, this should be set to true."
                                     }
                                 ]
                             }

src/config.ts

@@ -34,6 +34,11 @@ export const configSchema = z.object({
     .default('info')
     .describe('Desired logging level')
     .optional(),
+  stateless: z
+    .boolean()
+    .default(false)
+    .describe('Whether the server should be stateless')
+    .optional(),
 });
 
 export type SmitheryConfig = z.infer<typeof configSchema>;
@@ -46,6 +51,7 @@ type Configuration = {
   loggingLevel: LoggingLevel;
   enabledTools: string[];
   disabledTools: string[];
+  stateless: boolean;
 };
 
 const state: Configuration & { ready: boolean } = {
@@ -57,6 +63,7 @@ const state: Configuration & { ready: boolean } = {
   ready: false,
   enabledTools: [],
   disabledTools: [],
+  stateless: false,
 };
 
 export function isToolPermittedByUser(toolName: string): boolean {
@@ -77,12 +84,12 @@ export function getOptions(): Configuration | false {
     .option(
       '--enabled-tools <names...>',
       'tools to enable',
-      process.env.BRAVE_MCP_ENABLED_TOOLS?.split(' ') ?? []
+      process.env.BRAVE_MCP_ENABLED_TOOLS?.trim().split(' ') ?? []
     )
     .option(
       '--disabled-tools <names...>',
       'tools to disable',
-      process.env.BRAVE_MCP_DISABLED_TOOLS?.split(' ') ?? []
+      process.env.BRAVE_MCP_DISABLED_TOOLS?.trim().split(' ') ?? []
     )
     .option(
       '--port <number>',
@@ -94,6 +101,11 @@ export function getOptions(): Configuration | false {
       'desired host for HTTP transport',
       process.env.BRAVE_MCP_HOST ?? '0.0.0.0'
     )
+    .option(
+      '--stateless <boolean>',
+      'whether the server should be stateless',
+      process.env.BRAVE_MCP_STATELESS === 'true' ? true : false
+    )
     .allowUnknownOption()
     .parse(process.argv);
 
@@ -108,7 +120,11 @@ export function getOptions(): Configuration | false {
     return false;
   }
 
-  if ([...enabledTools, ...disabledTools].some((t) => !toolNames.includes(t))) {
+  if (
+    [...enabledTools, ...disabledTools].some(
+      (t) => t.trim().length > 0 && !toolNames.includes(t.trim())
+    )
+  ) {
     console.error(`Invalid tool name used. Must be one of: ${toolNames.join(', ')}`);
     return false;
   }
@@ -149,6 +165,9 @@ export function getOptions(): Configuration | false {
     }
   }
 
+  // Normalize stateless to boolean (CLI passes it as string)
+  options.stateless = options.stateless === true || options.stateless === 'true';
+
   // Update state
   state.braveApiKey = options.braveApiKey;
   state.transport = options.transport;
@@ -157,6 +176,7 @@ export function getOptions(): Configuration | false {
   state.loggingLevel = options.loggingLevel;
   state.enabledTools = options.enabledTools;
   state.disabledTools = options.disabledTools;
+  state.stateless = options.stateless;
   state.ready = true;
 
   return options as Configuration;

src/protocols/http.ts

@@ -37,13 +37,22 @@ const getTransport = async (request: Request): Promise<StreamableHTTPServerTrans
     return transport;
   }
 
-  // Otherwise, start a new transport/session
-  const transport = new StreamableHTTPServerTransport({
-    sessionIdGenerator: () => randomUUID(),
-    onsessioninitialized: (sessionId) => {
-      transports.set(sessionId, transport);
-    },
-  });
+  let transport: StreamableHTTPServerTransport;
+
+  if (config.stateless) {
+    // Some contexts (e.g. AgentCore) may prefer or require a stateless transport
+    transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined,
+    });
+  } else {
+    // Otherwise, start a new transport/session
+    transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => randomUUID(),
+      onsessioninitialized: (sessionId) => {
+        transports.set(sessionId, transport);
+      },
+    });
+  }
 
   const mcpServer = createMcpServer();
   await mcpServer.connect(transport);