API reference
MCP transport
A Model Context Protocol endpoint for MCP clients such as Claude Code and Claude Desktop. Same engine and same results as the REST API, exposed as five tools.
POSThttps://tax-mcp.com/mcp
Connection
- Streamable HTTP, stateless. Protocol version 2025-06-18.
- Authenticate with
Authorization: Bearer <API key>; the key is checked before the MCP handshake. - Currently not metered and not billed (an eval posture, subject to change). No quota use and no idempotency keys. A flat ceiling of 60 requests a minute per key applies.
Claude Code
claude mcp add --transport http tax-mcp https://tax-mcp.com/mcp \
--header "Authorization: Bearer YOUR_MCP_API_KEY"Tools
| Tool | Input | Description |
|---|---|---|
| tax_capabilitiesTax capabilities (discovery) | None. | Return the machine-readable supported-envelope: which years / filing statuses / income fields / deductions compute per jurisdiction (federal, CA, NY, IL, NC, MI, no-income-tax states), and what declines. Call this FIRST to learn the exact fields the compute tools accept. Computation support only — NOT tax, legal, accounting, or financial advice. The customer is the preparer of record; see https://tax-mcp.com/terms. NON-BILLING/eval MCP compute (not metered). |
| tax_compute_federalCompute a federal return | { "profile": <federal request body> } — The federal tax profile (year, filingStatus, canBeClaimedAsDependent, noForeignOrTerritoryExclusionAffirmed, wages, and the fields from tax_capabilities). | Compute a federal individual income tax return (1040 ordinary + preferential LTCG/QDIV + NIIT + Additional Medicare + Schedule A/D + FTC de-minimis + a narrow Form 1116 safe-harbor above the de-minimis ceiling + simple rental + covered-2026 crypto) from a structured profile, OR return a §6694 honest DECLINE naming what a preparer must supply. Deterministic, no LLM. Pass the profile under "profile" (see tax_capabilities / https://tax-mcp.com/api/openapi.json for the field list). A decline is a normal successful result (computed:false). Computation support only — NOT tax, legal, accounting, or financial advice. The customer is the preparer of record; see https://tax-mcp.com/terms. NON-BILLING/eval MCP compute (not metered). |
| tax_compute_stateCompute a state return | { "profile": <state request body> } — The state tax profile; must include state (ca, ny, il, nc, mi, or ak/fl/nv/sd/tx/wy/tn/nh/wa), canBeClaimedAsDependent and noForeignOrTerritoryExclusionAffirmed. | Compute a California (Form 540) or New York (IT-201) full-year-resident 2025 return, an Illinois (IL-1040), North Carolina (D-400) or Michigan (MI-1040) full-year-resident 2020-2026 return, or a $0 answer for a full-year resident of a no-income-tax state (ak, fl, nv, sd, tx, wy, tn, nh, wa; 2020-2026), from a structured profile, OR return a §6694 honest DECLINE. Set profile.state. Deterministic. Pass the profile under "profile" (see tax_capabilities for the fields incl. the state affirmations). A decline is a normal successful result (computed:false). Computation support only — NOT tax, legal, accounting, or financial advice. The customer is the preparer of record; see https://tax-mcp.com/terms. NON-BILLING/eval MCP compute (not metered). |
| tax_compute_return_linesForm 1040 lines | { "request": <return-lines request body> } — The /return-lines request body (profile, payments and its optional fields). | Every Form 1040 line and Schedules 1-3, D and 8812 of one original 2023-2025 federal return in that year's numbering, each with its status, OR a §6694 honest DECLINE. Same request and result as POST /api/mcp/tax-compute/return-lines. A decline is a normal successful result (computed:false). Computation support only — NOT tax, legal, accounting, or financial advice. The customer is the preparer of record; see https://tax-mcp.com/terms. NON-BILLING/eval MCP compute (not metered). |
| tax_compute_efile_readinessForm 8879 e-file readiness | { "request": <efile-readiness request body> } — The /efile-readiness request body without PINs: profile, payments, paymentsAffirmed, signature and optional signedAmounts. | Form 8879 Part I amounts and an e-file readiness check (blockers) for one original 2023-2025 federal return, OR a §6694 honest DECLINE. Same request and result as POST /api/mcp/tax-compute/efile-readiness, except that PINs (taxpayerPin, spousePin, eroEfinPin, a prior-year pin) are refused. Computation support only — NOT tax, legal, accounting, or financial advice. The customer is the preparer of record; see https://tax-mcp.com/terms. NON-BILLING/eval MCP compute (not metered). |
Results
- A tool result's text content is the same JSON the REST endpoint returns, with
billed: falseand without the HTTP usage and idempotency headers. - A decline (
computed: false) is a normal successful result, not an error. The assistant should explain it, not retry it. - An invalid profile returns
isError: truewitherror: "invalid_request"and avalidationlist of{ path, code }(withmessageon acustomissue), so the client can correct it.
Setup walkthrough
Step-by-step setup for Claude and ChatGPT is in Use from Claude or ChatGPT.