Metadata-Version: 2.4
Name: zado-mcp
Version: 0.2.0
Summary: Zado MCP server — AI agent access to envelope budgets via the Model Context Protocol
Author-email: Evolving Intelligence <nicholas.smith@evolvingintelligence.ai>
License-Expression: MIT
Project-URL: Homepage, https://zadofi.ai
Project-URL: Documentation, https://zadofi.ai/protocol/zado-agent-trust-protocol-v0.1
Project-URL: Source, https://github.com/evo-hydra/zado
Project-URL: Issues, https://github.com/evo-hydra/zado/issues
Keywords: mcp,model-context-protocol,ai,agent,budget,finance,zado
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: httpx>=0.27.0
Dynamic: license-file

# 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](https://modelcontextprotocol.io) server that connects any MCP-capable AI agent (Claude Code, Claude Desktop, OpenAI Assistants, custom) to your [Zado](https://zadofi.ai) 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](https://zadofi.ai/protocol/zado-agent-trust-protocol-v0.1).

## Install

```bash
pip install zado-mcp
```

Requires Python ≥ 3.10. Two dependencies: [`mcp`](https://pypi.org/project/mcp/), [`httpx`](https://pypi.org/project/httpx/).

## Get an agent token

In the Zado app: **Settings → [Agent Access](https://zadofi.ai/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

```bash
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:

```json
{
  "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](https://developers.openai.com/api/docs/guides/tools-connectors-mcp) 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`](https://github.com/sparfenyuk/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](LICENSE).

## Source

[github.com/evo-hydra/zado](https://github.com/evo-hydra/zado) · `tools/zado-mcp/`
