zado-mcp 0.2.0

Zado MCP server — AI agent access to envelope budgets via the Model Context Protocol

zado-mcp

One-line install for AI agent access to your Zado envelope budgets.

You review the budget on the weekends; your agents shop all week. zado-mcp is the Model Context Protocol server that connects any MCP-capable AI agent (Claude Code, Claude Desktop, OpenAI Assistants, custom) to your Zado instance. The server runs locally over stdio, but every authorization, spending guard, and audit entry is enforced server-side — zado-mcp is a pure transport bridge, not a trust boundary.

AI Agent → zado-mcp (local stdio) → HTTPS → zadofi.ai → real envelopes

The canonical, citable spec for the surface this server implements is the Zado Agent Trust Protocol v0.1.

Install

pip install zado-mcp

Requires Python ≥ 3.10. Two dependencies: mcp, httpx.

Get an agent token

In the Zado app: Settings → Agent Access → Create Agent. Choose:

• Name — e.g. "Claude Code", "OpenClaw", "Walmart shopper"
• Scope — read (view only) or spend (view + authorize purchases)
• Envelopes — optional: bind the agent to specific categories (e.g. groceries only)
• TTL — token lifetime (default 90 days)

Copy the token when shown — it's displayed once.

Quick Start

zado-mcp init

The interactive flow prompts for your Zado instance URL (default https://zadofi.ai) and the agent token (input is hidden), then writes ~/.config/zado-mcp/config.json (mode 0600). The server reads URL + token from that file at startup — no env vars required in most setups.

After init, paste this short snippet into your agent's MCP config:

{
  "mcpServers": {
    "zado": {
      "command": "zado-mcp",
      "args": ["serve"]
    }
  }
}

Resolution order: explicit kwargs → ZADO_API_URL / ZADO_AGENT_TOKEN env vars → ~/.config/zado-mcp/config.json. So you can override per-host (e.g. point at a local backend during dev) without touching the config file.

Claude Code

Add the snippet above to your .mcp.json (project root or ~/.claude.json), then restart Claude Code. The zado server appears in /mcp with the 5 tools below.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) and paste the same snippet. Quit and re-open Claude Desktop.

OpenAI (Responses API) and other HTTP-only MCP clients

zado-mcp v0.1 ships stdio transport only, which is what Claude Code, Claude Desktop, and the OpenAI Agents SDK speak. OpenAI's Responses API MCP integration connects to a remote MCP server over HTTP / Streamable HTTP, not stdio, so it can't talk to zado-mcp serve directly. (Note: the OpenAI Assistants API is deprecated and shuts down on 2026-08-26.)

Two options today:

1. Use the OpenAI Agents SDK (Python or JS), which speaks stdio MCP the same way Claude Code does — paste the snippet above into the SDK's MCP server list.
2. Bridge stdio → HTTP with mcp-proxy and point the Responses API at the proxy's URL.

A native HTTP/SSE transport is on the v0.2 roadmap.

Available tools

Tool	Scope	What it does
check_budget(category)	read	Returns budgeted / spent / remaining / percentage_used for one envelope.
get_daily_status()	read	Total available across all envelopes, daily allowance, days remaining, alerts.
list_envelopes()	read	All envelope balances for the current month.
authorize_purchase(amount, category, vendor)	spend	Authorize and log a purchase if the envelope has funds. Returns {authorized: true, transaction_id, remaining} or {authorized: false, reason}.
check_pending_authorization(pending_id)	spend	When authorize_purchase returns pending_human_approval, poll this with the returned pending_id to learn whether the user approved/denied/let it expire.

All tools are pure transport — they delegate to the Zado REST API, which enforces auth, spending caps, rate limits, envelope binding, and audit on every call.

What agents CAN see

• Envelope names and balances (budgeted, spent, remaining)
• Daily spending allowance + alerts
• Whether a specific purchase is affordable

What agents CANNOT see

• Bank account or routing numbers
• Bank-connection tokens (Teller, Plaid)
• Raw transaction history
• User personal information

Spending guards (spend scope only)

• Per-transaction cap — default $50, configurable per agent
• Session cap — cumulative; resets after 24h of inactivity
• Rate limit — max 3 transactions per minute
• Budget pacing — denies purchases that consume too much budget too fast
• Envelope binding — agent can only spend in bound categories
• Envelope balance — if the envelope is empty, the purchase is denied

All guards run server-side. The local zado-mcp server cannot bypass them.

Kill switch

Settings → Agent Access → Freeze All Agents — one click deactivates every agent token. Use it whenever you're not sure.

Configuration

zado-mcp resolves config in this order (first non-empty wins):

1. Explicit kwargs to ZadoAPIClient(...) (programmatic use)
2. Environment variables (ZADO_API_URL, ZADO_AGENT_TOKEN)
3. ~/.config/zado-mcp/config.json (written by zado-mcp init, mode 0600)

Source	Variable / key	Required	Description
env / config	ZADO_API_URL / api_url	yes	Your Zado instance URL (e.g. https://zadofi.ai)
env / config	ZADO_AGENT_TOKEN / agent_token	yes	Agent token from Settings → Agent Access

Troubleshooting

ZADO_API_URL environment variable not set — init never ran or the agent's MCP config doesn't pass the env vars through. Re-run zado-mcp init and copy the printed snippet exactly.

Zado API error 401: Invalid or revoked agent token — token expired, was revoked from Settings → Agent Access, or the user account changed password. Create a new agent and re-init.

Zado API error 403: Agent scope does not permit this operation — agent is read scope but tried authorize_purchase, or is bound to specific envelopes and tried to spend in a different category. Edit the agent in Settings → Agent Access to widen scope or bindings.

httpx.ConnectError — wrong ZADO_API_URL, your Zado instance is offline, or local DNS issue. Try curl $ZADO_API_URL/healthz from the same shell.

Server starts but agent doesn't see the tools — restart the host (Claude Code / Claude Desktop) after editing .mcp.json. MCP servers are loaded at host startup.

License

MIT — see LICENSE.

Source

github.com/evo-hydra/zado · tools/zado-mcp/