serena-pool
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
serena-pool
Project-aware pooling proxy for Serena MCP servers.
Serena has no built-in pooling: a stdio server dies with every client session, so each
new session pays a cold start for the language servers behind it. serena-pool keeps
warm, per-project Serena instances alive between sessions and shares them across clients
(Codex, ZCode, Claude Code, ...) through a lightweight stdio <-> streamable-http bridge.
How it works
The proxy is a single-file Python program you register as an MCP server (stdio) in your client:
detects the project root from the working directory (
.serena/project.ymlor.gitupwards, fallback: cwd);derives a deterministic port from
md5(project path + context), with linear probing on collisions and a cross-process file lock against double spawns;lazily starts
serena start-mcp-server --transport streamable-http --project <path>as a detached, hidden-window process;writes a lease with a heartbeat; a detached reaper kills instances that received no fresh leases for
ttl_seconds;bridges MCP JSON-RPC both ways (POST + SSE, session ids,
202notifications, server pings);if the backing server dies, transparently restarts it and replays
initialize— the client never notices;enforces a per-request deadline (
request_timeout): a wedged server triggers reconnect/restart instead of hanging the client forever.
The same project can hold separate instances per client context (codex, zcode, ...)
— see SERENA_POOL_CONTEXT below. State lives in ~/.serena/pool/:
dir | contents |
| one JSON per live instance (key, port, pid, context) |
| cross-process spawn locks |
| heartbeat files, one per connected proxy |
| per-instance serena logs + reaper log |
Related MCP server: mcp-streamable-http-bridge
Install
Requires Python 3.10+ and Serena on PATH or at
~/.local/bin/serena.exe. The only dependency is httpx.
Run directly from git with uv:
uvx --from git+https://github.com/svetkis/serena-pool serena-poolor clone and run with any interpreter that has httpx:
git clone https://github.com/svetkis/serena-pool
pip install httpx
python serena_pool_proxy.pyClient configuration
Codex (~/.codex/config.toml):
[mcp_servers.serena]
command = "C:\\path\\to\\python.exe" # any python with httpx
args = ["C:\\path\\to\\serena_pool_proxy.py"]ZCode (~/.zcode/cli/config.json) or any Claude-style MCP config:
{
"mcp": {
"servers": {
"serena": {
"type": "stdio",
"command": "uvx",
"args": ["--from", "git+https://github.com/svetkis/serena-pool", "serena-pool"],
"env": { "SERENA_POOL_CONTEXT": "zcode" }
}
}
}
}Configuration
Global config: ~/.serena/pool/config.json (created with defaults on first run).
key | default | meaning |
|
| idle time without fresh leases before the reaper kills an instance |
|
| port window for pool instances |
|
| Serena context ( |
|
| explicit path to the |
|
| extra args for |
|
| seconds to wait for the server port to open |
|
| per-request deadline through the bridge, seconds ( |
Environment:
SERENA_POOL_CONTEXT— overridescontextfor this proxy invocation without touching the shared config. Instances are keyed per (project, context) pair, so Codex and ZCode opening the same project each get their own Serena instance with the right tool set.
Smoke test
python examples/pool_test_client.py <project_dir>Runs initialize → tools/list → a tool call through the proxy and prints each step.
Platform status
Windows-first: process control uses msvcrt locks, taskkill /T, hidden-window creation
flags and pythonw.exe for the detached reaper. Linux/macOS support is not implemented
yet; patches welcome.
License
MIT. This project is an independent process that talks to Serena over its public MCP interface; it contains no Serena code. Serena itself is GPL-3.0-or-later since v2.0.0 (SolidLSP remains MIT).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
MCP Gateway: wrap any MCP server with cold-start retries, uptime SLA, and per-execution MPP billing.
Stateless MCP gateway and OTel span-streaming bridge for hosted MCP servers.
Streamable HTTP MCP gateway for NV oOS fleets — one API key, namespaced tools, quotas and policy.
Coordinate and verify OpenCode workers over MCP Streamable HTTP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA bridge server that converts stdio protocol to streamable-http protocol, allowing clients to interact with MCP services over HTTP.2Mulan Permissive Software , Version 2
- AlicenseNot gradedqualityDmaintenanceBridges stdio Model Context Protocol (MCP) servers to MCP Streamable HTTP behind a single gateway, enabling multi-tenant, multi-user deployment with per-tenant environment variables via HTTP headers.MIT
- AlicenseNot gradedqualityDmaintenanceEnables a single MCP client to connect to many upstream MCP servers through one gateway, with prefix-based routing, health checks, circuit-breaker failover, and unified stdio/HTTP access.MIT
- FlicenseNot gradedqualityDmaintenanceEnables local MCP clients to share expensive stdio MCP servers and browsers across WSL/Windows with lazy startup, idle scale-to-zero, session isolation, and verified process cleanup.-