MongoDB MCP Server

The ToolBase is the abstract foundation for all tools in the MCP server. It manages the lifecycle, configuration, and execution of a tool.

Core Lifecycle and Methods

• invoke(args, context): The primary method to trigger tool execution.
• enable() / disable(): Methods to control the availability of the tool.
• requiresConfirmation(): Indicates if the tool requires user approval before execution.
• normalizeRawArgs(args): Used to clean and prepare incoming raw arguments.
• execute(args, context): The internal method implemented by subclasses to perform the actual logic.

Key Properties

• name: The unique identifier for the tool.
• category: The ToolCategory this tool belongs to (mongodb, atlas, atlas-local, or assistant).
• operationType: The type of operation the tool performs.
• outputSchema: A Zod schema defining the structure of the tool's return value.

MongoDB connections are managed in an app-level MCPConnectionStore. You can extend connection management in two ways:

1. Custom dialing, default bookkeeping: Construct your own MCPConnectionStore with a custom createConnectionManager. This is ideal if you want to use your own connection logic while keeping standard handle semantics (IDs, connection limits). You provide a view of this store to sessions via sessionOptions.connectionRegistry by overriding createServerForRequest in a StreamableHttpRunner.

2. Full ownership: Implement the ConnectionRegistry interface yourself and supply it per session via sessionOptions.connectionRegistry. This is used for multi-tenant scoping or backing connections with durable storage. The server calls registry.close() when a session ends; you decide if that should release resources or be a no-op.

import {
  MCPConnectionStore,
  StreamableHttpRunner,
  UserConfigSchema,
} from "mongodb-mcp-server";
import type { Server, TransportRequestContext } from "mongodb-mcp-server";

// Extend StreamableHttpRunner and override createServerForRequest to serve
// sessions from a store you own.
class CustomStreamableHttpRunner extends StreamableHttpRunner {
  private readonly connectionStore = new MCPConnectionStore({
    userConfig: this.userConfig,
    logger: this.logger,
    deviceId: this.deviceId,
    createConnectionManager: () => new MyConnectionManager(),
  });

  protected override async createServerForRequest({
    request,
  }: {
    request: TransportRequestContext;
  }): Promise<Server> {
    return this.createServer({
      userConfig: this.userConfig,
      sessionOptions: {
        connectionRegistry: this.connectionStore.view(),
      },
    });
  }

  override async close(): Promise<void> {
    await super.close();
    await this.connectionStore.closeAll();
  }
}

const runner = new CustomStreamableHttpRunner({
  userConfig: UserConfigSchema.parse({}),
});

await runner.start();

The MCP Server supports standard proxy environment variables for outbound connections (Atlas API, OIDC, MongoDB cluster, and MongoDB Assistant). This behavior is consistent with mongosh.

Proxy Environment Variables:

• HTTPS_PROXY: Proxy for HTTPS requests (Atlas API, OIDC, Assistant).
• HTTP_PROXY: Proxy for plain HTTP requests.
• ALL_PROXY: Fallback proxy for all protocols.
• NO_PROXY: Comma-separated list of hosts/domains to bypass the proxy.

Example (bash/zsh):

export HTTPS_PROXY="http://proxy.example.com:8080"
export NO_PROXY="localhost,127.0.0.1,*.internal.example.com"

Proxy in MongoDB Connection String: For cluster connections specifically, you can define a SOCKS5 proxy directly in the connection string using these parameters:

• proxyHost
• proxyPort
• proxyUsername
• proxyPassword

Example Connection String:

mongodb+srv://<host>/?proxyHost=127.0.0.1&proxyPort=1080&proxyUsername=user&proxyPassword=pass

Certificate Authorities: The server trusts the operating system's certificate store in addition to bundled CAs, meaning corporate root certificates installed at the OS level are automatically recognized.

To provide user-specific permissions or dynamic settings (like different connection strings based on an environment header), extend StreamableHttpRunner and override the createServerForRequest method. This is the recommended pattern for per-session customization.

Inside createServerForRequest, you can access the RequestContext to inspect headers (e.g., x-user-id or x-environment), fetch user permissions, and then call this.createServer({ userConfig: sessionConfig }) to return a server instance tailored to that specific request.

import { UserConfigSchema, StreamableHttpRunner } from "mongodb-mcp-server";
import type { Server, UserConfig } from "mongodb-mcp-server";
import type { RequestContext } from "mongodb-mcp-server";

class CustomStreamableHttpRunner extends StreamableHttpRunner {
  protected override async createServerForRequest({
    request,
  }: { 
    request: RequestContext; 
  }): Promise<Server> {
    const userId = request?.headers?.["x-user-id"];
    // ... logic to fetch permissions and build sessionConfig ...
    const sessionConfig: UserConfig = {
      ...this.userConfig,
      readOnly: true,
    };

    return this.createServer({
      userConfig: sessionConfig,
    });
  }
}

When configuring access for the MongoDB MCP Server, use the principle of least privilege. Assign roles based on the specific tasks required:

• List orgs/projects: Use Org Member or Org Read Only (at the Organization level).
• Create new projects: Use Org Project Creator (at the Organization level).
• View clusters/databases in a project: Use Project Read Only (at the Project level).
• Create/manage clusters in a project: Use Project Cluster Manager (at the Project level).
• Manage project access lists: Use Project IP Access List Admin (at the Project level).
• Manage database users: Use Project Database Access Admin (at the Project level).
• Manage stream processing resources: Use Project Stream Processing Owner (at the Project level).

Best Practices:

• Prefer project-level roles to limit scope.
• Avoid using Organization Owner unless full administrative control over all projects is strictly necessary.