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 ...]
    Q -->|Portable agent instructions| D[Agent skills<br/>npx skills add …]
    

Skills are not a transport — they are skills.sh packages that teach an AI agent how to use the CLI or MCP tools. Install them when you want your coding agent (Claude Code, Codex, Copilot, …) to know the project’s commands and parameters without manual prompting. See Agent skills for details.

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.