Stdio Transport, HTTP Bridge & Tool Spec Export¶

In addition to serving Streamable HTTP directly from your Litestar application, litestar-mcp registers a litestar mcp CLI command group with subcommands for in-process stdio execution (stdio), remote Streamable HTTP bridging (bridge), static tool manifest export (export-tool-spec), and interactive CLI inspection (list-tools, list-resources, run).

Choosing Between stdio and bridge¶

In-Process Stdio (litestar mcp stdio)¶

Run your Litestar application as an in-process stdio MCP server using the Litestar CLI:

litestar --app my_app:app mcp stdio

During litestar mcp stdio, standard output is reserved exclusively for newline-delimited JSON-RPC frames; any accidental print() output from application code is redirected to sys.stderr.

Programmatic Stdio & MCPStdioContext¶

You can also drive the in-process stdio loop directly from Python using run_stdio, run_stdio_async, or MCP.run(transport="stdio"). Pass an MCPStdioContext to pre-populate caller identity, task ownership, and request state on every synthesized ASGI scope:

from litestar import Litestar
from litestar_mcp import LitestarMCP, MCPStdioContext
from litestar_mcp.mcp.stdio import run_stdio

app = Litestar(route_handlers=[...], plugins=[LitestarMCP()])

stdio_context = MCPStdioContext(
    client_id="local-desktop",
    owner_id="user:local-dev",
    user={"id": "local-dev", "roles": ["admin"]},
    auth={"sub": "local-dev"},
    state={"workspace": "default"},
)

run_stdio(app, stdio_context=stdio_context)

HTTP-to-Stdio Bridge (litestar mcp bridge)¶

When your Litestar service runs remotely (or in a separate local process/container) and an MCP host only supports stdio, use litestar mcp bridge:

litestar --app my_app:app mcp bridge --base-url https://api.example.com

Automatic Base Path Resolution¶

The bridge inspects the loaded application's LitestarMCP plugin configuration and appends MCPConfig.base_path to --base-url (or http://{LITESTAR_HOST}:{LITESTAR_PORT}, defaulting to http://127.0.0.1:8000):

"""Snippet: bridge target app with a custom MCP base path."""

from litestar import Litestar

from litestar_mcp import LitestarMCP, MCPConfig


def build() -> "Litestar":
    # start-example
    app = Litestar(
        plugins=[LitestarMCP(MCPConfig(base_path="/api/mcp"))],
    )
    # end-example
    return app

For the application above (MCPConfig(base_path="/api/mcp")), running litestar --app my_app:app mcp bridge targets http://127.0.0.1:8000/api/mcp automatically.

litestar mcp bridge & litestar mcp stdio CLI Options¶

Desktop Client Configuration Example¶

{
  "mcpServers": {
    "my-litestar-service": {
      "command": "litestar",
      "args": [
        "--app",
        "my_app:app",
        "mcp",
        "bridge",
        "--base-url",
        "https://api.example.com",
        "--bearer-env",
        "MCP_API_TOKEN"
      ]
    }
  }
}

Static Tool Manifest Export (litestar mcp export-tool-spec)¶

Use litestar mcp export-tool-spec in CI pipelines, schema registries, or documentation builds to export the exact tools/list JSON specification (name, description, inputSchema, outputSchema, annotations) without starting an HTTP server:

litestar --app my_app:app mcp export-tool-spec \
  --output tools.json \
  --indent 2 \
  --strict-bounds

Description Length Validation (--strict-bounds)¶

Passing --strict-bounds (or configuring max_tool_description_length, max_param_description_length, or max_output_field_description_length on MCPConfig) runs validate_tool_descriptions against every exported tool entry and exits non-zero if any description exceeds its character budget:

You can also invoke validate_tool_descriptions(tools, max_tool_description_length=1000, max_param_description_length=750, max_output_field_description_length=300) directly in your unit test suite to enforce concise LLM tool descriptions in CI.