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.comAll 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
| Header | Required | Value |
|---|---|---|
| Authorization | Yes | Bearer <your API key>. See Get an API key. |
| Content-Type | Yes | application/json |
| Idempotency-Key | Recommended; required on what-if and review-packet | A 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
400with anunrecognized_keysissue instead of being silently ignored. The response does not name the field, so check your body against the reference. - Required on every compute:
yearandfilingStatus(one ofsingle,married_filing_jointly,married_filing_separately,head_of_household), andcanBeClaimedAsDependent(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 needsstate. A federalmarried_filing_separatelyreturn also needsspouseItemizesDeductions(yes,noorunknown). - Excluded foreign or territory income.
noForeignOrTerritoryExclusionAffirmedis required on every compute:trueattests 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).falsedeclines (out_of_scope_income; on the state endpoint a CA, NY, IL, NC or MI return declines asfederal_declined). - W-2 wages need box 5. When
wagesis positive, also sendmedicareWages(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.
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
}'{
"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:
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
}'{
"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.GETon/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.
| Capability | Status |
|---|---|
| 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 |