From c60ff92be3f896c13910b2682cae376d9aa3ec5e Mon Sep 17 00:00:00 2001 From: Nick Taylor Date: Sun, 10 Aug 2025 00:39:37 -0400 Subject: [PATCH 1/4] docs: add gateways and proxies section to README --- README.md | 49 +++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 41 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index a556f65b..8c983acb 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ A Model Context Protocol server for interacting with MongoDB Databases and Mongo - [Environment Variables](#environment-variables) - [Command-Line Arguments](#command-line-arguments) - [MCP Client Configuration](#mcp-configuration-file-examples) - - [Proxy Support](#proxy-support) + - [Gateways and Proxies](#gateways-and-proxies) - [🤝 Contributing](#contributing) @@ -262,6 +262,46 @@ npx -y mongodb-mcp-server@latest --transport http --httpHost=0.0.0.0 --httpPort= > **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. +### Gateways and Proxies + +When deploying the MongoDB MCP as a Remote MCP Server to production, you should place it behind an authentication gateway or reverse proxy. + +#### Pomerium (Open Core Identity-Aware Proxy) + +[Pomerium](https://www.pomerium.com/) is an identity-aware access proxy designed for zero-trust access that [supports MCP](https://www.pomerium.com/docs/capabilities/mcp) out of the box. + +**Key Benefits:** +- Policy-based access control on every request +- Fine-grained access control +- Enterprise identity provider support (Microsoft Entra ID, Google Identity, Okta, Auth0, GitHub, Keycloak, etc.) +- Built-in audit logging and monitoring + +For complete setup instructions and configuration examples, see the [Pomerium MCP documentation](https://www.pomerium.com/docs/capabilities/mcp). + +#### Add Your Gateway/Proxy Solution + +Help us expand this section. We welcome community contributions for additional gateway and proxy solutions. If you've successfully deployed the MongoDB MCP Server with authentication gateways or reverse proxies, please share your suggestions by [opening an issue](https://github.com/mongodb-js/mongodb-mcp-server/issues/new). + +#### Outbound Proxy Support + +The MCP Server will detect typical PROXY environment variables and use them for connecting to the Atlas API, your MongoDB Cluster, or any other external calls to third-party services like OIDC Providers. The behavior is the same as what `mongosh` does, so the same settings will work in the MCP Server. + +This is useful when the MCP Server needs to connect through corporate firewalls or network restrictions to reach MongoDB Atlas or other external services. + +**Supported environment variables:** +- `HTTP_PROXY` / `http_proxy` - HTTP proxy for non-SSL connections +- `HTTPS_PROXY` / `https_proxy` - HTTPS proxy for SSL connections +- `NO_PROXY` / `no_proxy` - Comma-separated list of hosts to bypass proxy + +**Example:** +```bash +export HTTPS_PROXY=http://corporate-proxy.company.com:8080 +export NO_PROXY=localhost,127.0.0.1,*.company.com +npx -y mongodb-mcp-server@latest --transport http +``` + +> **Note:** This proxy support is for **outbound connections** from the MCP server to MongoDB/Atlas. For **inbound authentication** (securing access to your MCP server), use the gateway examples above. + ## 🛠️ Supported Tools ### Tool List @@ -575,13 +615,6 @@ npx -y mongodb-mcp-server@latest --apiClientId="your-atlas-service-accounts-clie } ``` -### Proxy Support - -The MCP Server will detect typical PROXY environment variables and use them for -connecting to the Atlas API, your MongoDB Cluster, or any other external calls -to third-party services like OID Providers. The behaviour is the same as what -`mongosh` does, so the same settings will work in the MCP Server. - ## 🤝Contributing Interested in contributing? Great! Please check our [Contributing Guide](CONTRIBUTING.md) for guidelines on code contributions, standards, adding new tools, and troubleshooting information. From 9329b60ae2f8afdb68c33b2699df886d5341e9cc Mon Sep 17 00:00:00 2001 From: Kevin Mas Ruiz Date: Mon, 11 Aug 2025 11:08:33 +0200 Subject: [PATCH 2/4] chore: Clarify relationship with third parties and that other security practices might be relevant --- README.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 8c983acb..0171538f 100644 --- a/README.md +++ b/README.md @@ -264,13 +264,17 @@ npx -y mongodb-mcp-server@latest --transport http --httpHost=0.0.0.0 --httpPort= ### Gateways and Proxies -When deploying the MongoDB MCP as a Remote MCP Server to production, you should place it behind an authentication gateway or reverse proxy. +When deploying the MongoDB MCP as a Remote MCP Server with access to sensitive data, it's crucial to place it behind an authentication gateway or reverse proxy. This is an essential security and privacy best practice, consistent with deploying any service or integration that handles sensitive information. + +The templates provided in this document are meant to be a starting point. While they can be a useful reference, they may not fully align with the best security practices for your specific situation. We strongly recommend you review and adapt these examples to ensure they meet your unique requirements and security policies before using them in a production environment. + +** ⚠️ Important Note**: The provided templates are offered on a _best-effort basis_. We do not endorse, nor do we have a support policy or any formal agreements with, the third-party services mentioned in these templates. Our team cannot provide direct support for issues related to their specific configurations. Please refer to the official documentation for those services for any technical assistance. #### Pomerium (Open Core Identity-Aware Proxy) [Pomerium](https://www.pomerium.com/) is an identity-aware access proxy designed for zero-trust access that [supports MCP](https://www.pomerium.com/docs/capabilities/mcp) out of the box. -**Key Benefits:** +**Key Features:** - Policy-based access control on every request - Fine-grained access control - Enterprise identity provider support (Microsoft Entra ID, Google Identity, Okta, Auth0, GitHub, Keycloak, etc.) From 5620c2f8b6747283044150ecbc63169204c7d1d3 Mon Sep 17 00:00:00 2001 From: Kevin Mas Ruiz Date: Mon, 11 Aug 2025 11:14:22 +0200 Subject: [PATCH 3/4] chore: fix formatting issue Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0171538f..0b84d27d 100644 --- a/README.md +++ b/README.md @@ -268,7 +268,7 @@ When deploying the MongoDB MCP as a Remote MCP Server with access to sensitive d The templates provided in this document are meant to be a starting point. While they can be a useful reference, they may not fully align with the best security practices for your specific situation. We strongly recommend you review and adapt these examples to ensure they meet your unique requirements and security policies before using them in a production environment. -** ⚠️ Important Note**: The provided templates are offered on a _best-effort basis_. We do not endorse, nor do we have a support policy or any formal agreements with, the third-party services mentioned in these templates. Our team cannot provide direct support for issues related to their specific configurations. Please refer to the official documentation for those services for any technical assistance. +**⚠️ Important Note:** The provided templates are offered on a _best-effort basis_. We do not endorse, nor do we have a support policy or any formal agreements with, the third-party services mentioned in these templates. Our team cannot provide direct support for issues related to their specific configurations. Please refer to the official documentation for those services for any technical assistance. #### Pomerium (Open Core Identity-Aware Proxy) From 20ea4abfa99068e0bfb312ef6f885f55acf59b06 Mon Sep 17 00:00:00 2001 From: Kevin Mas Ruiz Date: Mon, 11 Aug 2025 11:21:49 +0200 Subject: [PATCH 4/4] chore: fix prettier complains --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 0b84d27d..719d5b5c 100644 --- a/README.md +++ b/README.md @@ -275,6 +275,7 @@ The templates provided in this document are meant to be a starting point. While [Pomerium](https://www.pomerium.com/) is an identity-aware access proxy designed for zero-trust access that [supports MCP](https://www.pomerium.com/docs/capabilities/mcp) out of the box. **Key Features:** + - Policy-based access control on every request - Fine-grained access control - Enterprise identity provider support (Microsoft Entra ID, Google Identity, Okta, Auth0, GitHub, Keycloak, etc.) @@ -293,11 +294,13 @@ The MCP Server will detect typical PROXY environment variables and use them for This is useful when the MCP Server needs to connect through corporate firewalls or network restrictions to reach MongoDB Atlas or other external services. **Supported environment variables:** + - `HTTP_PROXY` / `http_proxy` - HTTP proxy for non-SSL connections - `HTTPS_PROXY` / `https_proxy` - HTTPS proxy for SSL connections - `NO_PROXY` / `no_proxy` - Comma-separated list of hosts to bypass proxy **Example:** + ```bash export HTTPS_PROXY=http://corporate-proxy.company.com:8080 export NO_PROXY=localhost,127.0.0.1,*.company.com