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

EndpointWhat it does
POST /tax-compute/federalCompute a federal Form 1040.
POST /tax-compute/stateCompute a California, New York, Illinois, North Carolina or Michigan return.
POST /tax-compute/reconcileRecompute a CA return and diff it against a filed return.
POST /tax-compute/what-ifCompute up to 25 independent federal scenarios.
POST /tax-compute/review-packetAssemble up to 25 recomputed profiles into a review packet.
POST /tax-compute/amended-returnCompute Form 1040-X columns A, B and C for an amended 2020-2025 return.
POST /tax-compute/efile-readinessForm 8879 amounts and an e-file readiness check for a 2023-2025 return.
POST /tax-compute/return-linesEvery Form 1040 line of a 2023-2025 return, in that year's numbering.
POST /tax-compute/draft-pdfThat Form 1040 on the official IRS PDF, as a draft not for filing.
GET /tax-capabilitiesDiscover the supported envelope without sending taxpayer data.
POST /intake/readRead a broker 1099-B CSV into unconfirmed lot evidence.
MCP transportThe /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

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 owedOrRefund or amtDerivation), 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.

Product-builder API, contract & trust surfaces
CapabilityStatus
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