feat: add streamable http [MCP-55] (#359)

Author: fmenezes

.github/workflows/check.yml

@@ -55,4 +55,4 @@ jobs:
           rm -rf node_modules
           npm pkg set scripts.prepare="exit 0"
           npm install --omit=dev
-      - run: npx -y @modelcontextprotocol/inspector --cli --method tools/list -- node dist/index.js --connectionString "mongodb://localhost"
+      - run: npx -y @modelcontextprotocol/inspector --cli --method tools/list -- node dist/index.js

Dockerfile

@@ -4,6 +4,7 @@ RUN addgroup -S mcp && adduser -S mcp -G mcp
 RUN npm install -g mongodb-mcp-server@${VERSION}
 USER mcp
 WORKDIR /home/mcp
+ENV MDB_MCP_LOGGERS=stderr,mcp
 ENTRYPOINT ["mongodb-mcp-server"]
 LABEL maintainer="MongoDB Inc <[email protected]>"
 LABEL description="MongoDB MCP Server"

README.md

@@ -225,6 +225,27 @@ With Atlas API credentials:
 }
 ```
 
+#### Option 6: Running as an HTTP Server
+
+You can run the MongoDB MCP Server as an HTTP server instead of the default stdio transport. This is useful if you want to interact with the server over HTTP, for example from a web client or to expose the server on a specific port.
+
+To start the server with HTTP transport, use the `--transport http` option:
+
+```shell
+npx -y mongodb-mcp-server --transport http
+```
+
+By default, the server will listen on `http://127.0.0.1:3000`. You can customize the host and port using the `--httpHost` and `--httpPort` options:
+
+```shell
+npx -y mongodb-mcp-server --transport http --httpHost=0.0.0.0 --httpPort=8080
+```
+
+- `--httpHost` (default: 127.0.0.1): The host to bind the HTTP server.
+- `--httpPort` (default: 3000): The port number for the HTTP server.
+
+> **Note:** The default transport is `stdio`, which is suitable for integration with most MCP clients. Use `http` transport if you need to interact with the server over HTTP.
+
 ## 🛠️ Supported Tools
 
 ### Tool List
@@ -278,23 +299,53 @@ The MongoDB MCP Server can be configured using multiple methods, with the follow
 
 ### Configuration Options
 
