Configuration¶

The Litestar MCP plugin is configured through MCPConfig. This page walks through each knob the plugin exposes, from a default registration to task-lifecycle support.

Minimal Setup¶

The plugin registers with sensible defaults when no configuration is passed. Every marked route is picked up and served from /mcp.

docs/examples/snippets/configuration_minimal.py¶

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

Custom Configuration¶

Override the base path, server name, or OpenAPI visibility via MCPConfig.

docs/examples/snippets/configuration_custom.py¶

config = MCPConfig(
    base_path="/api/mcp",
    name="My MCP Server",
    include_in_schema=True,
)
app = Litestar(route_handlers=[], plugins=[LitestarMCP(config)])

Auth-Enabled Configuration¶

Attach an MCPAuthConfig to require bearer tokens on MCP endpoints and publish /.well-known/oauth-protected-resource. See Authentication for the full authentication story.

docs/examples/snippets/configuration_auth.py¶

auth = MCPAuthConfig(
    issuer="https://auth.example.com",
    audience="https://api.example.com/mcp",
    scopes={"mcp:read": "Read access to MCP resources"},
)
config = MCPConfig(auth=auth)
app = Litestar(route_handlers=[], plugins=[LitestarMCP(config)])

Task Lifecycle¶

Enable the experimental in-memory task endpoints by passing an MCPTaskConfig. Tasks let MCP clients submit long-running work and poll for completion.

docs/examples/snippets/configuration_tasks.py¶

config = MCPConfig(
    tasks=MCPTaskConfig(enabled=True, default_ttl=300_000),
)
app = Litestar(route_handlers=[], plugins=[LitestarMCP(config)])

Configuration Options¶

Option	Default	Description
`base_path`	`"/mcp"`	Base path for the MCP Streamable HTTP endpoint.
`include_in_schema`	`False`	Whether to include MCP routes in the OpenAPI schema.
`name`	`None`	Server name override (falls back to the OpenAPI title).
`guards`	`None`	Litestar guards applied to the MCP router.
`allowed_origins`	`None`	Restrict accepted `Origin` header values.
`include_operations` / `exclude_operations`	`None`	Filter exposure by Litestar operation name.
`include_tags` / `exclude_tags`	`None`	Filter exposure by OpenAPI tags.
`auth`	`None`	Enable bearer-token validation and OAuth protected-resource metadata.
`tasks`	`False`	Enable experimental in-memory MCP task support.

Environment Overrides¶

MCPConfig is a plain dataclass, so the ordinary Litestar pattern applies: read the environment before constructing it and pass the resolved values through. For example, to keep base_path and name configurable at deploy time:

export MCP_BASE_PATH=/api/mcp
export MCP_SERVER_NAME="My MCP Server"

Then build MCPConfig using os.getenv for each option - the shape is identical to the Custom Configuration snippet above, just with environment lookups replacing literal values.