Jaz AI · Agent stack for the ledger

The complete agent surface for Jaz accounting. 284 MCP tools, 6 skills, 16 IFRS recipes, 13 calculators, 12 close playbooks. Designed for any agent: Claude, GPT, Gemini, Copilot, Cursor. Hyper token economics, one-shot discovery, structured errors that an LLM can recover from.

Also fully compatible with Juan Accounting (same API surface).

Contents

• Install · 30 seconds

• What you get

• Three layers

• Quick start

• Token economics + speed

• For AI agents

• For accountants

• Reference

• Troubleshooting

• Privacy & security

• Support

Install · 30 seconds

Stdio MCP config (Claude Desktop, Cursor, Windsurf, OpenAI Codex CLI / Agents SDK, any host that runs MCP servers as local processes):

{
  "mcpServers": {
    "jaz": {
      "command": "npx",
      "args": ["-y", "jaz-clio@5.5.0", "mcp"],
      "env": { "JAZ_API_KEY": "jk-your-api-key" }
    }
  }
}

VS Code MCP config (.vscode/mcp.json — workspace-scoped — used by VS Code itself and the GitHub Copilot Chat extension):

{
  "servers": {
    "jaz": {
      "command": "npx",
      "args": ["-y", "jaz-clio@5.5.0", "mcp"],
      "env": { "JAZ_API_KEY": "jk-your-api-key" }
    }
  }
}

Pin jaz-clio@5.5.0 for stability, or jaz-clio@latest for auto-updates. Multi-org: comma-separated keys, e.g. "JAZ_API_KEY": "jk-aaa,jk-bbb". Personal access tokens (pat_...) also work for multi-org.

OpenAI Responses API

The Responses API only accepts HTTP MCP (no stdio). To use Jaz from a Responses API tool, host the MCP server behind HTTP and point at it:

{
  "type": "mcp",
  "server_label": "jaz",
  "server_url": "https://your-hosted-jaz-mcp/",
  "require_approval": "never"
}

A managed hosted endpoint isn't published yet; use the OpenAI Codex CLI / Agents SDK path above for stdio in the meantime.

Just want skills (no MCP, any agent on the Agent Skills standard):

npx jaz-clio init                  # auto-detects your tool
npx jaz-clio init --platform cursor
npx jaz-clio init --no-rules       # skills only, skip the agent-rules file
npx jaz-clio init --check          # report drift between installed agent-rules version and current

Skills install to .agents/skills/ (Agent Skills standard, used by Cursor, Copilot, Codex, Antigravity, Windsurf, Goose, Roo Code, Junie, Amp, and more) or .claude/skills/ (Claude Code).

init also writes a one-page jaz-agent-rules.md block to the path your platform reads on workspace open, so any agent (Claude / GPT / Gemini / Copilot / Cursor) starts every session with the meta-tool discovery flow, the 6 API gotchas, and the recipe-engine carve-out (no double-posting on fx-reval).

The block is wrapped in version-stamped markers (<!-- BEGIN jaz-agent-rules vX.Y.Z --> / <!-- END jaz-agent-rules -->), so re-running init updates only the Jaz block — your own rules above and below stay untouched. Run clio init --check to report drift between your installed version and the current package version (exit 1 = drift, exit 0 = current).

What you get

• 284 MCP tools covering every Jaz endpoint. Each tool description disambiguates against similar tools, lists enum values inline, and flags idempotency. The LLM picks right on the first call.

• 6 skills with the production-grade rules and playbooks any agent needs:

• 3 meta-tools (search_tools, describe_tools, execute_tool) for deferred discovery so the full catalog never has to load into context.

• OpenAPI spec at spec/openapi.yaml synced weekly from the source.

• Help center mirror at help-center-mirror/ synced weekly from Intercom.

• Structured-search DSL for natural-feeling queries (status:unpaid amount:>500 contact:Acme).

Three layers

The stack is one binary plus markdown skills, exposed through three layers that compose. The default agent setup is Skills + MCP. The CLI is the same binary as the MCP server with a different transport flag.

Skills layer on top of either. Most installs (Claude Code plugin, Claude Desktop MCPB, Cursor + MCP, Gemini extension) load Skills + MCP together.

Quick start

Once installed, skills load automatically when an agent works with Jaz. Describe what you need:

Close the books for Acme for January. Bank-recon DBS Current first.
Then file GST for Q1.

Or call the CLI directly:

clio invoices list --json
clio calc loan --principal 100000 --rate 6 --term 60 --json
clio jobs month-end --period 2025-01 --json

Or via MCP from any agent:

search_tools("anomalous bills")
  → download_export at rank 1
execute_tool("download_export", { exportType: "analysis-anomalous-bills" })
  → { fileName, fileUrl }

Token economics + speed

Built so any LLM sees the right tool fast and calls it once.

For AI agents

• Skills load automatically from .claude/skills/, .agents/skills/, the Claude Code marketplace, the Gemini CLI extension, or the Claude Desktop MCPB.

• Discovery is one-shot. 68 canonical-query lock-in tests guarantee the right tool at rank 1 for the queries that matter.

• Disambiguation is explicit. Tools that look similar carry "USE THIS, not X" preambles. No more guessing.

• Errors are structured. Server validation failures return field-level details so the agent can self-correct.

