# Otis workflows

Otis is a free MCP service for business records. Your AI handles conversation and document generation. Otis runs no inference and sends no invoices or team-invitation emails.

## Connect and discover

Read /llms.txt, try /demo/mcp without an account, then connect /mcp with your client's OAuth flow. Sign in using an email code in the browser. Never paste codes into chat. One verified email has one personal business and can join other businesses. Call businesses_list for business IDs and invitations. Omit business_id to use your personal business; include it on every call for a shared business. A connection grants the client access within your current membership permissions.

## Set up

1. business_get reports missing setup. business_set stores confirmed business name, currency and billing address. Optional invoice_preferences sets the number prefix/padding, starting number, default note and payment instructions. Omitted invoice_preferences preserves the existing settings. The starting number can only change before first issuance.
2. tax_guide returns dated country checklists and official references. Ask for missing facts. Country and currency do not determine tax.
3. tax_profile_set records country, state/province, registration status, numbers, effective dates, review date and notes. Only the owner can change the business or tax profile.
4. client_save stores billing details, country/region, business or consumer status, tax IDs and evidence. It replaces supplied client details; retain existing fields when editing.
5. Start recording immediately; incomplete tax setup only prevents invoice issuance.

## Team sharing

The owner calls team_invite with the person's email and editor/viewer role. This creates a seven-day invitation. No email is sent. Tell the person to connect Otis with that exact email and call businesses_list; they then call team_accept with business_id and invitation_id. Already connected users can discover invitations the same way. Invited users cannot read business records until accepting. Editors can record work, draft/issue invoices and report payments. Viewers can read and export records. Only owners manage members and business/tax settings. team_member_set changes a role or removes access immediately; removing access also blocks retries from existing OAuth tokens. The sole owner cannot be removed or downgraded. Ownership transfer is unavailable.

## Record work and expenses

billable_record accepts time, expense or ai_usage. Pass item_id to replace an existing unreserved, uninvoiced item. Reserved or billed source items cannot be edited. Cancel drafts first when appropriate. Audit history preserves the changes. Store total amount and quantity separately; optional rate_minor must match quantity × rate rounded half up. AI usage requires measured or estimated. Cost and billable price are distinct. expense_record stores vendor, category, date, cost and optional client/reference; billable_amount_minor atomically creates a linked billable. Do not create the same billable again. Pass expense_id to replace an expense; its linked billable updates atomically, retaining the same ID. Linked billables must be edited through expense_record. Include billable_amount_minor when updating a linked expense; zero stops billing an unreserved item. References can point to external documents; no files are uploaded.

## Partial billing

Every billable reports amount_minor, reserved_minor, invoiced_minor and remaining_minor. These track source amounts, before invoice discounts and before exclusive taxes. For inclusive lines, the allocation itself is the agreed inclusive price. List all relevant items and inspect remaining_minor; state=unbilled alone misses partially billed items. Each invoice line explicitly allocates an amount from one source item. A 100000 item can be allocated 40000 now and 60000 later. Drafts reserve allocations until issued or explicitly cancelled; reservations do not expire. Multiple drafts cannot reserve more than the source amount. Cancelling releases the reservation. Issuing moves it from reserved to invoiced. Discounting a 40000 allocation to 36000 still consumes 40000 of the original work. Partial allocation is by amount; the original quantity is a source snapshot, not a claim that the whole quantity was invoiced again.

## Tax and discount arithmetic

All money uses integer currency minor units: USD 125.00 = 12500; JPY 125 = 125. Supply the business ISO currency; it locks once financial records exist. No conversion is performed. Rates use integer parts per million: 20% = 200000, 8.875% = 88750. A tax component may have a taxable fraction: 80% = 800000. The server does not choose that fraction or decide whether it is lawful.

Line discounts apply first. Invoice discounts apply proportionally to the remaining line prices; largest fractional remainders receive leftover minor units, with line order breaking ties. Discounts can be fixed amounts or percentages. They reduce the tax base in this calculation model. Conditional discounts, rebates and rules requiring a different tax base are unsupported; verify applicability before using this model.

Line tax treatment is taxable, zero_rated, exempt, out_of_scope, reverse_charge or not_registered, with a jurisdiction, service category, reason and optional evidence. Missing tax is unknown, never an implicit tax-free decision. Taxable lines need named components; other treatments have no charged components. Multiple components use the same base and do not compound. Exclusive prices add each rounded component. Inclusive prices extract components from the discounted price using their combined effective rates; the remainder is net. Component amounts use half-up rounding per line. Invoice totals sum these recorded line results. There is no jurisdiction-specific rounding engine or automatic rate/registration lookup. Preserve source links and explain the recorded treatment.

## Draft, review and issue

invoice_draft reserves source amounts and snapshots business/client facts and line treatments. supply_date records the supplied date for tax review; it does not automatically determine a legal tax point. invoice_check returns ready, blockers, fields, messages and next_tool suggestions. A failed issue returns INVOICE_NOT_READY with the same structured feedback. Fix source facts and cancel/recreate the draft where instructed. Draft contents have no edit operation. Changed business/client facts make the old draft stale.

Show the exact draft, tax treatment and total to the user. Only then call invoice_issue with confirmed=true and expected_total_minor. Otis cannot independently prove human approval from an agent's flag. Server checks validate required fields, totals, permissions and allocations, not legal tax compliance. A sequential number is assigned atomically on issuance, starting at the configured starting_number (default 1) per business. display_number applies the recorded prefix and padding; number is the numeric sequence. Numbers are not reused. Issued contents are immutable. Issuance is not document generation or delivery; generate the document from the returned snapshot. Issued corrections, credit notes and voids are not available yet. Do not issue an invoice that needs a correction workflow Otis cannot currently represent.

## Payments and export

payment_record records reported partial/full payments against issued invoices. Use a stable, business-wide reference; identical references and facts do not double-count. Different facts under the same reference are rejected. Payments exceeding the outstanding balance are rejected. Bank verification, unapplied credits, payment reversals and automated reconciliation are unavailable. invoice_get and invoices_list compute paid and outstanding amounts from records.

records_export provides paginated JSON by kind, including audit. Follow next_offset until null. This is a record export, not a transactional backup or import/restore facility. Concurrent changes can affect pages; export during a quiet period when a consistent handoff matters. Financial records cannot currently be deleted or rewritten.

## Reliable calls and feedback

Every write requires a unique request_id, 8–128 characters. Reuse it only for the exact same action and business; permissions are rechecked even for retries. An identical retry returns the recorded result; a changed payload returns IDEMPOTENCY_CONFLICT. IDs are scoped to the acting user within a business. Retry transient failures with the same ID. Tool errors use isError plus structured ok=false, code, message and optional details. Never invent a missing value to silence a blocker.

Useful errors: FORBIDDEN (ask the owner); ALLOCATION_CONFLICT (reload remaining amounts); INVOICE_NOT_READY (follow blockers); TOTAL_CHANGED (review exact draft); PAYMENT_REFERENCE_CONFLICT (inspect payment); OVERPAYMENT (resolve mismatch, do not split to conceal it).

## Availability

Remote Streamable HTTP is the primary connection. MCP resources and a setup prompt provide context where the host supports them; tax_guide and tool feedback work through ordinary tools. Host support determines how instructions, resources and prompts appear. Reading a website does not install tools. No Otis npm package, marketplace plugin, or second business API is published. Public demo and signup endpoints have short-window abuse protection and may return 429 with Retry-After. Email requests are limited per address and IP; these security controls are not paid tiers. No operational dashboard exists. Quotes, corrections, automated tax filing, bank connections and inference are outside this build.