Configuration¶

Configure UML-MCP with environment variables and MCP client config files.

Running with FastMCP CLI¶

When a fastmcp.json file is present in the project root, you can run the server with the FastMCP CLI:

# Use config from fastmcp.json (auto-detected in current directory)
fastmcp run

# Or specify the config file explicitly
fastmcp run fastmcp.json

# Or run a specific file; the CLI looks for a variable named mcp, server, or app
fastmcp run server.py

Command-line options override values in fastmcp.json (e.g. fastmcp run --port 8080). For the full local CLI with options like --list-tools, use python server.py instead.

Environment variables¶

When MCP_URL_ONLY=true, the server avoids downloading rendered image bytes inside the process (lower latency and cost on serverless). Responses omit content_base64 unless you disable URL-only mode. MCP_MEMORY_ONLY=true skips all file writes; use URL/base64-from-client fetch if needed.

Health check (HTTP deployment)¶

When running the FastAPI app (app.py) for HTTP deployment (e.g. Vercel, Docker, uvicorn), a health endpoint is available:

• Endpoint: GET /health (no authentication required)
• Response: {"status": "healthy", "modules_available": true|false}
• status: Always "healthy" when the server is up.
• modules_available: Whether diagram backends (Kroki, PlantUML, etc.) could be loaded.

Use /health for load balancers, Kubernetes or Docker liveness/readiness probes, Vercel checks, and similar monitoring whenever you run the FastAPI app (app.py).

When running the MCP server via fastmcp run with HTTP transport only (no FastAPI app), the standalone server does not expose /health unless you add a custom route; use the FastAPI app if you need the health endpoint.

Stateless HTTP (multi-worker / horizontal scaling)¶

When running multiple workers or instances (e.g. uvicorn app:app --workers 4 or multiple pods behind a load balancer), FastMCP’s default server-side sessions can break because sessions are stored per process. Enable stateless HTTP so each request gets a fresh context:

Set the environment variable:

FASTMCP_STATELESS_HTTP=true

This is recommended for multi-worker or horizontally scaled deployments. The MCP server is created with stateless_http=True when this variable is set to 1, true, or yes (case-insensitive).

MCP client configuration¶

Example MCP server config snippets for Cursor and Claude Desktop are in the config/ folder in this repo:

• config/cursor_config.json: Cursor
• config/claude_desktop_config.json: Claude Desktop
• config/README.md: Where each app stores its config and how to copy the examples

For Claude Code, you can install the bundled plugin from this repo’s marketplace instead of pasting JSON; see Claude Code integration.

Copy the relevant mcpServers block into your client’s config file and set cwd to your uml-mcp project root. The examples use args: ["-u", "server.py"] (unbuffered stdio, path relative to cwd). The main server entry point is server.py. Optional env keys include KROKI_SERVER, MCP_OUTPUT_DIR, and MCP_DIAGRAM_FALLBACK (see table above).

Advanced configuration¶

Custom Templates¶

You can customize diagram templates by modifying the templates in the tools/kroki/kroki_templates.py file.

Output Formats¶

Each diagram type supports specific output formats:

Set output_format in the MCP tool arguments when you generate a diagram.

Server card and config schema (Smithery / quality score)¶

Smithery and other MCP clients read the server card for tool metadata and optional session fields:

• The server card at /.well-known/mcp/server-card.json lists tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) and a config schema URL (configSchemaUrl: config-schema.json).
• The session config schema is served at /.well-known/mcp/config-schema.json (same path as the card) so clients can resolve it when the card is loaded from that origin.
• When publishing on Smithery, add session configuration from smithery-config-schema.json in the project settings (see Vercel/Smithery integration).