diff --git a/docs/02-usage/020_running.md b/docs/02-usage/020_running.md index 6a126368..3b82a73b 100644 --- a/docs/02-usage/020_running.md +++ b/docs/02-usage/020_running.md @@ -132,7 +132,7 @@ to use such a launch command. (streamable-http)= ### Streamable HTTP Mode -When using instead the *Streamable HTTP* mode, you control the server lifecycle yourself, +When using *Streamable HTTP* mode, you control the server lifecycle yourself, i.e. you start the server and provide the client with the URL to connect to it. Simply provide `start-mcp-server` with the `--transport streamable-http` option and optionally provide the desired port @@ -147,7 +147,14 @@ you would run and then configure your client to connect to `http://localhost:9121/mcp`. -Note that while the legacy SSE transport is also supported (via `--transport sse` with corresponding /sse endpoint), its use is discouraged. +**When to use.** Note that Serena is a stateful MCP server, and only one coding project can be active at a time. +Therefore, starting a single Serena instance and connecting it to multiple clients is only +appropriate if all clients will be working on the same project. +If you want several agents to work on different projects, making each client/agent start its own server +in stdio mode is likely the best option. +See section [The Project Workflow](040_workflow) for more information on how to manage projects in Serena. + +The legacy SSE transport is also supported (via `--transport sse` with corresponding /sse endpoint), its use is discouraged. (mcp-args)= ### MCP Server Command-Line Arguments diff --git a/docs/02-usage/040_workflow.md b/docs/02-usage/040_workflow.md index 4e7821e5..a4be275b 100644 --- a/docs/02-usage/040_workflow.md +++ b/docs/02-usage/040_workflow.md @@ -160,13 +160,13 @@ and that has a good test coverage is much easier to work with for Serena. We generally recommend to start an editing task from a state where all linting checks and tests pass. -## Working with Multiple Projects Simultaneously +## Multiple Projects, Multiple Agents There are several ways in which you might want to work with multiple projects simultaneously. -### Simultaneously Editing in Multiple Projects +### A Single Agent Editing Multiple Projects Simultaneously -If fulfilling a task requires the agent to edit code in multiple projects, the recommended approach is to create a **monorepo folder**, +If fulfilling a task requires a single agent to edit code in multiple projects, the recommended approach is to create a **monorepo folder**, i.e. a folder that contains all the projects as sub-folders, and open that monorepo folder as a project in Serena. You may also use symbolic links to create a monorepo folder if the projects are located in different places on your filesystem. @@ -197,3 +197,16 @@ Depending on the language backend being used, the management of resources for th where `` is your way of running Serena. For example, when using `uvx`, run uvx --from git+https://github.com/oraios/serena serena start-project-server + +### Multiple Agents Accessing a Single Serena Instance + +If you want multiple agents to access the same project via a single Serena instance, +i.e. you do not want several instances of Serena (including its language servers) to be running, +you can achieve this by [starting the Serena MCP server in HTTP mode](streamable-http) +and connecting all client agents to the same HTTP endpoint. +The agents will then share the resources of the single Serena instance. + +### Multiple Agents Working on Different Projects + +For this use case, simply run a separate instance of Serena for each project, which naturally +occurs when Serena is started by the MCP client in stdio mode. \ No newline at end of file