docs: document how to start a remote MCP Coder server (#19150)

hugodutka · web-flow · commit a02d1c1e59e2 · 2025-08-04T18:53:12.000+02:00
Document how to start a remote MCP Coder server. Addresses coder/internal#823.
diff --git a/docs/ai-coder/mcp-server.md b/docs/ai-coder/mcp-server.md
@@ -1,6 +1,6 @@
 # MCP Server
 
-Power users can configure Claude Desktop, Cursor, or other external agents to interact with Coder in order to:
+Power users can configure [claude.ai](https://claude.ai), Claude Desktop, Cursor, or other external agents to interact with Coder in order to:
 
 - List workspaces
 - Create/start/stop workspaces
@@ -12,6 +12,8 @@ Power users can configure Claude Desktop, Cursor, or other external agents to in
 
 In this model, any custom agent could interact with a remote Coder workspace, or Coder can be used in a remote pipeline or a larger workflow.
 
+## Local MCP server
+
 The Coder CLI has options to automatically configure MCP servers for you. On your local machine, run the following command:
 
 ```sh
@@ -30,4 +32,27 @@ coder exp mcp server
 ```
 
 > [!NOTE]
-> The MCP server is authenticated with the same identity as your Coder CLI and can perform any action on the user's behalf. Fine-grained permissions and a remote MCP server are in development. [Contact us](https://coder.com/contact) if this use case is important to you.
+> The MCP server is authenticated with the same identity as your Coder CLI and can perform any action on the user's behalf. Fine-grained permissions are in development. [Contact us](https://coder.com/contact) if this use case is important to you.
+
+## Remote MCP server
+
+Coder can expose an MCP server via HTTP. This is useful for connecting web-based agents, like https://claude.ai/, to Coder. This is an experimental feature and is subject to change.
+
+To enable this feature, activate the `oauth2` and `mcp-server-http` experiments using an environment variable or a CLI flag:
+
+```sh
+CODER_EXPERIMENTS="oauth2,mcp-server-http" coder server
+# or
+coder server --experiments=oauth2,mcp-server-http
+```
+
+The Coder server will expose the MCP server at:
+
+```txt
+https://coder.example.com/api/experimental/mcp/http
+```
+
+> [!NOTE]
+> At this time, the remote MCP server is not compatible with web-based ChatGPT.
+
+Users can authenticate applications to use the remote MCP server with OAuth2. An authenticated application can perform any action on the user's behalf. Fine-grained permissions are in development.
