> For the complete documentation index, see [llms.txt](https://docs.datasentinel.io/manual/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.datasentinel.io/manual/ai-connector/troubleshooting/private-network-mcp-servers.md). # MCP servers on a private network Which assistants work with a platform that has no public endpoint, and how to keep it private. **Applies to:** a Datasentinel platform on a private network, with no public endpoint. The network can be an on-premises data center, a private cloud or VPC, or a VPN. Typical signs are an internal DNS name, a private IP address, a VPN-only host, or a certificate from an internal CA. For certificate errors alone, see [Self-signed and untrusted TLS certificates](/manual/ai-connector/troubleshooting/ssl-certificates.md). For sign-in loops, see [Sign-in problems](/manual/ai-connector/troubleshooting/sign-in-problems.md). ## Symptom The same platform works in one assistant and fails in another. Typical cases: * The server works in Visual Studio Code or Cursor, but ChatGPT on the web cannot create the app. * A local Codex chat in the ChatGPT desktop app reaches the platform, but a Codex cloud task cannot. OpenAI describes the cloud environment's network in [Codex cloud internet access](https://learn.chatgpt.com/docs/cloud/internet-access). * Copilot Studio fails at **Add** when you add the MCP server, or the Datasentinel login page never opens. * Claude Desktop reaches the platform through the local bridge, but a Claude custom connector or a dashboard artifact cannot. * The sign-in page opens, you sign in, and the assistant still reports that it cannot connect. The platform is fine. The assistant simply cannot reach it from where it runs. ## One question: where does the MCP client run? An assistant connects to the MCP server from the machine where its MCP client runs. That is not always your workstation. * **A local assistant** runs the MCP client on your workstation or on a server you control. It uses that machine's network: the LAN, the VPN, the internal DNS and the trusted certificates. If your browser reaches the platform from that machine, the assistant does too. * **A cloud assistant** runs the MCP client in the vendor's infrastructure. Your workstation's VPN, internal DNS and private routes do not apply there. The platform must be reachable from the internet, or through a connection the vendor provides. ``` Local assistant Cloud assistant Workstation Vendor cloud (OpenAI, Microsoft, ...) assistant + browser MCP client │ LAN / VPN │ internet ▼ ▼ Datasentinel platform Datasentinel platform ◄── your browser (private is fine) (must be reachable from the vendor) ``` Running the assistant's app on your desktop does not make it local. What matters is where the MCP calls come from. Claude Desktop is an example: the same app is a local assistant with the local bridge, and a cloud assistant with a custom connector. ## Which assistants can use a private platform | Assistant | Where the MCP calls come from | Private platform | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------- | ---------------- | | [Visual Studio Code](/manual/ai-connector/connect-an-ide/configure-vscode.md) (GitHub Copilot) | Your workstation | Yes | | [GitHub Copilot CLI](/manual/ai-connector/connect-a-cli-assistant/configure-copilot-cli.md) | The machine running the CLI | Yes | | [Cursor](/manual/ai-connector/connect-an-ide/configure-cursor.md) | Your workstation | Yes | | [ChatGPT desktop app](/manual/ai-connector/connect-a-desktop-app/configure-chatgpt-desktop-app.md) (Chat, Work and Codex, local chats), with the server added in **Settings → MCP servers** | Your workstation | Yes | | [Codex CLI](/manual/ai-connector/connect-a-cli-assistant/configure-codex-cli.md), [Mistral Vibe CLI](/manual/ai-connector/connect-a-cli-assistant/configure-mistral-vibe-cli.md), [Antigravity CLI](/manual/ai-connector/connect-a-cli-assistant/configure-antigravity-cli.md) | The machine running the CLI | Yes | | [Antigravity desktop app](/manual/ai-connector/connect-a-cli-assistant/configure-antigravity-cli.md#use-the-antigravity-desktop-app) (Antigravity 2.0) | Your workstation | Yes | | [Deep Agents Code, Hermes Agent](/manual/ai-connector/connect-a-cli-assistant/connect-a-compatible-assistant.md), [Python agents](/manual/ai-connector/developers/build-a-python-agent-with-deepagents.md) | The machine running them | Yes | | [Claude Desktop](/manual/ai-connector/connect-a-desktop-app/configure-claude-desktop-windows.md) with the local bridge (`mcp-remote`), and Claude Code | Your workstation | Yes | | Codex **Cloud** chats and tasks | A container hosted by OpenAI | Not as-is | | [ChatGPT on the web](/manual/ai-connector/connect-a-desktop-app/configure-chatgpt-desktop-app.md#using-chatgpt-on-the-web-instead) (developer mode apps) | OpenAI's cloud | Not as-is | | [Copilot Studio](/manual/ai-connector/connect-a-desktop-app/configure-copilot-studio.md), and Microsoft 365 Copilot or Teams through a published agent | Microsoft's cloud (Power Platform) | Not as-is | | [Microsoft Copilot app](/manual/ai-connector/connect-a-desktop-app/configure-microsoft-copilot-app.md): Copilot Cowork, declarative agents, federated connectors | Microsoft's cloud | Not as-is | | Claude custom connectors (claude.ai, Claude Desktop), and [Claude artifacts](/manual/ai-connector/dynamic-dashboards/claude-artifact.md) | Anthropic's cloud | Not as-is | | [Gemini app](/manual/ai-connector/connect-a-desktop-app/configure-gemini-desktop-app.md) custom apps (added in the web app; personal Google accounts in the US only) | Google's servers | Not as-is | {% hint style="success" %} **Claude Desktop works with a private MCP server.** Add the server with the **local bridge**: it is declared in Claude Desktop's configuration file (**Settings → Developer → Edit Config**) and runs `mcp-remote` on your workstation. The MCP calls and the sign-in then use your workstation's network, VPN and internal DNS. See [Add the Datasentinel MCP server](/manual/ai-connector/connect-a-desktop-app/configure-claude-desktop-windows.md#add-the-datasentinel-mcp-server). The **custom connector** method does not work with a private server: Claude calls connectors from Anthropic's cloud. Dashboard artifacts only use connectors, so they need a public MCP server. {% endhint %} {% hint style="success" %} **The ChatGPT desktop app works with a private MCP server.** Since September 2026, the Codex app has become the new ChatGPT desktop app, with Chat, Work and Codex in one app, on Windows and macOS. Add the server in **Settings → MCP servers**. The app writes it to the Codex configuration file (`config.toml`), shared with the Codex CLI and IDE extension, and calls it from your workstation. {% endhint %} "Not as-is" means you need one of the options in [Keep the platform private](#keep-the-platform-private). ## What a cloud assistant must reach OAuth protects the platform. It does not create connectivity. A cloud assistant signs in through its own servers, so it needs more than `/mcp`: * the MCP endpoint, `https:///mcp`; * the discovery documents, `/.well-known/oauth-protected-resource/mcp` and `/.well-known/oauth-authorization-server`; * the client registration, `/register`, and the token endpoint, `/token`. All of them live on the same host, and the vendor calls them from its cloud. The list of nginx locations is in [MCP Server Setup](/manual/ai-connector/server-setup/mcp-server-setup.md). Your users' browsers must reach two more locations: `/authorize` and the login page, `/oauth/login`. The browser runs on the user's machine, so the private network or the VPN is enough for these two. Three more constraints apply: * **A public DNS name.** The vendor resolves the host name with public DNS. An internal zone such as `*.corp.local` is invisible to it. * **A publicly trusted certificate.** A cloud service does not accept a self-signed certificate or your internal CA, and you cannot install a CA there. There is no workaround. * **No IP allowlist to rely on, for some vendors.** Anthropic publishes the fixed range Claude uses to call MCP servers, in [IP addresses](https://platform.claude.com/docs/en/api/ip-addresses): you can restrict the host to it. Microsoft publishes regional service tags for Power Platform connectors (**AzureConnectors**, **PowerPlatformPlex**), in [Outbound IP addresses](https://learn.microsoft.com/en-us/connectors/common/outbound-ip-addresses). Copilot Studio's MCP calls go through that infrastructure, but the page does not name MCP, so validate it on your tenant. Power Platform's [virtual network support](https://learn.microsoft.com/en-us/power-platform/admin/vnet-support-overview) covers custom connectors, but Microsoft states that [OAuth and token requests do not transit the virtual network](https://learn.microsoft.com/en-us/connectors/custom-connectors/#virtual-network-support), and Copilot Studio's [virtual network page](https://learn.microsoft.com/en-us/microsoft-copilot-studio/admin-network-isolation-vnet) does not list MCP servers. It does not replace a sign-in host reachable from Microsoft's cloud. Other vendors publish no fixed address ranges. The public name must also be the platform's own name. The discovery documents advertise it as the `issuer`. If the assistant connects under another name, the sign-in loops. Set `DS_MCP_PUBLIC_URL` to the public name, as described in [TLS hostname mismatch on API calls](/manual/ai-connector/troubleshooting/tls-hostname-mismatch.md#the-fix). ## Keep the platform private Pick the first option that fits your constraints. {% stepper %} {% step %} #### Use a local assistant This is the simplest fix, and nothing is exposed. Visual Studio Code, Cursor, Claude Desktop with the local bridge, the ChatGPT desktop app, and the CLIs reach the platform over the LAN or the VPN. The sign-in happens in the user's own browser. See the table above. If nothing may leave your network, not even the prompts, pair a local assistant with a local model. [Run a fully local agent with Gemma 4](/manual/ai-connector/developers/build-a-python-agent-with-deepagents.md#run-a-fully-local-agent-with-gemma-4) shows one way. {% endstep %} {% step %} #### Use the vendor's tunnel, when it offers one OpenAI's [Secure MCP Tunnel](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels) serves ChatGPT on the web and Codex cloud. You run OpenAI's [tunnel client](https://github.com/openai/tunnel-client) on a host inside your network that reaches the platform. It makes outbound-only connections to OpenAI and relays the MCP requests, so no inbound port is opened. Check three points before you rely on it: * The tunnel carries the MCP traffic and the OAuth discovery. OpenAI notes that the authorization server is not automatically tunneled. With Datasentinel it is on the same host as `/mcp`: verify in OpenAI's guide that `/register` and `/token` are covered by your setup. * The user's browser must still reach the login page, through the corporate network or the VPN. * An organization administrator creates the tunnel in the OpenAI platform settings. Run the tunnel client on a managed server or container, not on a laptop. It must resolve the platform's internal name and trust its certificate. {% endstep %} {% step %} #### Publish only the MCP host through a gateway This is the design for Copilot Studio and for any cloud assistant without a tunnel. PostgreSQL, the collectors, the monitoring data and the platform stay on the private network. A reverse proxy or API gateway in the DMZ publishes one host name, with public DNS and a publicly trusted certificate. It forwards to the platform internally. Keep the gateway a plain reverse proxy for the MCP and sign-in locations: * Forward `/mcp`, `/.well-known/oauth-*`, `/authorize`, `/register`, `/token`, `/revoke` and `/oauth/login` unchanged. Everything else can stay closed. * Do not put the gateway's own authentication in front of them. The sign-in must end on the Datasentinel login page. * Keep the `Authorization` header, and do not turn the `/token` answers into redirects. * Do not buffer the `/mcp` responses. The server streams them, and the platform's own nginx sets `proxy_buffering off` on that location. * Route `/mcp` before any catch-all location. Otherwise the assistant receives the web interface's login page instead of the MCP server. With Microsoft Entra ID and Azure, Azure API Management can play this role, with a VPN or ExpressRoute to the platform. See [Secure access to MCP servers in Azure API Management](https://learn.microsoft.com/en-us/azure/api-management/secure-mcp-servers). See [Cloud service and private platforms](/manual/ai-connector/connect-a-desktop-app/configure-copilot-studio.md#cloud-service-and-private-platforms) for the Copilot Studio options. {% endstep %} {% step %} #### Accept that some combinations do not work A cloud assistant with no inbound exposure and no vendor tunnel cannot reach the platform. An air-gapped environment cannot use a cloud assistant at all. In both cases, use a local assistant. {% endstep %} {% endstepper %} ## Constraints that still apply to local assistants A local assistant reaches the private network, but a few things can still block it. * **The internal CA.** The assistant's own HTTP client checks the certificate, not only your browser. Node-based clients (VS Code, Cursor, Copilot CLI, Claude Desktop's local bridge) and Python agents each have their own trust store. See [Self-signed and untrusted TLS certificates](/manual/ai-connector/troubleshooting/ssl-certificates.md) for the setting per client. * **The corporate proxy.** When the workstation sends web traffic through a proxy, the assistant may send the platform's traffic there too, and the proxy cannot reach internal hosts. Exclude the platform's host from the proxy: `NO_PROXY`, or the assistant's proxy bypass setting. * **The VPN.** It must be up for the sign-in and for every tool call. A session that worked yesterday fails today when the VPN is down; the platform is not at fault. * **One name everywhere.** Use the same host name in every assistant, and make it the name the platform advertises. A short name on one machine and a full name on another makes the sign-in loop. See [Sign-in problems](/manual/ai-connector/troubleshooting/sign-in-problems.md#the-assistant-loops-on-authenticate). * **A CLI on a remote server.** The platform is reachable from the server, but the sign-in callback goes to `localhost` on that server. See [Sign in from a server without a browser](/manual/ai-connector/server-setup/how-authentication-works.md#sign-in-from-a-server-without-a-browser). ## Check it yourself Run these from the machine where the MCP client runs. For a cloud assistant, run them from a host outside your network, such as a small cloud VM or a phone hotspot: that is the view the vendor has. The MCP endpoint answers `401` to a request without a session. That is the expected result: the server is reachable and asks for a sign-in. ```bash curl -sS -o /dev/null -w '%{http_code}\n' https:///mcp ``` The discovery documents must answer with JSON, and `issuer` must be the exact name you registered in the assistant: ```bash curl -s https:///.well-known/oauth-protected-resource/mcp curl -s https:///.well-known/oauth-authorization-server ``` For a cloud assistant, the name must resolve in public DNS and the certificate must come from a public authority: ```bash nslookup 8.8.8.8 openssl s_client -connect :443 -servername /dev/null \ | openssl x509 -noout -subject -issuer ``` | What you see | Cause | Fix | | ------------------------------------------------------------------ | ------------------------------------------------------- | ---------------------------------------------------------- | | Timeout or `Could not resolve host` from outside, fine from inside | The platform is only reachable from the private network | Local assistant, vendor tunnel, or gateway | | `nslookup` from outside returns nothing | The name exists only in internal DNS | Publish a public DNS name on the gateway | | The certificate issuer is your company's CA | Internal CA, not trusted by the vendor | Publicly trusted certificate on the gateway | | `/mcp` returns `200` with HTML, or a login page | A catch-all location answers before `/mcp` | Route `/mcp` first, on the platform and the gateway | | `/mcp` answers `401`, but discovery fails from outside | The gateway only forwards `/mcp` | Forward the OAuth locations too | | `issuer` differs from the name in the assistant | Public name and platform name disagree | Set `DS_MCP_PUBLIC_URL`, register the same name | | The login page opens, then the connection fails | The vendor cannot reach `/token` | Check `/token` from outside, through the gateway or tunnel | | The login page does not open for some users | Their browser cannot reach the platform | Corporate network or VPN for the browser | The platform logs every sign-in step in `/datasentinel/log/mcp.log`. If no `oauth client registered` line appears when a cloud assistant adds the server, its requests never reached the platform. See [Where the server logs it](/manual/ai-connector/troubleshooting/sign-in-problems.md#where-the-server-logs-it). ## Vendor documentation The vendors change their products often. Check their current documentation for the network side: | Assistant | Official documentation | | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ChatGPT on the web | [Developer mode](https://developers.openai.com/api/docs/guides/developer-mode), [Apps SDK authentication](https://developers.openai.com/apps-sdk/build/auth) | | ChatGPT on the web, Codex cloud | [Secure MCP Tunnel](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels), [tunnel client](https://github.com/openai/tunnel-client) | | ChatGPT desktop app, Codex CLI | [ChatGPT desktop app](https://learn.chatgpt.com/docs/app), [Moving to the new ChatGPT desktop app](https://help.openai.com/en/articles/20001276-moving-to-the-new-chatgpt-desktop-app), [Model Context Protocol](https://learn.chatgpt.com/docs/extend/mcp), [Codex cloud internet access](https://learn.chatgpt.com/docs/cloud/internet-access) | | Antigravity | [MCP](https://antigravity.google/docs/mcp), [Skills](https://antigravity.google/docs/skills) | | Gemini app | [Connect & manage custom apps](https://support.google.com/gemini/answer/17209137) | | Microsoft Copilot app (Cowork) | [Build plugins for Copilot Cowork](https://learn.microsoft.com/en-us/microsoft-365/copilot/cowork/cowork-plugin-development), [Customize Copilot Cowork](https://learn.microsoft.com/en-us/microsoft-365/copilot/cowork/cowork-customize) | | Copilot Studio | [Add an MCP server to your agent as a tool](https://learn.microsoft.com/en-us/microsoft-copilot-studio/agents-experience/tools-add-mcp-server), [Manage and delete tools in an agent](https://learn.microsoft.com/en-us/microsoft-copilot-studio/agents-experience/tools-manage), [Data policies for agents](https://learn.microsoft.com/en-us/microsoft-copilot-studio/admin-data-loss-prevention) | | Azure API Management | [Secure access to MCP servers](https://learn.microsoft.com/en-us/azure/api-management/secure-mcp-servers) | | Claude custom connectors and artifacts | [Custom connectors using remote MCP](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp), [IP addresses](https://platform.claude.com/docs/en/api/ip-addresses), [Artifacts and MCP connectors](https://code.claude.com/docs/en/artifacts#pull-live-data-with-mcp-connectors) | | Visual Studio Code | [MCP servers](https://code.visualstudio.com/docs/agent-customization/mcp-servers) | | GitHub Copilot CLI | [Add MCP servers](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers) | | Cursor | [MCP](https://cursor.com/docs/mcp) | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.datasentinel.io/manual/ai-connector/troubleshooting/private-network-mcp-servers.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.