Transports

The MCP server supports two transports. Pick based on how you intend to use it.

Transport	Use case	Cost	Concurrency
stdio	Local agent integration (Claude Desktop, Cline)	Lowest — no network overhead	Single client
streamable-http	Remote / multi-client / production deployments	Slightly higher (HTTP framing)	Multiple clients

Quick selection guide

        graph TD
    Q{How will you use the server?}
    Q -->|Local agent on the same machine| A[stdio]
    Q -->|Remote / multi-client / production| B[streamable-http]
    Q -->|Scripting — direct CLI use| C[CLI: novelai-image-mcp generate<br/>uv run python -m ...]
    

Transport-agnostic design

The server’s lifespan owns a single shared httpx.AsyncClient (connection pool) and one NovelAIClient. Every tool reads those from the request context’s lifespan state — neither tool code nor tool signatures change between transports.

Transport selection happens at server startup via MCP_TRANSPORT (or the CLI --transport flag):

# stdio (default)
MCP_TRANSPORT=stdio uv run python -m novelai_image_mcp serve

# streamable-http
MCP_TRANSPORT=streamable-http uv run python -m novelai_image_mcp serve

See Configuration for the full list of MCP_* variables.