Run the first safe call

Prerequisites

• API key in the header Authorization: Bearer <api_key>. Treat it like a password.
• Canonical host https://tax-mcp.com.
• Header Content-Type: application/json.
• Header Idempotency-Key on every billable POST.

Reference links: GET /api/mcp/tax-capabilities for the supported envelope, OpenAPI for request and response schema, roadmap feedback, changelog/release notes, support/contact, and terms.

1. Computed 200

curl https://tax-mcp.com/api/mcp/tax-compute/federal \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "year": 2025,
    "filingStatus": "single",
    "wages": 85000,
    "medicareWages": 85000,
    "federalWithholding": 9500
  }'

The same first safe call in TypeScript:

import crypto from "node:crypto";

const response = await fetch("https://tax-mcp.com/api/mcp/tax-compute/federal", {
  method: "POST",
  headers: {
    Authorization: "Bearer <api_key>",
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    year: 2025,
    filingStatus: "single",
    wages: 85000,
    medicareWages: 85000,
    federalWithholding: 9500,
  }),
});

const body = await response.json();
if (body.computed) {
  console.log(body.totalTax, body.next_action);
} else {
  console.log(body.code, body.reason, body.next_action);
}

A computed 200 on a metered customer plan is billable. Replay the same Idempotency-Key with the same body if a network retry is needed; do not mint a new key for an unknown result.

2. Deterministic decline 200

This request omits the required Schedule C affirmation. Tax MCP returns a successful safety answer:computed:false, a code, a reason, billed, retry_safe, and next_action. It does not leak a tax value.

curl https://tax-mcp.com/api/mcp/tax-compute/federal \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "year": 2025,
    "filingStatus": "single",
    "wages": 80000,
    "scheduleCIncome": 20000
  }'

{
  "computed": false,
  "code": "schedule_c_needs_review",
  "reason": "Schedule C self-employment compute requires scheduleCIsSingleSolePropFinalNetAffirmed:true before Tax MCP can compute this bounded path.",
  "billed": true,
  "retry_safe": false,
  "next_action": "review_inputs"
}

3. needs_review 200

Reconcile can compute independently and still route the comparison to human review. Filed values are reconciliation oracles, not compute inputs.

curl https://tax-mcp.com/api/mcp/tax-compute/reconcile \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "sourceProfile": {
      "state": "ca",
      "year": 2025,
      "filingStatus": "single",
      "wages": 80000,
      "medicareWages": 80000,
      "caWithholding": 5000
    },
    "filed": {
      "stateAGI": "<caller-supplied filed value>"
    }
  }'

{
  "status": "needs_review",
  "computed": {
    "computed": true,
    "state": "ca",
    "year": 2025,
    "stateTaxableIncome": "<computed value elided>",
    "totalTax": "<computed value elided>"
  },
  "diff": [
    {
      "line": "CA AGI (540:17)",
      "engine": "<computed value elided>",
      "filed": "<filed value supplied by caller, elided>",
      "delta": "<difference elided>",
      "cls": "DIFFERS",
      "note": "source set appears incomplete vs the filed oracle; a human reviews"
    }
  ],
  "billed": true,
  "retry_safe": true,
  "next_action": "review_inputs",
  "provenance": {
    "engine": "deterministic",
    "jurisdiction": "ca",
    "tax_year": 2025
  }
}

4. Response states and recovery

Recovery is state-specific: fix request shape for validation errors, add required affirmations only when the capability manifest names them, route needs_review to a human, reuse the same idempotency key for safe replay, back off for rate limits, open support for persistent failures, or file roadmap feedback for unsupported workflows.

All examples together

Computed 200

{
  "computed": true,
  "year": 2025,
  "filingStatus": "single",
  "taxableIncome": 69250,
  "incomeTax": 10149,
  "totalTax": 10149,
  "billed": true,
  "retry_safe": true,
  "next_action": "none",
  "provenance": {
    "engine": "deterministic",
    "jurisdiction": "federal",
    "tax_year": 2025
  },
  "legal_notice": {
    "ref": "https://tax-mcp.com/terms#compute-notice",
    "version": "v1"
  }
}

Deterministic decline 200

{
  "computed": false,
  "code": "schedule_c_needs_review",
  "reason": "Schedule C self-employment compute requires scheduleCIsSingleSolePropFinalNetAffirmed:true before Tax MCP can compute this bounded path.",
  "billed": true,
  "retry_safe": false,
  "next_action": "review_inputs"
}

needs_review 200

{
  "status": "needs_review",
  "computed": {
    "computed": true,
    "state": "ca",
    "year": 2025,
    "stateTaxableIncome": "<computed value elided>",
    "totalTax": "<computed value elided>"
  },
  "diff": [
    {
      "line": "CA AGI (540:17)",
      "engine": "<computed value elided>",
      "filed": "<filed value supplied by caller, elided>",
      "delta": "<difference elided>",
      "cls": "DIFFERS",
      "note": "source set appears incomplete vs the filed oracle; a human reviews"
    }
  ],
  "billed": true,
  "retry_safe": true,
  "next_action": "review_inputs",
  "provenance": {
    "engine": "deterministic",
    "jurisdiction": "ca",
    "tax_year": 2025
  }
}

Validation error

{
  "error": "invalid_request",
  "billed": false,
  "retry_safe": false,
  "next_action": "fix_request_and_resubmit",
  "reason": "Correct the request body before resubmitting."
}