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

ToolAnswers
zexl_statusIs it connected, to which workspace, and when did the last call arrive?
zexl_connect_startStarts connecting a project; returns a link and a code for you
zexl_connect_finishWaits for your approval, writes ZEXL_API_KEY to .env, saves the read key
zexl_setup_guideExact steps to add the SDK to a Python app, or to track Claude Code
zexl_check_connectionDid the first call arrive, and what was recorded?
zexl_spend_summarySpend, waste by pattern, useful share, budget left, invoice coverage
zexl_forecastWhere the month will end, the likely range, and when it passes the budget
zexl_top_wasteThe biggest findings, each with a fix
zexl_breakdownSpend and waste by feature, model, customer or actor
zexl_explain_spikeWhy a day cost more: its waste, and the features and models that changed
zexl_pattern_runsThe runs behind one finding, worst first
zexl_run_detailOne 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

VariableMeaningDefault
ZEXL_READ_KEYA read keythe saved credentials
ZEXL_API_URLThe Zexl APIhttps://zexl-api.fly.dev
ZEXL_CONFIG_DIRWhere 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.