MCP Server

DayZero exposes a Model Context Protocol (MCP) server that lets AI assistants — Claude, ChatGPT, Cursor, and other MCP-compatible clients — interact with your accounting data through natural language.

The server is mounted at /mcp and uses the Streamable HTTP transport (stateless: each request stands alone, with no server-side session). Authentication uses OAuth 2.1 — your client discovers the auth server, registers itself, and opens a browser for you to sign in to DayZero and approve access. No tokens to copy.

Just want to connect? Claude users can click Add DayZero to Claude — claude.ai opens the connector dialog prefilled; review it, click Add, and sign in. Every other client: add https://mcp.ondayzero.com/mcp with no credentials and you'll be prompted to sign in to DayZero in your browser and approve access. See Quick Connect below.

Note: REST API keys (dz_…) from Settings → Developers authenticate the REST API only. They do not work on the MCP server — use the OAuth browser flow instead.

Quick Connect

The fastest path per client. Every row uses the same server URL — https://mcp.ondayzero.com/mcp — and ends in the same browser OAuth sign-in. Settings → Developers inside DayZero has one-click Add to Claude / Add to Cursor buttons and copy-paste snippets for the rest.

On Claude Team/Enterprise plans only org owners can add custom connectors — send your admin the same link on the admin path:

https://claude.ai/admin-settings/connectors?modal=add-custom-connector&connectorName=DayZero&connectorUrl=https%3A%2F%2Fmcp.ondayzero.com%2Fmcp

Domain Profiles For Power Users

DayZero keeps the unified server at /mcp for general use and also exposes focused domain profiles for multi-server MCP setups. Each mount below core is one domain: the reads and the writes of the same records live together.

• https://mcp.ondayzero.com/mcp/core (dayzero-core) — the default /mcp surface as a mount: business picker, daily brief, the AR and AP happy paths, transaction review, close status, reports
• https://mcp.ondayzero.com/mcp/ar (dayzero-ar) — invoices from draft to paid, customers, credit memos, the AR snapshot
• https://mcp.ondayzero.com/mcp/ap (dayzero-ap) — bills, vendors, vendor credits, AP approval routing, payment runs, aged payables
• https://mcp.ondayzero.com/mcp/inbox (dayzero-inbox) — the Bill Inbox: mail at the business's intake address (get_business_info.inbox_email), what reading each attachment found, drafts turned into bills, emailed receipts filed on their transactions
• https://mcp.ondayzero.com/mcp/banking (dayzero-banking) — transactions (categorize, split, bulk edit), bank accounts and balances, bank rules, receipts, transaction uploads
• https://mcp.ondayzero.com/mcp/counterparties (dayzero-counterparties) — naming rules and renames, merges, counterparty default ledgers, the counterparty registry
• https://mcp.ondayzero.com/mcp/ledger (dayzero-ledger) — chart of accounts, journal entries (including bulk upload and recurring), fixed assets and depreciation, prepaid amortization and tags
• https://mcp.ondayzero.com/mcp/close (dayzero-close) — close status and verification, accounting periods and sign-off, close packages and the publication gate, anomalies, the close-run tracker
• https://mcp.ondayzero.com/mcp/recon (dayzero-recon) — bank reconciliations, AI-match review, payment matching, Stripe payouts, external tie-outs
• https://mcp.ondayzero.com/mcp/reports (dayzero-reports) — financial statements, generated reports, analytics, budgets, forecasts, models, exports, audit trails
• https://mcp.ondayzero.com/mcp/o2c (dayzero-o2c) — order to cash: pipeline deals, sales orders, customer contracts, job-costing projects, and bulk import for each
• https://mcp.ondayzero.com/mcp/commerce (dayzero-commerce) — products, standard costs and COGS, inventory, Shopify, invoice posting ledgers
• https://mcp.ondayzero.com/mcp/people (dayzero-people) — the people roster, org chart and payroll reconciliation
• https://mcp.ondayzero.com/mcp/credit (dayzero-credit) — the partner-credit book, credit lines and loans (read-only)
• https://mcp.ondayzero.com/mcp/automations (dayzero-automations) — workflows: the graph schema (describe_workflow_schema) and the tools a node may call, drafting, validating, testing and publishing (publishing needs a passing test's test_run_hash and the user's approval; runs execute the published snapshot), running on DayZero's servers with an idempotency_key, polling a run, answering its approval steps, schedules
• https://mcp.ondayzero.com/mcp/workers (dayzero-workers) — the agent workforce: the business's agent roles (list_agent_roles), their runs with what each agent is doing now and what waits on a person (list_agent_runs, get_agent_run), and handing a role a job, answering its question or stopping it (start_agent_run, answer_agent_run, stop_agent_run); a run's own writes are filed as proposed changes. Also SOPs from chat: the SOPs worth writing for the business (suggest_sops), drafting and editing one (create_sop, update_sop), setting it live, draft or retired with the person's approval (set_sop_status), and starting its team (build_team_from_sop; a person installs it on the SOP page)
• https://mcp.ondayzero.com/mcp/agents (dayzero-agents) — what this connection may do (get_connection_info: email, scopes, write access, bound business, staff grant), pending changes and approval rounds, the decision log, background jobs, client-portal requests and messages

