Tools

Current public tool catalog for Jupid hosted MCP.

Business data is scoped to the authorized user's active Jupid business. Search tools return bounded results with totals and links back to the app. Use IDs from those results when calling detail tools. To connect a client first, follow the quickstart.

Conventions used across all tools:

• Resolve "last month" or "Q1" into explicit dates before calling. Ingestion requires YYYY-MM-DD; reports also accept ISO 8601 datetimes. Transaction timestamps use ISO 8601; Stripe billing period timestamps use Unix seconds.
• Transaction amounts are signed: negative for outflows, positive for inflows. Ingestion uses the supplied currency's units, not cents. Read fields named amountUsd or currentBalanceUsd expose stored amounts without converting currencies; do not treat mixed-currency totals as converted USD. Report summary outflows and expenses are positive magnitudes.
• Search limit accepts 1–50 and defaults to 20. Ingestion batches accept 1–500 records. Searches have no page cursor: use total and hasMore to detect truncated results, then narrow the filters.
• Account numbers are masked and raw provider payloads are excluded. Business data comes only from the business resolved for the authorized user.

Profile and accounts

getProfile

• Purpose: get the current Jupid profile, company summary, and data coverage.
• Inputs: none.
• Output: the signed-in user's profile, the active business's company summary, data counts, transaction date range, pending count, and app link.

listAccounts

• Purpose: list data sources and their accounts, including connection status.
• Inputs: optional includeInactive (boolean, default false).
• Output: connections, account names, masked account numbers, statuses, balances, sync timestamps, totals, and app links. Each connection has a health of ok, needs_reauth, pending_expiration, error, or revoked, and a lastError (code, at) while it is not connected.

By default, each source contains only active accounts. Set includeInactive to include other account statuses; deleted accounts remain excluded. Sources can appear with a revoked status or an empty account list.

Example questions:

• "What data is connected to Jupid?"
• "Which accounts are active?"
• "When did my accounts last sync?"
• "Does any bank need to be reconnected?"

listConnectionActivity

• Purpose: list recent events of the business's data connections, newest first.
• Inputs, all optional: connectionId (a connection id from listAccounts), kinds (event kinds to include), since (ISO 8601 datetime), limit (1–50, default 20).
• Output: events with kind, occurredAt, via, the connection's provider and name, and details limited to codes, counts, and reasons. Kinds are connected, accounts_updated, repaired, disconnected, needs_reauth, pending_expiration, error, new_accounts_available, and transactions_synced (only syncs that changed transactions).

Example questions:

• "Why did my bank stop syncing?"
• "When was my bank last reconnected?"

Categories

listCategories

• Purpose: list the classification categories available to the user.
• Inputs: none.
• Output: enabled public classification ontologies and category nodes with paths, names, descriptions, and codes, plus ontology mandatory/exclusive flags. Each category has a path array and a dot-separated pathText string.

This tool is read-only. It does not expose category editing or direct recategorization.

Example questions:

• "What categories does Jupid use?"
• "Which categories exist for meals or software?"

Transactions

searchTransactions

• Purpose: search and filter transactions.
• Inputs, all optional:
  • query (string) — merchant, description, category, or context keywords. Omit it for requests such as "latest 10 transactions".
  • dateFrom, dateTo (ISO date; date-only dateTo is inclusive).
  • dateField — "primary" (default), "authorized", or "processed".
  • amountFrom, amountTo (numbers) — minimum and maximum signed amounts. For expenses over $500 in USD data, use amountTo: -500. Zero bounds are ignored; omit unused bounds.
  • categoryPath (string) — use a category's pathText from listCategories.
  • counterpartyId (string), accountIds (string array) — IDs from other tools.
  • needsAttention (boolean) — true restricts results to attention items; false leaves this filter off.
  • limit (1–50, default 20).
• Output: bounded transaction results with category and counterparty names, filing status, context narrative, totals, and per-transaction app links.

