CLI Reference (litestar mcp)¶
When LitestarMCP is registered on a Litestar application, it automatically attaches the mcp command group to the litestar CLI (LitestarMCP.on_cli_init).
For transport architecture and configuration patterns, see Stdio, HTTP Bridge & Tool Spec Export.
Command Reference¶
All commands run under the Litestar CLI mcp group:
| Command | Category | Summary |
|---|---|---|
litestar mcp stdio |
Transports & Proxies | Serve this Litestar app's MCP endpoint to a local stdio client in-process. |
litestar mcp bridge |
Transports & Proxies | Proxy local stdio JSON-RPC to this Litestar app's MCP endpoint. |
litestar mcp export-tool-spec |
Specification & Schema Export | Export the MCP tools/list specification as formatted JSON. |
litestar mcp list-tools |
Discovery & Interactive Execution | List all available MCP tools. |
litestar mcp list-resources |
Discovery & Interactive Execution | List all available MCP resources. |
litestar mcp run |
Discovery & Interactive Execution | Run a discovered MCP tool by name. |
Transports & Proxies¶
Commands for serving the Litestar application over in-process stdio or proxying stdio JSON-RPC frames to a remote Streamable HTTP endpoint.
litestar mcp stdio¶
Serve this Litestar app's MCP endpoint to a local stdio client in-process.
Options
| Option | Type | Default | Description |
|---|---|---|---|
--header |
text |
None |
Static HTTP header as 'Name: value'. |
--bearer-env |
text |
None |
Environment variable containing the bearer token. |
--bearer-cmd |
text |
None |
Command whose stdout returns the bearer token. |
--header-name |
text |
"Authorization" |
Header used for bearer tokens. |
--token-prefix |
text |
"Bearer " |
Prefix prepended to bearer token values. |
--sse-read-timeout |
float |
300.0 |
Subscription stream read timeout in seconds. |
--max-message-size |
integer |
16777216 |
Maximum bytes for one JSON-RPC message, from stdin or from the server. Use -1 to disable the limit. |
litestar mcp bridge¶
Proxy local stdio JSON-RPC to this Litestar app's MCP endpoint.
Options
| Option | Type | Default | Description |
|---|---|---|---|
--endpoint |
text |
None |
Full MCP Streamable HTTP endpoint URL. Overrides --base-url and the app's MCPConfig.base_path. |
--base-url |
text |
None |
Base URL of the already-running Litestar app. Defaults to LITESTAR_HOST/LITESTAR_PORT or http://127.0.0.1:8000. |
--header |
text |
None |
Static HTTP header as 'Name: value'. |
--bearer-env |
text |
None |
Environment variable containing the bearer token. |
--bearer-cmd |
text |
None |
Command whose stdout returns the bearer token. |
--header-name |
text |
"Authorization" |
Header used for bearer tokens. |
--token-prefix |
text |
"Bearer " |
Prefix prepended to bearer token values. |
--timeout |
float |
30.0 |
HTTP connect/write/pool timeout in seconds. |
--sse-read-timeout |
float |
300.0 |
SSE stream read timeout in seconds. Use 0 for no quiet-period timeout. |
--max-message-size |
integer |
16777216 |
Maximum bytes for one JSON-RPC message, from stdin or from the server. Use -1 to disable the limit. |
Specification & Schema Export¶
Commands for exporting deterministic MCP tool manifests and validating description length bounds in CI pipelines.
litestar mcp export-tool-spec¶
Export the MCP tools/list specification as formatted JSON.
Options
| Option | Type | Default | Description |
|---|---|---|---|
--output, -o |
Path |
None |
Write the exported tool specification JSON to this file instead of stdout. |
--indent |
integer |
2 |
Number of spaces for JSON indentation. |
--strict-bounds, --no-strict-bounds |
bool |
False |
Validate tool, parameter, and output field description lengths against bounds. |
Discovery & Interactive Execution¶
Commands for inspecting discovered MCP tools and resources or invoking a tool directly from the terminal.
litestar mcp list-tools¶
List all available MCP tools.
Uses plain description so terminal output never shows ## headers.
litestar mcp list-resources¶
List all available MCP resources.
Uses plain description so terminal output never shows ## headers.
litestar mcp run¶
Run a discovered MCP tool by name.
Usage Examples¶
1. In-Process Stdio Server (litestar mcp stdio)¶
Run your Litestar application as a local MCP server over stdin/stdout without binding a TCP port. The in-process ASGIStreamingTransport enters app.lifespan() and dispatches every JSON-RPC frame through the full Litestar middleware, guard, and dependency injection stack:
# Serve the application in-process over stdio
litestar --app my_app.main:app mcp stdio
# Inject a bearer token from an environment variable into every synthesized ASGI scope
litestar --app my_app.main:app mcp stdio --bearer-env MCP_API_TOKEN
# Fetch a short-lived token dynamically via a shell command and attach a custom tenant header
litestar --app my_app.main:app mcp stdio \
--bearer-cmd "gcloud auth print-identity-token" \
--header "X-Tenant-Id: acme-prod"
2. Stdio-to-Streamable HTTP Proxy (litestar mcp bridge)¶
Connect a stdio-only MCP desktop client or IDE to a remote or local Streamable HTTP deployment (POST /mcp):
# Proxy stdio to a local running server (auto-resolving MCPConfig.base_path)
litestar --app my_app.main:app mcp bridge --base-url http://127.0.0.1:8000
# Proxy to a remote production endpoint with bearer authentication and custom headers
litestar --app my_app.main:app mcp bridge \
--endpoint https://api.example.com/mcp \
--bearer-env PROD_MCP_TOKEN \
--header "X-Environment: production" \
--sse-read-timeout 600
3. Static Tool Manifest Export (litestar mcp export-tool-spec)¶
Export the deterministic tools/list JSON manifest in CI pipelines without starting an HTTP server, and enforce description length bounds across all tools, input parameters, and output fields:
# Print the formatted tools/list manifest to stdout
litestar --app my_app.main:app mcp export-tool-spec
# Write the manifest to disk and fail with exit code 1 if any description violates length bounds
litestar --app my_app.main:app mcp export-tool-spec \
--output artifacts/mcp-tools.json \
--indent 2 \
--strict-bounds
4. Terminal Inspection (list-tools, list-resources, run)¶
Inspect discovered MCP primitives or execute a tool directly from your development shell:
# Inspect all discovered MCP tools and their parameter signatures
litestar --app my_app.main:app mcp list-tools
# Inspect all discovered static resources and RFC 6570 URI templates
litestar --app my_app.main:app mcp list-resources
# Interactively invoke a discovered tool by name
litestar --app my_app.main:app mcp run