Each profile keeps tools/list scoped to that domain (at most 40 tools, under strict hosted-client limits). Every mount also lists search_tools, call_tool, confirm_write, get_job_status, list_ledgers, upload_file and generate_upload_url, so a tool another mount carries is one search_tools + call_tool(name, arguments) away; call_tool applies the same permissions, dry_run and approval gate as calling the tool directly. Claude clients (claude.ai, Claude Code, Claude desktop) load tool schemas on demand, so on /mcp they are listed every tool they can call. Self-hosted deployments can force one profile process-wide with MCP_DOMAIN_PROFILE (for example MCP_DOMAIN_PROFILE=dayzero-ar).

Multi-Server Setup Examples

Use multiple MCP server entries when you want separate focused tool surfaces in one client session.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "dayzero-core": {
      "url": "https://mcp.ondayzero.com/mcp/core"
    },
    "dayzero-ar": {
      "url": "https://mcp.ondayzero.com/mcp/ar"
    },
    "dayzero-ap": {
      "url": "https://mcp.ondayzero.com/mcp/ap"
    },
    "dayzero-reports": {
      "url": "https://mcp.ondayzero.com/mcp/reports"
    },
    "dayzero-banking": {
      "url": "https://mcp.ondayzero.com/mcp/banking"
    },
    "dayzero-o2c": {
      "url": "https://mcp.ondayzero.com/mcp/o2c"
    },
    "dayzero-recon": {
      "url": "https://mcp.ondayzero.com/mcp/recon"
    }
  }
}

Cursor: add one MCP server per profile in Settings → MCP Servers (same URLs above). Cursor will run OAuth for each server entry and keep tools separated by server.

ChatGPT: create one connector per profile under Settings → Connectors → Create using the profile URLs above.

GitHub Copilot / VS Code MCP: add each profile as a separate server in your MCP configuration (same URLs above) so tool discovery stays focused and below hosted limits. Add only the profiles you need; the example above is a starting set, and every other profile in the list works the same way.

What You Can Do

The MCP server exposes one tool per job across accounting domains; the Full tool reference below is generated from the live registry and lists every tool with its access level and approval gate. The table here groups the main workflows. Tools marked (write) mutate data and require write permission; everything else is a read-only query. Call search_tools with no query for a compact category map, or with a query to rank the tools for a job.

Modules the app has switched off (estimates, delayed charges, tax settings and payment terms, among others) have no MCP tools. Personal Gmail is not available over MCP either: a linked mailbox can be searched only by Regent in the DayZero app (see QuickBooks, Meta Ads, Gmail and MCP Connections).

You don't need to know your business ID upfront. The business_id parameter is optional on every tool — the server automatically resolves it:

• One business — selected automatically, zero friction.
• Multiple businesses — clients that support elicitation show a scope picker (firm-wide vs a specific business) as a native dropdown; other clients get your business list so the assistant can ask which one to use. Firm users with many clients can call find_business("name") to fuzzy-search for the right ID.
• Explicit ID — you can always pass a business_id directly if you prefer.

For cross-client questions ("across all our clients"), advisory-firm users should use the firm-wide tools (get_firm_client_overview, get_firm_user_activity) instead of looping per business.

The assistant remembers your selection for the rest of the conversation. Say "switch to [business name]" at any time to change.

Note: All monetary amounts are in cents (e.g. $150.00 = 15000). IDs are UUID v7 strings. Pagination is cursor-based — pass the next_cursor value from a response as cursor to get the next page. All date parameters use YYYY-MM-DD format.