getTransaction

• Purpose: get detail for one transaction.
• Inputs: required transactionId (from searchTransactions results).
• Output: transaction detail, notes, fee and net amounts when present, categories, context narrative, and app link.

Example questions:

• "Show transactions with Stripe last quarter."
• "Find expenses over $500 that need attention."
• "Show me the details of that $1,200 Stripe charge."

For vendor drill-downs, use searchCounterparties first, then call searchTransactions with the returned counterpartyId.

Counterparties

searchCounterparties

• Purpose: search vendors, clients, investors, contractors, and other counterparties.
• Inputs, all optional:
  • query (string) — name or public metadata keywords.
  • relationship — client, service, partner, contractor, investor, owner, lifestyle, supplier, utility, landlord, lender, insurer, payment_processor, marketplace, regulator, tax_authority, donation_recipient, payroll, or unknown.
  • type — company, person, government, non-profit, educational, financial, healthcare, religious, charity, association, cooperative, partnership, trust, or estate.
  • limit (1–50, default 20).
• Output: bounded counterparty results, relationship and type fields, transaction stats, enrichment status, confidence level, totals, and links.

getCounterparty

• Purpose: get detail for one counterparty.
• Inputs: required counterpartyId (from searchCounterparties results).
• Output: public counterparty metadata, narrative, sources, matching rules, stats, up to 10 recent transactions, and app link.

Example questions:

• "Who are our investors?"
• "List contractors."
• "What do we know about Anthropic?"

Reports

Reports use filed transactions. startDate and endDate accept YYYY-MM-DD or ISO 8601 datetimes; a date-only endDate includes the whole UTC day.

periodLimit is a positive integer selecting the newest periods, with a default of 12. Summary totals cover the full requested range even when the period breakdown is shorter. Check basis.truncated and basis.totalPeriodsInRange; increase periodLimit when you need the period values to reconcile with the full-range totals.

getCashflowReport

• Purpose: get filed cash-flow by period, category tree, and counterparty.
• Inputs:
  • Required startDate and endDate (date or datetime strings).
  • dateField — "processed_at" (default) or "authorized_at".
  • periodGrouping — "quarter", "month" (default), "week", or "day".
  • periodLimit (default 12).
  • categoryNames (string array) — matches category names within a path.
  • categoryPaths (string[][]) — category-name path prefixes from the report's categoryTree[].path, including descendants. These are display-name paths, unlike the key paths returned by listCategories.
  • ontologyId or ontologyKey (string) — defaults to the Schedule C ontology. counterpartyIds (string array) optionally filters counterparties.
• Output: basis metadata, summary totals, periods, full category tree, counterparty attribution, and app link.

getPnlReport

• Purpose: get a Schedule C P&L report (pinned to the tax_us_schedule_c ontology).
• Inputs: required startDate and endDate; optional dateField, periodGrouping, periodLimit, and category filters — same formats as getCashflowReport.
• Output: revenue, COGS, gross profit, operating expenses, net profit, margins, periods, deductible category tree, and app link.

Example questions:

• "Compare cash flow this month vs last month."
• "Generate a P&L for Q1."
• "Who are my top paying clients this year?"

Outstanding issues

listOutstandingIssues

• Purpose: list open questions that need user context.
• Inputs: optional objectType — "transaction", "counterparty", or "company" — and limit (1–50, default 20).
• Output: issue and related-hook IDs, object summaries, questions, rationale, answer options when present, task references, totals, and app links.

answerOutstandingIssue

• Purpose: save an explicit answer to one open issue.
• Inputs: required hookId (the issue ID returned by listOutstandingIssues) and answer (string); optional selectedOption (string or null).
• Output: status and hookId. A completed answer also returns relatedHookIds, objectType, objectId, taskType, taskId, and eventsSent. Other statuses are not_found, skipped (with currentStatus), unsupported (with objectType), and object_not_found.