• Multi-org is native. Comma-separated keys (jk-aaa,jk-bbb) or PATs unlock cross-org tools (list_organizations, per-call org_id).

• OpenAPI spec at spec/openapi.yaml for code-gen pipelines and custom SDKs.

• CONTEXT.md captures runtime rules-of-engagement (bootstrap with clio context --json, search before create, mutate as draft first, never echo API keys).

For accountants

Set up the firm workspace once, then run period work conversationally:

clio practice init --firm-name "My Firm"
clio practice onboard --name "Acme Pte Ltd" --fy-end 12-31 --gst quarterly
clio practice create-engagement acme-pte-ltd --type monthly-close --period 2026-03

Or describe it to any agent:

Onboard Beta Pte Ltd, FY June, GST quarterly. Close March for Acme.

Each engagement template names the exact Jaz tools, recipes, and calculators to invoke. The agent loads CLIENT.md automatically before touching the books: FY end, GST scheme, COA mapping, banks, recurring accruals.

13 calculators (clio calc loan / depreciation / lease / ecl / fx-reval / provision / fixed-deposit / asset-disposal / prepaid-expense / deferred-revenue / accrued-expense / leave-accrual / dividend), 12 job blueprints (clio jobs month-end / quarter-end / year-end / bank-recon / document-collection / gst-vat / payment-run / credit-control / supplier-recon / audit-prep / fa-review / statutory-filing), all with --json for structured blueprint output.

Reference

• CLAUDE.md · architecture, source structure, version-bump procedure, contributor guide

• CONTEXT.md · runtime rules-of-engagement for agents using the stack

• CHANGELOG.md · release notes

• Skills source · all 6 skills (jaz-api / jaz-cli / jaz-conversion / jaz-jobs / jaz-recipes / jaz-practice)

• OpenAPI spec · full HTTP surface, synced weekly

• README-cli.md · npm-package README, full CLI command catalog

• help.jaz.ai · Jaz product help center

• CLI surface: 55 command groups across the clio binary

jaz-api

jaz-recipes (16 IFRS recipes + 13 calculators)

jaz-jobs (12 close playbooks + Singapore Form C-S)

jaz-conversion

Troubleshooting

command not found: clio

Node.js is not installed, or npm's global bin directory is not on PATH.

node --version    # Need v18+. If missing, install LTS from https://nodejs.org
npm install -g jaz-clio
npm config get prefix    # e.g. /usr/local or ~/.nvm/versions/node/v22.x.x
export PATH="$(npm config get prefix)/bin:$PATH"   # Add to ~/.bashrc or ~/.zshrc

Auth error / 401 Unauthorized

Missing or invalid API key. Keys expire if regenerated in the Jaz app.

clio auth whoami
clio auth add <your-api-key>       # Get from Settings > API in Jaz
clio auth list                     # Confirm the right org is active

If you use env vars, set JAZ_API_KEY in the current shell or your MCP config's env block.

MCP not connecting

The config path is wrong, the command is wrong, or the server crashes on startup.

npx jaz-clio mcp                   # Smoke-test the server (Ctrl+C to stop)
claude mcp list                    # Confirm Claude Code sees "jaz"
claude mcp add jaz -- npx jaz-clio mcp

For Cursor / VS Code / Windsurf, validate the JSON and pin the API key:

{
  "command": "npx",
  "args": ["-y", "jaz-clio@5.5.0", "mcp"],
  "env": { "JAZ_API_KEY": "jk-your-api-key" }
}

Pin JAZ_API_KEY in MCP config rather than relying on the active CLI profile. MCP servers cache credentials at startup so clio auth switch won't take effect until restart. For multi-org, use comma-separated keys.

Skills not loading

Files are in the wrong path, or your tool doesn't auto-discover from there.

ls .claude/skills/                 # Claude Code
ls .agents/skills/                 # Agent Skills standard (Cursor, Copilot, etc.)
npx jaz-clio init                  # Re-install with auto-detection

Each skill folder must contain SKILL.md plus its reference files. Manual copies often miss subdirectories.

EACCES permission denied on npm install

npm's global directory needs elevated permissions on macOS/Linux without nvm.

# Option A — nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
nvm install --lts && npm install -g jaz-clio

# Option B — fix npm permissions
mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"   # Add to ~/.bashrc or ~/.zshrc
npm install -g jaz-clio

Stale data after org switch

You ran clio auth switch but the MCP server still uses the previous org (it cached auth at startup).

# In Claude Code: remove and re-add
claude mcp remove jaz && claude mcp add jaz -- npx jaz-clio mcp

# In Cursor / VS Code: restart the editor or reload MCP servers

Or use multi-org mode and skip restarts: comma-separated keys (jk-aaa,jk-bbb) and switch orgs in conversation.

Privacy & security

Runs entirely on your machine. API calls go directly from your machine to the Jaz API over HTTPS. No telemetry. The API key lives locally in ~/.config/jaz-clio/credentials.json.

Full policy: jaz.ai/legal. Vulnerability disclosure: SECURITY.md.

Support

• Help center: help.jaz.ai

• Issues: github.com/teamtinvio/jaz-ai/issues

• Email: api-support@jaz.ai

License

MIT · Copyright (c) 2026 Tinvio / Jaz · Clio is a registered trademark of Tinvio.