Every tool marked write in the Full tool reference requires the write permission (a viewer-role token cannot call them): journal entries, transactions, bills, invoices, payments, contacts, counterparty registry links, counterparty default rules, vendor/customer exports and bulk imports, credit memos, vendor credits, reconciliation, anomalies, attention, file uploads (upload_file, generate_upload_url), and more. The assistant should confirm details with you before calling them.

Bulk imports (end-to-end): call upload_file(filename, content) with the file inline (text, or encoding="base64" for xlsx/pdf/images; up to 5 MB) to get an s3_key, then call bulk_create_vendors, bulk_create_customers, or bulk_create_counterparty_defaults (or the trigger_bulk_* uploads) with that s3_key. For a file over 5 MB, call generate_upload_url(filename) instead and send the file with an HTTP POST (outside MCP, e.g. curl -F) to the returned upload_url.

Every write tool accepts an optional dry_run=true parameter that returns a preview of the change without saving it. When a preview reports a plan_hash, pass that plan_hash back on the apply call. If the books moved between preview and apply (a sync landed, someone edited a row), the apply is refused as stale and you preview again. create_pending_change takes the same plan_hash so a person approving in the app is approving exactly what was previewed.

Journal entry drafts and standards:

• A draft for a human to post is create_pending_change(tool_name="create_journal_entry", arguments={...}, preview_payload=..., summary=...). The approver applies it under their own identity, so the entry's created_by is the approver. The arguments are the assistant tool's own shape, signed cents (debit positive, credit negative), with the date given explicitly: {"entry_date": "2026-09-30", "description": "Clearco $300K loan - interest accrual Sep 2026", "line_entries": [{"ledger_id": "<interest expense>", "amount_cents": 125000}, {"ledger_id": "<accrued interest>", "amount_cents": -125000}]}.
• An entry allows one line per ledger and side. create_journal_entry(combine_duplicate_lines=true) sums lines sharing a ledger, side and counterparty (descriptions joined with "; ") and the result reports how many were combined; without it the error names the ledger and side.
• Called directly, create_journal_entry takes date, description and line_items of {ledger_id, amount_cents, type} (optional description per line), where amount_cents is a positive integer and type is debit or credit; debits must equal credits. update_journal_entry edits an entry in place (description, entry_date, line_updates or line_entries with signed amount_cents, debit positive and credit negative) and refuses an entry in, or moved into, a closed period.
• create_journal_entry and update_journal_entry return warnings (never errors) when the description is empty, only an id such as "JE 15845", or has no month or year. Use " - ".
• list_journal_entries filters by created_by_user_id and linked_to (bill, invoice, credit_memo, vendor_credit, none); ask for fields such as invoice_id, bill_ids, credit_memo_id, vendor_credit_id, created_by_user_id to see the links and creator. Entries made before attribution was recorded have no creator.
• Reversal is not an MCP tool: use update_journal_entry to fix an entry in place, or the REST reverse route (POST /api/v1/journal-entries/{id}/reverse), which requires reversal_date (YYYY-MM-DD) and never defaults to today.

Full tool reference

Auto-generated from the live MCP registry: 417 tools (216 write, 165 approval-gated, 42 exposed by default). Regenerate with make mcp-manifest.

Approval gates

High-risk writes — payments (link_invoice_payment, link_bill_payment, mark_invoice_paid), voids (void_invoice, void_credit_memo, void_vendor_credit, cancel_bill), external sends (send_invoice), irreversible state changes (finalize_invoice), journal entries, merges and bulk posts — wait for your approval before committing. The same flow works in Claude Code, Cursor, Codex and claude.ai:

• Confirm dialog. A client that supports MCP elicitation on the 2026-07-28 protocol shows a native dialog summarizing the change (amounts in dollars). Choosing No in the form returns {"approved": false, "reason": "rejected"} and commits nothing.
• Approve in DayZero. Every other client, including Claude Code hosts that can't draw the dialog and decline it on their own, gets {"status": "approval_required", "approval_id": "…", "approve_url": "…", "summary": "…"} back. The assistant gives you the link; you open it signed in to DayZero, review the tool, business and arguments, and choose Approve or Decline (with an optional note). The assistant then calls confirm_write(approval_id): an approved write runs exactly that call once and returns its result, a declined one comes back as reason: "rejected" with your note, and an undecided one as status: "awaiting_approval" (it can pass wait_seconds up to 50 to wait for you). The assistant can cancel a waiting write (cancel=true) but has no way to approve one: only you, signed in as the user the write belongs to, can. An approval belongs to the user and client that received it and expires after 30 minutes.
• Large changes. A bulk tool's confirm_large_change=true (go past its blast-radius limit) always takes the same approval, even for a tool you have a standing grant for.