Call this tool only with an answer the user explicitly supplied. It replaces the object's context narrative and completes the selected hook plus related open hooks for the same object. A repeated answer to a completed hook returns skipped. eventsSent: true means the follow-up processing events were sent; false means the answer was saved but those events were not sent. Completion does not mean categorization finished, and the tool does not directly edit categories.

Example questions:

• "What still needs my review?"
• "Answer this issue: it was a business lunch with a client."

Setup and billing

getAgentConnectionInfo

• Purpose: get setup details for connecting external AI agents.
• Inputs: none.
• Output: MCP URL, transport, auth mode, Codex config, Cursor config, and app setup link.

getBillingStatus

• Purpose: get your personal billing status from synced Stripe subscriptions.
• Access: owners and members read their own subscription. Select a business before using the external MCP connection.
• Inputs: none.
• Output: paid flag, status, subscription details when present (including cancellation flag, period timestamps, and price ID), and billing page link. Missing billing records produce statuses such as no_customer or no_subscription; unknown can have a null paid flag.

Partner-provided paid access is separate and is not reflected in this response. Billing changes must be made in the Jupid web app. MCP can report status and return a link; it cannot change plans, cards, Jupid subscription invoices, or payment methods. The outgoing customer invoices below are separate.

Example questions:

• "How do I connect Jupid to Codex?"
• "What is my billing status?"
• "Where do I manage billing?"

Synchronize data

These four tools use the same validation, writes, and processing as the HTTP API. Demo users cannot call them. Partner source creation uses POST /api/v1/auth/partner; MCP has no separate source-creation tool.

upsertAccounts

• Inputs: source_id (connected API-source UUID) and accounts (1–500 items).
• Each account requires external_id, name, type, currency, and current_balance. See the account schema.
• Output: accounts, each with id and external_id.

upsertTransactions

• Inputs: account_id (Jupid UUID) and transactions (1–500 items).
• The account must belong to a connected API source in the active business.
• Each transaction requires external_id, amount, date, and description; pending and currency are optional. See the transaction schema.
• date is a UTC YYYY-MM-DD date. pending defaults to false and currency to the account's currency.
• Output: transactions, each with id and external_id.

Transaction external IDs are unique across all accounts in a source and cannot move between accounts. Repeats update bank fields while preserving Jupid IDs and local filing, notes, categories, and deletion state. Acceptance waits for saving and the background-processing event, not AI completion. Omitted records are left unchanged.

deleteAccount

• Input: account_id (Jupid UUID).
• Requires owner membership in the active business.
• Disconnects the account and preserves transaction history. Revokes its source when no active accounts remain.
• Output: account_id and deleted: true. Repeated deletion succeeds.

deleteTransaction

• Input: transaction_id (Jupid UUID).
• Soft-deletes the transaction.
• Output: transaction_id and deleted: true. Repeated deletion succeeds.

Customer invoicing

These tools operate on outgoing USD invoices in the selected business. The Box uses its fixed company's records, regardless of a person's active business. The invoice ID, number and /invoices/{id} app link identify the same record in both the agent and invoice interface. No tool accepts a company override. Demo users cannot call invoice write tools.

getInvoiceDefaults

• Input: optional counterpartyId from searchCounterparties.
• Output: company and optional customer, each containing only the known ID, name, address and business contact email; currency is USD.
• Missing company or contact values stay absent. Ask the user for necessary missing facts. A contact email does not authorize sending an invoice.

listInvoices

• Inputs: optional status (draft, paid, canceled), counterpartyId, exact customerName, exact invoiceNumber, limit (1–50, default 20), and offset (default 0).
• Output: compact invoice summaries, totals, current versions, app links, total and hasMore. Advance offset by the number returned for the next page. This pagination applies to invoices; transaction and counterparty searches still use bounded single-page results.

getInvoice

