MCP Tool Reference

This page documents the tools available on https://mcp.numeralhq.com/mcp. It mirrors what tools/list returns, but the server is the authoritative source — call tools/list to see the live catalog for your account. Conventions that apply throughout:

• Amounts are decimal strings, and identifiers too large for a JSON-safe integer are strings too. Parse them as such rather than as numbers.
• Timestamps are ISO 8601, except fields suffixed _at that are explicitly documented as Unix epoch seconds.
• Jurisdiction IDs are uppercase, like US-CA or CA-BC. Always pass jurisdiction_id filters in uppercase — a lowercase value such as us-ca matches nothing and returns an empty list rather than an error.
• merchant_id accepts either the Numeral ID (mer_...) or the reference_merchant_id you supplied when creating the merchant.
• Paginated tools return has_more and a cursor; pass that cursor value back as the cursor argument to fetch the next page.
• Failures return { error_code, error_message } — see error codes.

​

Merchants

Your merchant roster. Filings, nexus, registrations, and products are account-level; transactions and sales can be scoped to a single merchant.

​

list_merchants

Lists the merchants on your account, returning each merchant’s Numeral ID, your reference_merchant_id, name, and default address. Paginated.

​

get_merchant

Fetches a single merchant’s profile, including tax IDs.

​

Nexus

​

get_nexus_study

The account’s current nexus position per jurisdiction: whether nexus has been triggered (economic and/or physical), the economic thresholds with current sales and transaction counts measured against them, and any physical presence on record. Returns jurisdictions and physical_presences arrays. Both are empty if no nexus data has been established yet.

​

Registrations

​

list_registrations

The account’s state sales-tax registrations: jurisdiction, status, account number, effective start date, and completion or deregistration timestamps. Registrations are managed by Numeral, so this surface is read-only by design.

​

Filings

​

list_filings

The account’s sales-tax filings, upcoming and past: jurisdiction, status, filing period, due date, and tax, penalty, and interest amounts. Valid statuses: unfiled, in_progress, pending_admin_approval, pending_client_approval, client_approved, filed, client_rejected, admin_rejected, has_problems, canceled, on_hold, transmitting, pending_ack, pending_payment, pni_portal_review An unrecognized status returns invalid_filing_status along with the valid list, so an agent can correct itself.

​

get_filing

A single filing’s detail, including the calculated sales data backing the return. This is the tool to use when reviewing a filing.

​

Transactions and sales

​

list_transactions

API-recorded tax transactions — purchases, refunds, and refund reversals — newest first. Returns summaries; use get_transaction for line items.

​

get_transaction

A single transaction’s full detail: destination address, line items with computed tax amounts, and the tax jurisdictions applied to each line item.

​

get_sales_summary

Aggregated sales from API transactions, grouped by month, destination country and state, currency, and liability category. Returns transaction count, net sales (refunds subtract), and tax collected. Liability categories tell you who is responsible for remitting the tax:

​

Products

​

list_products

The account’s products and the tax category assigned to each. The tax category determines taxability per jurisdiction. Paginated by reference_product_id.

​

list_tax_categories

The Numeral tax category catalog. Each category maps a product to its taxability rules. See product categories for background on how categories drive taxability.

​

Exemption certificates

​

list_certificates

The account’s exemption certificates: status, certificate type, linked customer or buyer, jurisdictions, and effective and expiration dates. Paginated. Statuses: processing, needs_info, active, expiring, expired, invalid

​

get_certificate

A single certificate by ID, including a time-limited download URL for the certificate document when one is available.

​

get_certificate_upload_status

Processing status of a certificate upload. Once files finish processing, certificate_ids lists the resulting certificates, which you can inspect with get_certificate. Numeral’s pipeline classifies the jurisdiction and certificate type from the document itself. Upload statuses: pending (still processing), completed, failed, duplicate For how exemptions affect calculations, see exemptions behavior.

​

Write tools

The MCP server currently exposes read-only tools. Write capabilities exist and are gated behind a server-side setting that is off by default: Because gated tools are not registered at all, they do not appear in tools/list — an agent will not discover them and then fail when calling them. When write access is enabled for your account, they appear in the catalog automatically and your agent can use them with no code changes on your side. In the meantime, filing approval and rejection, product recategorization, and certificate upload are all available in the Numeral dashboard and, where applicable, the REST API.