dry_run=true previews never ask. The gate is also applied to any write whose name starts with delete_, bulk_delete_, void_, bulk_void_ or cancel_, so a newly added destructive tool cannot slip through. The Approval gate column of the Full tool reference marks every gated tool.

Two ways around a prompt, both set up by a person:

• Standing approvals. A per-tool "always allow" grant you have given in the DayZero in-app assistant lets that tool skip the prompt for that business. Only explicit per-tool grants count (the broader Auto-Approval toggles in the assistant settings are ignored on MCP), and tools that delete, are irreversible or have external effects can never be auto-approved. list_auto_approvals shows your grants; revoke_auto_approval removes one.
• Proposed changes. An agent that should not apply a write itself can call create_pending_change with the tool name, its exact apply arguments, the preview and the plan_hash. A person approves or rejects it in the app's Proposed changes inbox; approval applies it as the approver, and the apply is refused as stale if the books moved since the preview. Read the outcome with list_pending_changes and get_pending_change.

Close agents: ask in the portal, report gaps

The agents profile (/mcp/agents) is for close agents run from the Agent window. Two things it does that the other profiles do not:

• Ask the client in the portal, not by email. create_transaction_clarification puts a question beside one transaction (with optional one-tap answers) under the client's Questions page; create_document_request asks for a file under Document requests. Both are for firm staff, reach only that business's own client users, can be cancelled, and need no approval. Read the answers back with list_transaction_clarifications(status="answered") and list_document_requests(status="fulfilled"). list_firm_conversations shows the message threads, send_firm_message and update_conversation_status work on them (those two still ask for approval), and get_client_portal_attention shows what the client sees on their dashboard. A connection bound to one business only lists that business's threads.
• Report a gap instead of pasting a transcript. create_feedback(kind="gap", tool_tried, error, sop_job?, expected?, excerpt?, severity?) files a feedback ticket for the DayZero team (source agent, tag platform_gap) and returns {feedback_id, deduplicated}. The same gap seen again within 14 days adds a note to the open ticket instead of a new one. It changes no books and needs no approval; it is rate limited.

UI cards (MCP Apps)

Hosts that advertise MCP Apps / mcp-ui support receive rendered HTML cards as embedded ui://dayzero/* resources alongside the JSON payload on snapshot tools: get_daily_brief, get_ar_snapshot, get_ap_snapshot, get_aged_payables, get_uncategorized_summary, and get_payment_priority_suggestions. Cards show key figures, aging tables, and dollar-formatted amounts with automatic light/dark styling. Clients without UI support receive identical JSON-only responses.

Note: create_invoice requires Stripe Connect (or a demo business, or historical=true for an invoice already issued elsewhere, which stays a local draft and never reaches Stripe) — call get_invoice_create_requirements first. For a migrated invoice pass historical=true with invoice_date and invoice_number. Typical flow: create_invoice → finalize_invoice → send_invoice or link_invoice_payment. mark_invoice_paid is for manual paid status without a bank match. AP: approve_bill → mark_bill_received (needs expense ledger_id). get_aged_payables pairs with get_ar_snapshot; get_payment_priority_suggestions ranks open bills late → early-pay discount → due within 7 days, with cash on hand.

Long-running workflows (trigger_bulk_transaction_upload, trigger_bulk_je_upload, trigger_month_end_close, generate_report, and bulk_create_invoices on a file of more than 500 rows) return immediately with {job_id, status: "started", poll_tool: "get_job_status"}. Do not wait inline; poll get_job_status(job_id) until completion/failure. list_jobs shows the business's recent jobs. Most MCP clients cancel a tool call after about a minute, which is why these tools hand back a job instead of blocking.

Multi-step agentic work that exceeds one call (hundreds of writes, many documents) can be handed to start_background_job: it runs detached on the server (about an hour of wall clock) under a write scope fixed at launch (allowed_write_tools, empty means read-only), and no human approves anything mid-run. Poll get_job_status for the summary and signed download links to any files it produced.

