Discover the form and environment
Read the current return catalog and the form-input schema for the selected year. The builder expects the installed field names, choices and lexical formats. Use strings for money and scalar values where the schema requires them rather than guessing a JSON shape.
The read-only catalog request below requires an authorized preparation credential. Keep that credential in your server environment and out of frontend bundles.
curl --fail-with-body https://taxcomposer.com/v1/returns/catalog \
-H "Authorization: Bearer $TAXCOMPOSER_PREPARATION_KEY"Prepare and retain the returned reference
Use POST /v1/returns with the schema-derived form input and a stable Idempotency-Key. The hosted MCP equivalent is taxcomposer_return_prepare with input and idempotency_key. Include the selected workspace through its documented field or tool argument.
Retain the filing ID, revision and hash returned by the workflow. These identify the exact draft; a human-readable title is not a replacement for them.
Validate and review the findings
POST /v1/filings/{id}/workflow/validate reruns the installed checks. The hosted MCP tool is taxcomposer_return_validate. GET /v1/filings/{id}/workflow or taxcomposer_return_get retrieves the current resumable state.
Review both the validation findings and blockers. A valid schema result is not a declaration that every IRS business rule is cleared, and neither result means that the IRS accepted a return.
Keep simulation separate from real filing
When available and explicitly confirmed, the IRIS sandbox tool simulates the exact saved revision locally. It does not contact the IRS, sign, approve, charge, queue or mark the real return filed. Its SIM-prefixed receipt is a test artifact.
Production availability remains a separate gate, including the actual filing window and required IRS readiness. A bookkeeping app should display those blockers without substituting a scheduled date or success message.
Primary sources
Sources checked November 12, 2026. Use the instructions for your reporting year and circumstances.
Your next step
Connect your bookkeeping workflow.
Use the current API contract and discover the tools available to your MCP connection.
API Documentation →Connect with MCP →TaxComposer is production-ready for IRS IRIS e-filing. Prepare for free and pay $1 per form when you file.