Using Zexl
MCP server
zexl-mcp lets AI assistants read your Zexl figures and set up new projects. It runs on your machine and talks to the Zexl API with a read key: it cannot send data or change anything.
Install
Claude Code:
bash
claude mcp add zexl -- uvx zexl-mcp
Claude Desktop, Cursor and others:
json
{
"mcpServers": {
"zexl": { "command": "uvx", "args": ["zexl-mcp"] }
}
}Log in
Either let the agent connect (Connect with your AI agent), or create a Read key in Settings > API keys and pass it:
bash
claude mcp add zexl -e ZEXL_READ_KEY=zx_... -- uvx zexl-mcp
Tools
| Tool | Answers |
|---|---|
zexl_status | Is it connected, to which workspace, and when did the last call arrive? |
zexl_connect_start | Starts connecting a project; returns a link and a code for you |
zexl_connect_finish | Waits for your approval, writes ZEXL_API_KEY to .env, saves the read key |
zexl_setup_guide | Exact steps to add the SDK to a Python app, or to track Claude Code |
zexl_check_connection | Did the first call arrive, and what was recorded? |
zexl_spend_summary | Spend, waste by pattern, useful share, budget left, invoice coverage |
zexl_forecast | Where the month will end, the likely range, and when it passes the budget |
zexl_top_waste | The biggest findings, each with a fix |
zexl_breakdown | Spend and waste by feature, model, customer or actor |
zexl_explain_spike | Why a day cost more: its waste, and the features and models that changed |
zexl_pattern_runs | The runs behind one finding, worst first |
zexl_run_detail | One run step by step |
Reading tools take days (default 30) and environment (default production; also staging, development, all). The prompt integrate_zexl walks an agent through setup.
Things to ask
- "What did we waste in production last week? Fix the biggest one."
- "Which feature has the worst useful-spend share?"
- "Explain the spike on the 10th."
- "Show me one of the looping runs in the researcher feature."
- "Will we stay within budget this month?"
Settings
| Variable | Meaning | Default |
|---|---|---|
ZEXL_READ_KEY | A read key | the saved credentials |
ZEXL_API_URL | The Zexl API | https://zexl-api.fly.dev |
ZEXL_CONFIG_DIR | Where credentials are saved | ~/.config/zexl |
Hosted server
A hosted version for claude.ai connectors and other remote clients, with sign-in instead of a key, is planned.