> ## Documentation Index
> Fetch the complete documentation index at: https://docs.numeral.com/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Tool Reference
> Every tool the Numeral MCP server exposes, with its inputs.
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.
All tools listed here are **read-only**. They operate on the account and mode your API key belongs to; none of them accept an account identifier. See [write tools](#write-tools) for capabilities that modify data.
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](/mcp/authentication#tool-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.
| Parameter | Type | Description |
| --------- | ----------------- | -------------------------------------- |
| `cursor` | string, optional | Pagination cursor from a previous call |
| `limit` | integer, optional | Page size (default 25, max 100) |
### `get_merchant`
Fetches a single merchant's profile, including tax IDs.
| Parameter | Type | Description |
| ------------- | -------------------- | --------------------------------------------------------------- |
| `merchant_id` | string, **required** | Numeral merchant ID (`mer_...`) or your `reference_merchant_id` |
## 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.
| Parameter | Type | Description |
| ----------------- | ---------------- | ---------------------------------------- |
| `jurisdiction_id` | string, optional | Limit to one jurisdiction (e.g. `US-CA`) |
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.
| Parameter | Type | Description |
| ----------------- | ---------------- | ----------------------------------------------------------------- |
| `status` | string, optional | Filter by registration status (e.g. `registered`, `unregistered`) |
| `jurisdiction_id` | string, optional | Limit to one jurisdiction (e.g. `US-NY`) |
## Filings
### `list_filings`
The account's sales-tax filings, upcoming and past: jurisdiction, status, filing period, due date, and tax, penalty, and interest amounts.
| Parameter | Type | Description |
| ----------------- | ------------------------------- | -------------------------------------------- |
| `status` | string, optional | Filter by filing status |
| `jurisdiction_id` | string, optional | Limit to one jurisdiction |
| `due_after` | string (`YYYY-MM-DD`), optional | Only filings due on or after this date |
| `due_before` | string (`YYYY-MM-DD`), optional | Only filings due on or before this date |
| `limit` | integer, optional | Max filings to return (default 100, max 500) |
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.
| Parameter | Type | Description |
| ----------- | --------------------- | ----------------- |
| `filing_id` | integer, **required** | Numeral filing ID |
**Review flow.** Call `list_filings` with `status: "pending_client_approval"` to find filings awaiting your review, then `get_filing` to inspect one. Approving or rejecting currently happens in the [Numeral dashboard](https://dashboard.numeralhq.com) — see [write tools](#write-tools).
## Transactions and sales
### `list_transactions`
API-recorded tax transactions — purchases, refunds, and refund reversals — newest first. Returns summaries; use `get_transaction` for line items.
| Parameter | Type | Description |
| -------------------- | --------------------------- | ------------------------------------------------------- |
| `merchant_id` | string, optional | Only this merchant's transactions |
| `reference_order_id` | string, optional | Only transactions for this reference order |
| `processed_after` | string (ISO 8601), optional | Only transactions processed at or after this timestamp |
| `processed_before` | string (ISO 8601), optional | Only transactions processed at or before this timestamp |
| `cursor` | string, optional | Pagination cursor from a previous call |
| `limit` | integer, optional | Page size (default 25, max 100) |
### `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.
| Parameter | Type | Description |
| ---------------- | -------------------- | --------------------------------- |
| `transaction_id` | string, **required** | Numeral transaction ID (`tr_...`) |
### `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.
| Parameter | Type | Description |
| ------------- | ------------------------------- | ------------------------------------------------ |
| `merchant_id` | string, optional | Only this merchant's sales |
| `from` | string (`YYYY-MM-DD`), optional | Start date, inclusive. Defaults to 12 months ago |
| `to` | string (`YYYY-MM-DD`), optional | End date, inclusive. Defaults to today |
Use this tool — not repeated `list_transactions` calls — for questions like "sales by state last quarter" or "monthly sales for merchant X". Paging through raw transactions to aggregate them by hand is slow and burns your rate limit.
**Liability categories** tell you who is responsible for remitting the tax:
| Category | Meaning |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `merchant_responsible` | The merchant collects and remits this tax themselves; the platform only processed the payment |
| `marketplace_facilitated` | The platform remits as marketplace facilitator. The merchant does not remit, but these sales generally still count toward the merchant's economic-nexus thresholds |
| `platform_merchant_of_record` | The platform is the seller of record and owns the liability; shown for sales visibility only |
| `marketplace_and_merchant_of_record` | The platform declared both roles on these transactions; the split between them is not recorded |
| `platform_fees` | Tax on the platform's own fees, which the platform remits |
| `direct` | Transactions recorded without platform roles |
For the marketplace and merchant-of-record categories, platform fee line items are included in the totals — the underlying data model does not separate them from order lines in those cases.
## 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`.
| Parameter | Type | Description |
| --------- | ----------------- | -------------------------------------- |
| `cursor` | string, optional | Pagination cursor from a previous call |
| `limit` | integer, optional | Page size (default 50, max 100) |
### `list_tax_categories`
The Numeral tax category catalog. Each category maps a product to its taxability rules.
| Parameter | Type | Description |
| --------- | ---------------- | ------------------------------------------------------ |
| `search` | string, optional | Case-insensitive match on category name or description |
See [product categories](/essentials/product-categories) for background on how categories drive taxability.
## Exemption certificates
Certificate tools are **live mode only**. Calling them with an `sk_test_` key returns `live_mode_required`.
### `list_certificates`
The account's exemption certificates: status, certificate type, linked customer or buyer, jurisdictions, and effective and expiration dates. Paginated.
| Parameter | Type | Description |
| ----------------- | ----------------- | ------------------------------------------------------------------ |
| `status` | enum, optional | One of the statuses below |
| `jurisdiction_id` | string, optional | Limit to one jurisdiction |
| `customer_id` | string, optional | Numeral customer ID (`cust_...`) or your own reference customer ID |
| `cursor` | string, optional | Pagination cursor from a previous call |
| `limit` | integer, optional | Max certificates to return (default 25, max 100) |
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.
| Parameter | Type | Description |
| ---------------- | -------------------- | ------------------------------- |
| `certificate_id` | string, **required** | The certificate ID (`cert_...`) |
### `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.
| Parameter | Type | Description |
| ----------- | -------------------- | -------------------------------------------------------- |
| `upload_id` | string, **required** | The upload ID returned by `submit_exemption_certificate` |
Upload statuses: `pending` (still processing), `completed`, `failed`, `duplicate`
For how exemptions affect calculations, see [exemptions behavior](/essentials/integration-guides/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:
| Tool | What it would do |
| ------------------------------ | ----------------------------------------------------------------------------- |
| `approve_filing` | Approve a filing pending your review, releasing it for submission |
| `reject_filing` | Reject a filing pending your review, sending it back to Numeral with a reason |
| `set_product_tax_category` | Assign or change a product's tax category |
| `submit_exemption_certificate` | Upload a certificate document and start Numeral's processing pipeline |
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.
Contact us to discuss enabling write tools for your account.
In the meantime, filing approval and rejection, product recategorization, and certificate upload are all available in the [Numeral dashboard](https://dashboard.numeralhq.com) and, where applicable, the [REST API](/api-reference/v2026-03-01/introduction).