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

ToolInputDescription
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: false and 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: true with error: "invalid_request" and a validation list of { path, code } (with message on a custom issue), so the client can correct it.

Setup walkthrough

Step-by-step setup for Claude and ChatGPT is in Use from Claude or ChatGPT.