-| Option             | Description                                                                                                                                                   |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `apiClientId`      | Atlas API client ID for authentication. Required for running Atlas tools.                                                                                     |
-| `apiClientSecret`  | Atlas API client secret for authentication. Required for running Atlas tools.                                                                                 |
-| `connectionString` | MongoDB connection string for direct database connections. Optional, if not set, you'll need to call the `connect` tool before interacting with MongoDB data. |
-| `logPath`          | Folder to store logs.                                                                                                                                         |
-| `disabledTools`    | An array of tool names, operation types, and/or categories of tools that will be disabled.                                                                    |
-| `readOnly`         | When set to true, only allows read, connect, and metadata operation types, disabling create/update/delete operations.                                         |
-| `indexCheck`       | When set to true, enforces that query operations must use an index, rejecting queries that perform a collection scan.                                         |
-| `telemetry`        | When set to disabled, disables telemetry collection.                                                                                                          |
+| Option             | Default    | Description                                                                                                                                                   |
+| ------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `apiClientId`      | <not set>  | Atlas API client ID for authentication. Required for running Atlas tools.                                                                                     |
+| `apiClientSecret`  | <not set>  | Atlas API client secret for authentication. Required for running Atlas tools.                                                                                 |
+| `connectionString` | <not set>  | MongoDB connection string for direct database connections. Optional, if not set, you'll need to call the `connect` tool before interacting with MongoDB data. |
+| `loggers`          | disk,mcp   | Comma separated values, possible values are `mcp`, `disk` and `stderr`. See [Logger Options](#logger-options) for details.                                    |
+| `logPath`          | see note\* | Folder to store logs.                                                                                                                                         |
+| `disabledTools`    | <not set>  | An array of tool names, operation types, and/or categories of tools that will be disabled.                                                                    |
+| `readOnly`         | false      | When set to true, only allows read, connect, and metadata operation types, disabling create/update/delete operations.                                         |
+| `indexCheck`       | false      | When set to true, enforces that query operations must use an index, rejecting queries that perform a collection scan.                                         |
+| `telemetry`        | enabled    | When set to disabled, disables telemetry collection.                                                                                                          |
+| `transport`        | stdio      | Either 'stdio' or 'http'.                                                                                                                                     |
+| `httpPort`         | 3000       | Port number.                                                                                                                                                  |
+| `httpHost`         | 127.0.0.1  | Host to bind the http server.                                                                                                                                 |
+
+#### Logger Options
+
+The `loggers` configuration option controls where logs are sent. You can specify one or more logger types as a comma-separated list. The available options are:
+
+- `mcp`: Sends logs to the MCP client (if supported by the client/transport).
+- `disk`: Writes logs to disk files. Log files are stored in the log path (see `logPath` above).
+- `stderr`: Outputs logs to standard error (stderr), useful for debugging or when running in containers.
+
+**Default:** `disk,mcp` (logs are written to disk and sent to the MCP client).
+
+You can combine multiple loggers, e.g. `--loggers disk,stderr` or `export MDB_MCP_LOGGERS="mcp,stderr"`.
+
+##### Example: Set logger via environment variable
+
+```shell
+export MDB_MCP_LOGGERS="disk,stderr"
+```
+
+##### Example: Set logger via command-line argument
+
+```shell
+npx -y mongodb-mcp-server --loggers mcp,stderr
+```
+
+##### Log File Location
 
-#### Log Path
+When using the `disk` logger, log files are stored in:
 
-Default log location is as follows:
+- **Windows:** `%LOCALAPPDATA%\mongodb\mongodb-mcp\.app-logs`
+- **macOS/Linux:** `~/.mongodb/mongodb-mcp/.app-logs`
 
-- Windows: `%LOCALAPPDATA%\mongodb\mongodb-mcp\.app-logs`
-- macOS/Linux: `~/.mongodb/mongodb-mcp/.app-logs`
+You can override the log directory with the `logPath` option.
 
 #### Disabled Tools
 

package-lock.json

@@ -37,6 +37,7 @@
     "@jest/globals": "^30.0.4",
     "@modelcontextprotocol/inspector": "^0.16.0",
     "@redocly/cli": "^1.34.4",
+    "@types/express": "^5.0.1",
     "@types/jest": "^30.0.0",
     "@types/node": "^24.0.12",
     "@types/simple-oauth2": "^5.0.7",
@@ -65,6 +66,7 @@
     "@mongodb-js/devtools-connect": "^3.7.2",
     "@mongosh/service-provider-node-driver": "^3.6.0",
     "bson": "^6.10.4",
+    "express": "^5.1.0",
     "lru-cache": "^11.1.0",
     "mongodb": "^6.17.0",
     "mongodb-connection-string-url": "^3.0.2",

package.json

@@ -17,13 +17,17 @@ export interface UserConfig {
     apiBaseUrl: string;
     apiClientId?: string;
     apiClientSecret?: string;
-    telemetry?: "enabled" | "disabled";
+    telemetry: "enabled" | "disabled";
     logPath: string;
     connectionString?: string;
     connectOptions: ConnectOptions;
     disabledTools: Array<string>;
     readOnly?: boolean;
     indexCheck?: boolean;
+    transport: "stdio" | "http";
+    httpPort: number;
+    httpHost: string;
+    loggers: Array<"stderr" | "disk" | "mcp">;
 }
 
 const defaults: UserConfig = {
@@ -39,6 +43,10 @@ const defaults: UserConfig = {
     telemetry: "enabled",
     readOnly: false,
     indexCheck: false,
+    transport: "stdio",
+    httpPort: 3000,
+    httpHost: "127.0.0.1",
+    loggers: ["disk", "mcp"],
 };
 
 export const config = {

src/common/config.ts

@@ -12,6 +12,7 @@ export const LogId = {
     serverCloseRequested: mongoLogId(1_000_003),
     serverClosed: mongoLogId(1_000_004),
     serverCloseFailure: mongoLogId(1_000_005),
+    serverDuplicateLoggers: mongoLogId(1_000_006),
 
     atlasCheckCredentials: mongoLogId(1_001_001),
     atlasDeleteDatabaseUserFailure: mongoLogId(1_001_002),
@@ -37,9 +38,16 @@ export const LogId = {
     mongodbDisconnectFailure: mongoLogId(1_004_002),
 
     toolUpdateFailure: mongoLogId(1_005_001),
+
+    streamableHttpTransportStarted: mongoLogId(1_006_001),
+    streamableHttpTransportSessionInitialized: mongoLogId(1_006_002),
+    streamableHttpTransportRequestFailure: mongoLogId(1_006_003),
+    streamableHttpTransportCloseRequested: mongoLogId(1_006_004),
+    streamableHttpTransportCloseSuccess: mongoLogId(1_006_005),
+    streamableHttpTransportCloseFailure: mongoLogId(1_006_006),
 } as const;
 
-abstract class LoggerBase {
+export abstract class LoggerBase {
     abstract log(level: LogLevel, id: MongoLogId, context: string, message: string): void;
 
     info(id: MongoLogId, context: string, message: string): void {
@@ -74,14 +82,14 @@ abstract class LoggerBase {
     }
 }
 
-class ConsoleLogger extends LoggerBase {
+export class ConsoleLogger extends LoggerBase {
     log(level: LogLevel, id: MongoLogId, context: string, message: string): void {
         message = redact(message);
-        console.error(`[${level.toUpperCase()}] ${id.__value} - ${context}: ${message}`);
+        console.error(`[${level.toUpperCase()}] ${id.__value} - ${context}: ${message} (${process.pid})`);
     }
 }
 
-class DiskLogger extends LoggerBase {
+export class DiskLogger extends LoggerBase {
     private constructor(private logWriter: MongoLogWriter) {
         super();
     }
@@ -133,7 +141,7 @@ class DiskLogger extends LoggerBase {
     }
 }
 
-class McpLogger extends LoggerBase {
+export class McpLogger extends LoggerBase {
     constructor(private server: McpServer) {
         super();
     }
@@ -152,18 +160,12 @@ class McpLogger extends LoggerBase {
 }
 
 class CompositeLogger extends LoggerBase {
-    private loggers: LoggerBase[];
+    private loggers: LoggerBase[] = [];
 
     constructor(...loggers: LoggerBase[]) {
         super();
 
-        if (loggers.length === 0) {
-            // default to ConsoleLogger
-            this.loggers = [new ConsoleLogger()];
-            return;
-        }
-
-        this.loggers = [...loggers];
+        this.setLoggers(...loggers);
     }
 
     setLoggers(...loggers: LoggerBase[]): void {
@@ -180,19 +182,5 @@ class CompositeLogger extends LoggerBase {
     }
 }
 
-const logger = new CompositeLogger();
+const logger = new CompositeLogger(new ConsoleLogger());
 export default logger;
-
-export async function setStdioPreset(server: McpServer, logPath: string): Promise<void> {
-    const diskLogger = await DiskLogger.fromPath(logPath);
-    const mcpLogger = new McpLogger(server);
-
-    logger.setLoggers(mcpLogger, diskLogger);
-}
-
-export function setContainerPreset(server: McpServer): void {
-    const mcpLogger = new McpLogger(server);
-    const consoleLogger = new ConsoleLogger();
-
-    logger.setLoggers(mcpLogger, consoleLogger);
-}