Reports follow: list_report_types → generate_report → poll get_job_status (use job_id) → optional get_report when the completed job returns a report_id. Pass wait=true to generate_report to wait up to wait_timeout_seconds (default 25, at most 55) and get the download link in one call; it falls back to the job handle if the report is not ready in time. output_format is csv (default) or xlsx. email_report sends a generated report's download link by email.

Whole datasets: export_dataset (up to 10,000 rows; format="jsonl" for programmatic use) replaces paging a list tool.

Download links (reports, exports, job files) are presigned, host-bound and expire after about an hour. Fetch them exactly as returned, with no Authorization header; changing the query string or adding auth breaks the signature.

When a tool fails

A failed tool returns a teaching error rather than a bare message — the same shape whether the failure came from the tool's own validation or from the data underneath it:

{
  "error": "You have access to multiple businesses. Please specify which one to use: …",
  "reason_code": "BUSINESS_SELECTION_REQUIRED",
  "how_to_fix": "Ask the user which of the businesses listed in the error to use, then pass its business_id.",
  "retryable": false,
  "did_you_mean": []
}

Read how_to_fix and did_you_mean before retrying, and don't retry at all when retryable is false. Common reason_code values:

A bare Error executing tool <name> with no envelope means an internal fault, not something to correct in the call — it is reported to DayZero automatically.

Working with Large Datasets

List tools return a total field showing total matching records. Use this to decide how to proceed:

• Analytical questions ("what did we spend the most on?", "are we profitable?", "how much revenue last quarter?") — use the analytics tools (get_financial_overview, get_top_expenses, get_cash_flow_totals, get_profit_trends, get_transaction_summary). These compute summaries server-side and return small payloads regardless of data volume.
• Under ~100 matching records — paginate through them if you need individual details.
• Over ~100 matching records — narrow with filters (date range, search text, ledger_id, status) or use analytics tools. Don't page through thousands of records.
• Full exports — use generate_report for a report file, or export_dataset for a raw dataset.

Strategy: summarize first, drill down second. Start with aggregate tools to understand the big picture, then use list tools with filters to examine specific subsets.

Prerequisites

1. A DayZero login for the browser consent flow. MCP sign-in is open to every account; it needs no separate approval and no API key.
2. API access not switched off for your user. If your advisory firm has disabled API access for you, authorization fails with access_denied.

Connecting Claude Desktop

The fastest path is the install link — Add DayZero to Claude. It opens claude.ai's Add custom connector dialog with the name and URL prefilled; review it, click Add, and sign in to DayZero when prompted. Connectors are account-level, so one add covers Claude on web, desktop, and mobile.

Prefer local config? Add the server with just its URL. Claude registers itself, opens a browser for you to sign in to DayZero and approve access, then stores the MCP OAuth token automatically:

{
  "mcpServers": {
    "dayzero": {
      "url": "https://mcp.ondayzero.com/mcp"
    }
  }
}

Config file location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Restart Claude Desktop after saving. You should see DayZero tools appear in the tools menu.

Connecting Claude Code

One command:

claude mcp add --transport http dayzero https://mcp.ondayzero.com/mcp

Then run /mcp inside Claude Code to complete the browser sign-in. To share the server with your whole team, commit a .mcp.json at the repo root instead:

{
  "mcpServers": {
    "dayzero": {
      "type": "http",
      "url": "https://mcp.ondayzero.com/mcp"
    }
  }
}

Calling your connected external MCP servers (Gusto and others)

