diff --git a/README.md b/README.md
index dd57cfcb3..4bf15f675 100644
--- a/README.md
+++ b/README.md
@@ -35,6 +35,36 @@ mvnw.cmd clean install
 ./mvnw clean install
 ```
 
+
+## Usage with eclipse.jdt.ls
+
+To use `java-debug` as a [jdt.ls](https://github.com/eclipse/eclipse.jdt.ls) plugin, an [LSP client](https://langserver.org/) has to launch [jdt.ls](https://github.com/eclipse/eclipse.jdt.ls) with `initializationOptions` that contain the path to the built `java-debug` jar within a `bundles` array:
+
+
+```
+{
+    "initializationOptions": {
+        "bundles": [
+            "path/to/microsoft/java-debug/com.microsoft.java.debug.plugin/target/com.microsoft.java.debug.plugin-<version>.jar"
+        ]
+    }
+}
+```
+
+Editor extensions like [vscode-java](https://github.com/redhat-developer/vscode-java) take care of this.
+
+
+Once `eclipse.jdt.ls` launched, the client can send a [Command](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#command) to the server to start a debug session:
+
+```
+{
+  "command": "vscode.java.startDebugSession"
+}
+```
+
+The response to this request will contain a port number on which the debug adapter is listening, and to which a client implementing the debug-adapter protocol can connect to.
+
+
 License
 -------
 EPL 1.0, See [LICENSE](LICENSE.txt) file.