> ## 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 Overview
> Connect an AI agent directly to your Numeral tax data over the Model Context Protocol.
The Numeral MCP server is a single HTTPS endpoint that exposes your Numeral account — nexus, filings, registrations, transactions, sales, products, and exemption certificates — as tools an AI agent can call directly.
```
https://mcp.numeralhq.com/mcp
```
It speaks [Model Context Protocol](https://modelcontextprotocol.io), so any MCP-capable client (Claude Code, Claude Desktop, Cursor, or your own agent built on an LLM SDK) can connect with your existing Numeral secret API key and start answering questions like *"which states have I triggered nexus in, and are any filings waiting on my review?"*
Connect a client and make your first call in a few minutes.
Every tool the server exposes, with its inputs.
Keys, testmode, tenancy, rate limits, and error codes.
A complete public example app you can run locally.
## Why use the MCP instead of the REST API
The REST API is the right tool when you are writing code with a fixed, known shape — a checkout that calculates tax, a job that commits transactions. You decide at build time which endpoints to call.
The MCP server is the right tool when an **agent** decides at runtime what to look up. Because the server describes itself, your agent needs no Numeral-specific integration code:
* **`tools/list` replaces API documentation.** Every tool arrives with a description and a JSON Schema for its inputs. The agent reads the catalog and knows how to call each tool.
* **New capabilities appear automatically.** When Numeral ships a new tool, it shows up in `tools/list` on your next request and your agent can use it immediately — no SDK upgrade, no redeploy.
* **Errors are written for agents.** Failed calls return a stable, machine-readable `error_code` so the agent can correct itself and retry rather than giving up.
Both surfaces are backed by the same data and the same API keys, and you can use them together.
## Three MCP-related things, clearly separated
Numeral has more than one thing with "MCP" in the name. They do different jobs:
| | What it gives an agent | When to use it |
| --------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **Numeral MCP server**
`mcp.numeralhq.com/mcp` | Your live tax **data** — your filings, your nexus position, your transactions | You want an agent to answer questions about, or act on, your actual account |
| **`numeral-api-docs` MCP** | The **documentation** for the REST API — endpoint shapes, field names, versions | You want a coding agent to write correct REST integration code. See [AI help](/ai-help/overview) |
| **[Claude skills](/ai-help/overview)** | Written guidance on integration patterns and pitfalls | You want a coding agent to follow Numeral's recommended patterns |
This section of the docs covers the first one.
## What the tools cover
All tools operate on the account your API key belongs to. There is no account parameter, so a request cannot reach another tenant's data.
| Area | Tools |
| -------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **Merchants** | List your merchant roster and fetch a single merchant profile with tax IDs |
| **Nexus** | Current nexus position per jurisdiction — economic thresholds, sales against them, physical presence |
| **Registrations** | State sales-tax registration status, account numbers, effective dates |
| **Filings** | Upcoming and past filings with status, period, due date, and tax/penalty/interest, plus full detail on any one |
| **Transactions** | Purchases, refunds, and refund reversals; full line-item detail with computed tax per jurisdiction |
| **Sales** | Aggregated sales by month, destination, currency, and liability category |
| **Products** | Your products and their assigned tax categories, plus the Numeral tax category catalog |
| **Exemption certificates** | Certificates with status, type, linked buyer, and jurisdictions (live mode only) |
See the [tool reference](/mcp/tools) for exact names and inputs.
The tools available today are **read-only** — no tool changes your data. Write capabilities are gated per account; see [write tools](/mcp/tools#write-tools) for details.
## How it works
The server is a stateless [Streamable HTTP](https://modelcontextprotocol.io/specification/basic/transports) endpoint. Every request is a JSON-RPC 2.0 `POST` carrying your API key, authenticated on its own — there is no session to establish or maintain, and no state is retained between calls.
Three JSON-RPC methods matter:
| Method | Purpose |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `initialize` | Handshake. Returns the server's name, version, and an `instructions` document explaining auth, testmode, and how the tools relate to each other. |
| `tools/list` | Discovery. Returns every tool with its description and input JSON Schema. |
| `tools/call` | Invocation. `{"name": "list_filings", "arguments": {"status": "pending_client_approval"}}` returns the data. |
Most MCP clients handle all three for you — you supply a URL and a key. If you are building your own agent, the [demo application](/mcp/demo-app) shows the full loop in about 150 lines.
There is also a `GET /ping` health check that returns `{"status":"ok"}`.
## Next step
Point Claude Code, Claude Desktop, or Cursor at the server and ask your first question.