Backend
MCP Server
Caspian can mount an app-owned FastMCP server into the same FastAPI
deployment. The feature is optional and is controlled by
caspian.config.json.
caspian.config.json
has "mcp": true. If the feature is disabled,
enable it intentionally and run the Caspian project update workflow so
framework-managed files such as src/lib/mcp/**
are generated together.
Generated application shape
src/lib/mcp/ ├── mcp_server.py └── fastmcp.json settings/restart-mcp.ts main.py package.json
Keep tools and server configuration in
src/lib/mcp/. The current
main.py imports that module only when
cfg.mcp is true, composes the MCP
lifespan with the FastAPI lifespan, and mounts the transport at
/mcp.
Run and inspect
Bundled workflow
npm run mcp
Direct FastMCP workflow
fastmcp run src/lib/mcp/fastmcp.json
Confirm the generated script names in package.json
before running them. Disabled projects do not expose the MCP script or
generated server files.
HTTP and CORS ownership
Browser MCP clients preflight the mounted endpoint. The app bootstrap
builds MCP-specific CORS settings from
CORS_ALLOWED_ORIGINS,
APP_BASE_URL, and related environment
values, and includes the required
mcp-session-id and
mcp-protocol-version headers.
The /mcp transport is long-lived and is
excluded from the normal request timeout in the generated app's
main.py. Preserve that exemption when
changing diagnostics or timeout middleware.
Bearer authentication
The mounted MCP application sits outside Caspian's page-routing tree, so
AuthMiddleware, private-route rules, and browser
session cookies do not protect it. Generated MCP-enabled projects instead wrap
the transport with MCPAuthMiddleware and use the
server-only MCP_AUTH_TOKEN environment value.
Authorization: Bearer <MCP_AUTH_TOKEN>
Token configured
Every non-preflight request must present the bearer token. Missing or invalid
credentials receive 401 with a bearer challenge.
Token missing
Development remains open for local tools. Production returns
503, keeping workspace metadata unavailable
until a token is configured.
Generate a different long random token for each deployment, keep it in the
platform's secret manager, and never reuse AUTH_SECRET
or expose the MCP token to browser code. The complete generated block is in the
environment-variable reference.