Servers an admin connected under Integrations → External MCP servers (Gusto, Stripe, a CRM, ...) are reachable through the same DayZero connection, so Claude Code never holds the third-party credentials. Three tools do it (all on /mcp, and on the focused https://mcp.ondayzero.com/mcp/integrations mount); they need the admin role on the business:

1. list_external_tools — the connected servers and their tools, each marked read (runs without approval) or write (needs your approval). Pass server + tool to get a tool's input schema before the first call.
2. call_external_read_tool(server, tool, arguments) — runs a tool trusted as read-only, with no approval prompt. It refuses anything else.
3. call_external_write_tool(server, tool, arguments) — runs any other non-blocked tool after you approve the exact server, tool and arguments in DayZero (the same approve_url → confirm_write flow as other gated writes). Write approval is never skipped.

Which tools count as read is an admin's call, made per connection on the Integrations page: either Trust read-only hints (tools the server itself marks read-only) or, for servers that don't annotate their tools, Allow as read on each tool. A tool the server marks destructive always needs approval, and a blocked tool never runs. For Gusto, mark the lookups you use — for example the company lookup (get_company, to see which company the connection is signed into), payroll detail (the per-employee breakdown of a payroll) and contractor payments (by date range) — as Allow as read. Tool names come from Gusto's server; check them with list_external_tools(server="gusto").

Example prompts in Claude Code:

• "Which Gusto company is our DayZero connection signed into?"
• "Pull the per-employee breakdown for the October 15 payroll from Gusto."
• "List Gusto contractor payments from 2026-09-01 to 2026-09-30."

Every external call is logged in DayZero's audit trail: who (the person who owns the DayZero token), through what (the MCP client, e.g. claude-code, and its OAuth client id), which server and tool, read or write, the outcome, and — for a write — the approval. Arguments are stored as a digest, not the payload. Results are third-party text and are marked untrusted.

Who did it, and where it came from

Every change made through DayZero is attributed in the audit trail (the History panel on a record, get_entity_audit_trail, get_activity_feed) to the person and the channel: browser (the app), api (an API key, shown by name), mcp (an MCP client, shown by its name), ai_chat (the in-app assistant), workflow (a workflow run) or system (background jobs). Writes an agent made after you approved them in DayZero also carry the approval.

Connecting Cursor

The Add to Cursor button under Settings → Developers in DayZero opens Cursor with the server prefilled — confirm the install and sign in when the browser opens.

To add it manually, go to Settings > MCP Servers in Cursor and add a new server:

• Name: DayZero
• URL: https://mcp.ondayzero.com/mcp

Leave the headers blank — Cursor opens a browser for you to sign in and approve via OAuth.

Connecting ChatGPT

ChatGPT requires Developer mode before you can add an unlisted MCP connector:

1. Enable it under Settings → Apps → Advanced settings → Developer mode (available on Plus and Pro; on Business, Enterprise, and Edu workspaces an admin may need to allow it — or an admin can add DayZero org-wide from the workspace admin console).
2. Create a new connector with Name: DayZero, URL: https://mcp.ondayzero.com/mcp.

ChatGPT discovers the OAuth endpoints, opens a browser for you to sign in to DayZero, and stores the token automatically. Connectors are account-level, so the same connection works in the ChatGPT web, desktop, and mobile apps.

Connecting Codex

Codex CLI, the Codex IDE extension, and the ChatGPT desktop app share one MCP configuration. Add two lines to ~/.codex/config.toml:

[mcp_servers.dayzero]
url = "https://mcp.ondayzero.com/mcp"

Or configure it in the ChatGPT desktop app under Settings → MCP servers → Add server — name dayzero, transport Streamable HTTP, URL above. Codex opens your browser to sign in to DayZero the first time it connects.

Connecting Other MCP Clients

Any MCP client that supports Streamable HTTP transport can connect. The server implements the full MCP authorization spec, so compatible clients configure themselves automatically from the server URL alone:

• RFC 9728 Protected Resource Metadata — https://mcp.ondayzero.com/.well-known/oauth-protected-resource/mcp
• RFC 8414 Authorization Server Metadata — https://api.ondayzero.com/.well-known/oauth-authorization-server

These advertise the authorization server, supported scopes, PKCE methods, and the authorize / token / registration endpoints.

A connector descriptor for directories and crawlers lives at https://mcp.ondayzero.com/.well-known/mcp.json (alias of /.well-known/mcp/server-card.json): the endpoints and domain mounts, both OAuth metadata URLs, logo, docs, categories, contact and the size of the default tool list.

The canonical resource URL (RFC 8707 audience) is https://mcp.ondayzero.com/mcp — no trailing slash.

Browser-based and hosted clients (Origin allowlist)

As part of the MCP spec's DNS-rebinding protection, the server validates the Origin header on every MCP request. Requests without an Origin header — desktop apps and CLIs such as Cursor, Claude Desktop, Codex CLI, and mcp-remote — always pass. Requests with an Origin header must match the allowlist, which covers:

• Anthropic — https://claude.ai, https://claude.com
• OpenAI — https://chatgpt.com, https://chat.openai.com, https://platform.openai.com
• Cursor — https://cursor.com, https://cursor.sh
• Local development — http://localhost:*, http://127.0.0.1:* (e.g. MCP Inspector)

A hosted client whose origin is not allowlisted receives 403 Invalid Origin header on every MCP call after OAuth succeeds — the connector shows as connected but lists zero tools. If you're building or operating a hosted MCP client that should connect to DayZero, contact us so we can add your origin (self-hosted deployments can extend the list via the MCP_ALLOWED_ORIGINS_EXTRA environment variable).

Environment URLs

Use the MCP server URL in your client config. The protected-resource metadata is served from the MCP host (https://mcp.ondayzero.com/.well-known/oauth-protected-resource/mcp); the authorization server — its metadata at /.well-known/oauth-authorization-server, its issuer, and the /oauth2/* endpoints — stays on the API host (https://api.ondayzero.com). Clients discover this automatically from the MCP server URL.

Authentication

MCP uses OAuth 2.1 with browser consent. Tokens minted through this flow are MCP-only — they cannot call the REST API (/api/v1/*). Likewise, REST API keys and SPA session tokens cannot authenticate MCP tool requests.

OAuth 2.1 flow

1. The client connects to /mcp and receives a 401 with a WWW-Authenticate header pointing at /.well-known/oauth-protected-resource.
2. It reads RFC 9728 protected-resource metadata and discovers the authorization server.
3. It reads RFC 8414 authorization-server metadata at /.well-known/oauth-authorization-server.
4. It dynamically registers itself (RFC 7591) at POST /oauth2/register — no pre-shared client credentials needed. Alternatively a client can skip registration and use an https URL it controls as its client_id (Client ID Metadata Documents): DayZero fetches that URL, which must serve the client's metadata JSON with a matching client_id. These clients are always public (PKCE, no secret).
5. It opens your browser to GET /oauth2/authorize with PKCE (S256) and an optional RFC 8707 resource parameter (must match the MCP server URL).
6. You sign in via Clerk and review the consent page, which shows:
   • The app name and human-readable scope descriptions
   • Your signed-in identity and accessible businesses (via GET /oauth2/userinfo)
   • Which businesses the app may reach — all of them, or only one you pick — and an Allow changes box (see Choosing a business and allowing changes)
   • Where you'll be redirected after approval (with loopback / non-HTTPS warnings when applicable)
7. After you click Allow access, the client exchanges the authorization code at POST /oauth2/mcp/token for an MCP access token (plus a refresh token when the grant includes offline_access).
8. The access token (valid for 60 minutes) is sent as Authorization: Bearer … on every MCP request and refreshed automatically when it expires.

MCP sign-in is open to every account. If your firm has disabled API access for your user, authorization fails with access_denied.

OAuth scopes

Scopes appear on the consent page in plain English:

Write tools require both mcp:write and write permission on the business. A token with only mcp:read can query data but cannot call write tools.

mcp:admin is different from the other scopes: it is not advertised in scopes_supported, a client cannot obtain it by asking, and a superuser's token does not carry it by default. It is granted only when a DayZero staff member ticks Act as DayZero staff on the consent screen. Without it, a staff member's token behaves like any customer's, and the admin tools return 403 with a message pointing back to that box.

A few scope rules to be aware of:

• Refresh tokens are only issued when the grant includes offline_access. Without it, the client gets an access token only and must re-authorize when it expires. A refresh may narrow the scopes but never widen them.
• If a client requests no scopes at all, it is granted mcp:read offline_access (read-only, but able to stay connected).
• If a client registered with an explicit scope, requests are narrowed to that registered set — a read-only registration cannot later escalate to mcp:write.

If the token is missing or invalid, the server returns 401 with a WWW-Authenticate header pointing to the resource metadata endpoint.

Choosing a business and allowing changes

The consent screen asks two things before you approve:

• Businesses. Keep All businesses you can access, or pick Only one business from the list. If you can open just one business, that business is picked for you. A connection limited to one business:

  • works on that business only. Asking for any other business returns 403 — "This connection is limited to ProScore. Reconnect DayZero to work on another business." A tool call that names another business anywhere in its arguments is refused before it runs;
  • uses that business when a tool call names none;
  • cannot use firm-wide tools (get_firm_client_overview, get_firm_user_activity) or DayZero staff tools, and is never staff — the Act as DayZero staff box is turned off while one business is picked;
  • lists the full tool catalog on /mcp (minus staff tools), so agents can call any tool for that business;
  • keeps its business for good: refreshing the token never changes it. To work on another business, connect again and pick it. If you lose access to the business, the connection stops (401, asking you to reconnect).

  The token response names the business (business_id, business_name), get_connection_info reports it, and Settings → Developers shows it on the connected app. One app can hold one connection per business plus one for all businesses; disconnecting one leaves the others working.

• Allow changes. Ticked, the app gets mcp:write and can create and edit records — each risky change still asks you first. Unticked, it can only read. The box starts ticked only when the app asked to make changes, and it is offered only when the app's registration allows changes.

Revoking access

OAuth-connected MCP clients (e.g. Claude Desktop, Cursor) create a connected app grant tied to your account. Revoke a grant to immediately invalidate its refresh token:

# List connected apps (requires a DayZero session or REST OAuth token)
curl "https://api.ondayzero.com/api/v1/oauth/grants" \
  -H "Authorization: Bearer YOUR_SESSION_OR_API_TOKEN"

# Revoke a grant by ID
curl -X DELETE "https://api.ondayzero.com/api/v1/oauth/grants/GRANT_ID" \
  -H "Authorization: Bearer YOUR_SESSION_OR_API_TOKEN"

Revoking a grant blacklists its refresh token and every active access token issued under it, so access is cut off immediately — not when the access token would naturally expire. You can also disconnect an app from Connected apps under Settings → Developers.

Revoking an MCP grant does not affect REST API keys — manage those separately under Settings → Developers.

Security notes

• MCP tokens carry JWT type=mcp and audience = the MCP resource URL — distinct from REST access, refresh, and api tokens.
• The consent screen is a React page served at GET /oauth2/authorize; standalone error pages use Jinja2 templates. Both ship strict security headers (CSP nonce, X-Frame-Options: DENY, Referrer-Policy: no-referrer).
• Dynamic client registrations expire after ~90 days of inactivity; clients re-register automatically.
• Registered redirect URIs are validated: https, loopback http (with a callback path), and the app schemes cursor://, vscode://, cursor-ide:// and claude:// are allowed; javascript:/data:/file: and http on non-loopback hosts are rejected, as are URIs with credentials or a fragment.
• PKCE (S256) is mandatory — authorization codes cannot be exchanged without a valid code verifier.
• DNS-rebinding protection validates the Host header and allowlists the Origin header on every MCP request (see Browser-based and hosted clients). Requests with an unrecognized Origin are rejected with 403.
• Refresh tokens are bound to the client they were issued to; the refresh grant requires client_id (and the client secret for confidential clients) and rejects tokens presented by a different client.
• Refresh tokens rotate on every use. Replaying an already-rotated token after a short grace window (about 5 minutes, which absorbs retries) is treated as possible theft and revokes the grant, so the client must sign in again.
• POST /oauth2/register, POST /oauth2/mcp/token and GET /oauth2/authorize are rate-limited per client IP and return 429 with a Retry-After header when exceeded.

Example Conversation

Once connected, just start asking questions — no setup required:

Single business (most common):

You: What invoices are overdue?

Assistant: You have 3 overdue invoices totaling $4,250.00…

The server auto-detected your business behind the scenes. No IDs needed.

Multiple businesses:

You: Show me last month's transactions

Assistant: You have access to 2 businesses:

1. Acme LLC — admin
2. Beta Corp — viewer

Which one would you like to use?

You: Acme

Assistant: Here are Acme LLC's transactions for last month…

After you pick, the assistant remembers your choice for the rest of the conversation. Say "switch to Beta Corp" at any time to change.

More things you can ask:

• "List all bank accounts"
• "Show me the last 10 transactions from checking"
• "Generate a profit and loss report for Q1 2026"
• "Create a journal entry for $500 rent expense on March 1"
• "Search for anything related to Acme Corp"
• "Compare the operating budget to actuals this quarter"
• "What are our top expenses this year?"
• "Are we cash-flow positive this quarter?"
• "How have profit margins changed over the past 6 months?"
• "How many transactions came in last month?"
• "What should I look at today?" (Daily Brief)
• "Mark that Amazon transaction as reviewed"
• "Add a new vendor called Acme Hosting with email billing@acme.com"
• "Create a $250 bill from Acme Hosting due next Friday"
• "Finalize draft invoice #1042"
• "Email invoice #1042 to the customer"
• "How much do we owe vendors by aging bucket?"
• "Void invoice #1042"
• "Create a $25 credit memo for Acme and issue it"
• "Cancel the draft bill from Acme Hosting"
• "Mark these three bank transactions as reconciled"
• "What's blocking us from creating invoices via API?"

Troubleshooting

What's Next?

• Authentication — managing API tokens
• First Request — getting started with the REST API
• Reports — available report types and formats