Add information on multi-user mode #20

README.md

@@ -189,3 +189,44 @@ This repository is a monorepo containing four main components:
 
 The core components are written in TypeScript, rendering interactions with the
 Penpot Plugin API both natural and type-safe.
+
+## Multi-User Mode
+
+The Penpot MCP server supports a multi-user mode, allowing multiple Penpot users
+to connect to the same MCP server instance simultaneously.
+This supports remote deployments of the MCP server, without requiring each user
+to run their own server instance.
+
+> [!WARNING]
+> Multi-user mode is currently experimental.
+
+### Limitations
+
+Multi-user mode has the limitation that tools which read from or write to 
+the local file system are not supported, as the server cannot access
+the client's file system. This affects the import and export tools.
+
+### Running Components in Multi-User Mode
+
+To run the MCP server and the Penpot MCP plugin in multi-user mode (for testing),
+you can use the following command:
+
+```shell
+npm run bootstrap:multi-user
+```
+
+This will:
+ * launch the MCP server in multi-user mode (adding the `--multi-user` flag),
+ * build and launch the Penpot MCP plugin server in multi-user mode.
+
+See the package.json scripts for both `mcp-server` and `penpot-plugin` for details.
+
+In multi-user mode, users are required to be authenticated via a token.
+
+* This token is provided in the URL used to connect to the MCP server,
+  e.g. `http://localhost:4401/mcp?userToken=USER_TOKEN`.
+* The same token must be provided when connecting the Penpot MCP plugin
+  to the MCP server.    
+  In the future, the token will, most likely be generated by Penpot and 
+  provided to the plugin automatically. 
+  For now, it is hard-coded in the plugin's source code for testing purposes.