API reference
API reference
Every endpoint, field, and response. Field lists come from the validators the API checks requests against, and descriptions come from the OpenAPI spec the API serves, so this reference changes when the API does.
Base URL and authentication
https://tax-mcp.com
Authorization: Bearer <API key>All requests use HTTPS and JSON. See Requests & authentication for the rules every endpoint shares and Responses & states for the envelope every response carries.
Endpoints
| Endpoint | What it does |
|---|---|
| POST /tax-compute/federal | Compute a federal Form 1040. |
| POST /tax-compute/state | Compute a California, New York, Illinois, North Carolina or Michigan return. |
| POST /tax-compute/reconcile | Recompute a CA return and diff it against a filed return. |
| POST /tax-compute/what-if | Compute up to 25 independent federal scenarios. |
| POST /tax-compute/review-packet | Assemble up to 25 recomputed profiles into a review packet. |
| POST /tax-compute/amended-return | Compute Form 1040-X columns A, B and C for an amended 2020-2025 return. |
| POST /tax-compute/efile-readiness | Form 8879 amounts and an e-file readiness check for a 2023-2025 return. |
| POST /tax-compute/return-lines | Every Form 1040 line of a 2023-2025 return, in that year's numbering. |
| POST /tax-compute/draft-pdf | That Form 1040 on the official IRS PDF, as a draft not for filing. |
| GET /tax-capabilities | Discover the supported envelope without sending taxpayer data. |
| POST /intake/read | Read a broker 1099-B CSV into unconfirmed lot evidence. |
| MCP transport | The /mcp endpoint and its five tools for MCP clients. |
Paths are under /api/mcp, for example /api/mcp/tax-compute/federal. The MCP transport is at /mcp.
Machine-readable contracts
/api/openapi.json: OpenAPI 3.1, for client generation and GPT Actions./api/mcp/tax-capabilities: the supported envelope, version2026-10-25.27. Record the version you integrate against.
Conventions
- Amounts are whole dollars. Field names are camelCase in requests; contract fields are snake_case.
- Request schemas are strict: an unknown field is a 400, never silently ignored.
- Omitting a schedule field means the schedule does not exist (see Leaving a schedule out).
- Responses carry some fields only when they apply (for example
owedOrRefundoramtDerivation), and gain fields as coverage grows. Ignore fields you do not recognize.
Roadmap status for this page
Generated from the roadmap (updated 2026-10-30). Shipped & certified means live and independently checked against primary tax sources; certifying means live, with those checks still in progress. 1 related item is planned and not available yet; see the roadmap.
| Capability | Status |
|---|---|
| OpenAPI 3.1 spec — full ComputeResult output schema + decline-code enumPublishes an OpenAPI 3.1 spec with the full compute-result output schema and the decline-code enum. | ✅ shipped & certified |