• Input: invoiceId (UUID).
• Output: invoice with line items, parties, dates, notes, calculated dollar amounts, status, version and pdf_version, plus appPath and url.
• Raw internal metadata, ownership IDs and private storage paths are excluded.

createInvoice

• Required inputs: requestKey, issueDate (YYYY-MM-DD), fromName, toName, and nonempty lineItems (description, positive quantity, nonnegative dollar unitPrice).
• Optional inputs: counterpartyId (UUID or null, default null), dueDate, fromAddress, toAddress, notes, taxRate (0–100, default 0), and dollar discount (default 0). Null customer ID supports an ad hoc customer whose name and address the user supplies.
• Output: the saved invoice, app link and pdfError (null on success).

Use a stable requestKey (1–200 characters) for the requested creation. Repeat the same key and contents after a timeout; a changed payload under the same key is rejected. A retry returns the existing record. The server assigns the next company INV-0001-style number with no annual reset or manual override. Totals are calculated on the server; amounts are dollars, not cents.

The invoice is saved before generating its PDF. If pdfError is present, retain the returned ID and call getInvoicePdf to recover. Do not create a second invoice. Creation does not send email.

updateInvoice

• Inputs: invoiceId, current version from getInvoice, and the complete editable contents described under createInvoice (without requestKey).
• Output: the saved invoice, app link and pdfError.
• A stale version is rejected: reload before deciding whether to edit again. Edits retain the invoice number and ID, increment the version and regenerate its PDF. Previously emailed drafts remain editable. Editing does not resend. Paid and canceled invoices cannot be edited.

getInvoicePdf

• Input: invoiceId.
• Output: invoiceId, invoiceNumber, version, pdfUrl, expiresInSeconds (900), and the app link.
• Generates a missing or stale PDF before returning a signed private link. It is a write tool because it can generate a document. The link represents the returned version; editing later creates a new version.

setInvoiceStatus

• Inputs: invoiceId and status (paid or canceled).
• Output: the resulting invoice and app link.
• Only drafts can change status. Repeating the current status succeeds. Marking paid records the user's statement; it does not collect payment. There is no invoice deletion tool or transition back to draft.

Example requests:

• "Create a $1,500 consulting invoice for Acme, due October 1."
• "Change the quantity on invoice INV-0042 and give me the updated PDF."
• "Mark INV-0042 paid."

getInvoiceEmailDetails

• Input: invoiceId (UUID).
• Output: senderEmail (the company's existing The Box agent email), recipient (suggested customer email), and deliveries (send receipts).
• No configured Box address means sending is unavailable. A suggested recipient is not permission to send.

sendInvoice

• Inputs: invoiceId, current invoice version, explicit recipient, and stable requestKey (1–200 characters).
• Sends the current PDF from the company's existing The Box agent email, using the same address for replies. Callers cannot override the sender.
• Output: delivery, appPath and url. The receipt includes its ID, request key, invoice number/version, sender, recipient, timestamps, send status, provider ID/status and any error.
• Save the key before calling. A timeout or unknown outcome must reuse the exact key, recipient and version. A separately requested resend gets a new key. Editing alone never emails anyone.
• accepted means the provider accepted the message, not confirmed delivery. An uncertain attempt older than the safe retry window requires checking the original delivery before creating another send.

getInvoiceDelivery

• Inputs: deliveryId (UUID), optional refresh (default false).
• Output: the saved delivery receipt. Refresh reads provider status and updates the saved status; it never sends another email.
• Demo users cannot send invoices or refresh delivery status.

Not available yet

Jupid MCP does not currently expose direct recategorization, category editing, CSV or file upload, provider pull-sync triggers, direct billing changes, online invoice payment, incoming supplier invoice tools, or tax filing tools.

External MCP clients cannot manage company participants or permissions. The Box's delegated access tool is available only through its separate company-bound connection and a verified owner's request. Partner company access is managed by the partner.