Using the API

Requests & authentication

Every compute call is an HTTPS POST of a JSON body with three headers. This page covers the rules all endpoints share.

Base URL

https://tax-mcp.com

All paths in these docs are relative to it, for example https://tax-mcp.com/api/mcp/tax-compute/federal. The one exception is document intake, which has its own host.

Headers

HeaderRequiredValue
AuthorizationYesBearer <your API key>. See Get an API key.
Content-TypeYesapplication/json
Idempotency-KeyRecommended; required on what-if and review-packetA unique value (a UUID) per logical request. Reuse it to retry that request without being billed twice. See Idempotency.

The request body

  • JSON, at most 64 KB. Larger bodies are rejected with 400.
  • Whole dollars.Send amounts as whole-dollar numbers. Where the engine's rounding can differ from a form rounded another way, tax-capabilities says so under not_modeled.cents_rounding.
  • Unknown fields are rejected. Schemas are strict, so a misspelled field returns 400 with an unrecognized_keys issue instead of being silently ignored. The response does not name the field, so check your body against the reference.
  • Required on every compute: year and filingStatus (one of single, married_filing_jointly, married_filing_separately, head_of_household), and canBeClaimedAsDependent (true when another taxpayer can claim the filer as a dependent; on the state endpoint CA, NY and IL decline true, and NC and MI compute it only for a single or married-filing-separately filer who claims no dependents). The state endpoint also needs state. A federal married_filing_separately return also needs spouseItemizesDeductions (yes, no or unknown).
  • Excluded foreign or territory income. noForeignOrTerritoryExclusionAffirmed is required on every compute: true attests that no one on the return (the filer, and on a joint return either spouse) files Form 2555 for the year or excludes income under §931 (Form 4563) or §933 (Puerto Rico). false declines (out_of_scope_income; on the state endpoint a CA, NY, IL, NC or MI return declines as federal_declined).
  • W-2 wages need box 5. When wages is positive, also send medicareWages (W-2 box 5). Box 5 can differ from box 1 by any amount (401(k) deferrals, for example), so without it the engine declines the Additional Medicare Tax determination.
A return with excluded foreign or territory income declines:
Request
curl https://tax-mcp.com/api/mcp/tax-compute/federal \
  -H "Authorization: Bearer $TAX_MCP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "year": 2025,
    "filingStatus": "single",
    "canBeClaimedAsDependent": false,
    "noForeignOrTerritoryExclusionAffirmed": false,
    "wages": 60000,
    "medicareWages": 60000
  }'
Response 200 · DECLINED · out_of_scope_income
{
  "computed": false,
  "code": "out_of_scope_income",
  "reason": "income excluded under §911, §931 or §933 is not modeled; noForeignOrTerritoryExclusionAffirmed:true attests: no one on the return (the filer, and on a joint return either spouse) files Form 2555 for the year or excludes income under §931 (Form 4563) or §933 (Puerto Rico)",
  "billed": true,
  "retry_safe": false,
  "next_action": "review_inputs"
}
Full response, including line derivations
{
  "computed": false,
  "code": "out_of_scope_income",
  "reason": "income excluded under §911, §931 or §933 is not modeled; noForeignOrTerritoryExclusionAffirmed:true attests: no one on the return (the filer, and on a joint return either spouse) files Form 2555 for the year or excludes income under §931 (Form 4563) or §933 (Puerto Rico)",
  "billed": true,
  "retry_safe": false,
  "next_action": "review_inputs"
}

Leaving a schedule out is a statement

For these fields, omitting the field says the schedule does not exist on the return; it does not mean $0. A schedule that exists and nets to zero must be sent as an explicit 0, because the affirmation checks for that schedule only run when it is present:

netShortTermCapGain, netLongTermCapGain, capGainAggregates, collectibles28Gain, sec1250UnrecapturedGain, priorYearCapLossCarryoverST, priorYearCapLossCarryoverLT, section1256NetGain, scheduleCIncome, scheduleEIncome.

The engine cannot catch this for you

An omitted field looks exactly like a schedule that does not exist. Map “schedule present with zero net” to 0 in your integration, and test that mapping.

Validation errors

A request that fails validation is never billed. The body lists each problem:

A misspelled filing status:
Request
curl https://tax-mcp.com/api/mcp/tax-compute/federal \
  -H "Authorization: Bearer $TAX_MCP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "year": 2025,
    "filingStatus": "single_filer",
    "canBeClaimedAsDependent": false,
    "noForeignOrTerritoryExclusionAffirmed": true,
    "wages": 50000
  }'
Response 400 · validation_failed
{
  "error": "validation failed",
  "issues": [
    {
      "path": ["filingStatus"],
      "code": "invalid_value"
    }
  ],
  "billed": false,
  "retry_safe": false,
  "next_action": "fix_request_and_resubmit",
  "reason": "validation_failed"
}

Affirmations

Some facts cannot be checked from numbers alone: whether a Schedule C amount is one sole proprietor's final net, whether investment income came with an estate or trust K-1, and so on. For those, the engine asks for an affirmation: a boolean field the preparer sets to true to attest to the fact. Leaving it out, or sending false, declines that path, and the reason names the field. Examples: estateTrustK1NoAmtAdjustmentAffirmed, scheduleCIsSingleSolePropFinalNetAffirmed, stateIncomeConformsToFederal. The full list is in the capability manifest; see Declines & affirmations.

Only affirm what someone has checked

An affirmation moves responsibility for that fact to the person who set it. Never default one to true to make a decline go away.

Discover fields before you call

  • GET /api/mcp/tax-capabilities: the whole supported envelope. No key, no cost.
  • GET on /federal, /state, or /reconcile: that endpoint's years and common fields (illustrative, not exhaustive). Needs a key, uses no quota.
  • /api/openapi.json: the OpenAPI 3.1 spec. The API referencelists every field the API accepts, with the spec's description where it has one.

See also: Reference overview.

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.

Special federal taxes & safe-decline mechanics
CapabilityStatus
Whole-dollar rounding at the form boundaryRounds amounts to whole dollars at form lines; not_modeled.cents_rounding in tax-capabilities says where that differs.✅ shipped & certified