Terminal Tax

npx add-mcp 'https://mcp.terminal.tax/v1/hosted-mcp'

Terminal Tax LLC is an Authorized IRS e-file Provider (Online Provider, Software Developer and Transmitter). Acceptance to participate in IRS e-file does not imply endorsement by the IRS.

Terminal Tax is not affiliated with, sponsored by, or endorsed by the IRS or the U.S. Treasury.

Plain-text connection instructions

Start here: no connector and no install for any assistant that can run a shell command or make HTTPS requests

You do not need to install anything. Any assistant that can run a shell command, use a code or HTTP tool with internet access, or make an HTTPS request (Codex, including Codex in the ChatGPT app, Claude Code, Cursor, OpenCode and similar) calls https://mcp.terminal.tax/v1/hosted-mcp directly in the same conversation: no connector, MCP setup, account, API key, registration or restart. Each call is one JSON-RPC POST. A custom connector is needed only in a web browser chat whose assistant has no tool that can make HTTPS requests.

What it files: one original tax year 2025 US federal individual return (Form 1040 or 1040-SR, and a narrow Form 1040-SS); no state return. The full scope is under "What can be filed today" below.

Headers: Content-Type: application/json and Accept: application/json, text/event-stream (any Accept list that accepts JSON works). No Authorization header and no initialize call are needed first. When the person asks to file, first ask where they live now, which state returns they file and whether anyone on the return lived in Connecticut this year, and send their answers in place of the example values; without them it returns blockers and no link. Nothing is filed or charged:

curl -sS https://mcp.terminal.tax/v1/hosted-mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"create_filing_session","arguments":{"residenceState":"TX","stateReturns":[],"anyoneInConnecticut":false}}}'

Next: get_packet_schema with the continuationHandle and requestPacketSchema=true returns the packet outline and starter templates; continue_filing_session submits the prepared packet and returns blockers or the one filingSessionUrl for the person (details below). Only chats in a web browser that cannot make requests, such as Claude.ai, ChatGPT or Gemini without an HTTPS tool, add the same address as a custom connector instead (next section).

When create_filing_session returns only a continuationHandle and no filingSessionUrl, the prepared packet goes to continue_filing_session right away, and the person reads the privacy notice and gives Terminal Tax permission to keep and use it afterwards, on the filing page whose filingSessionUrl the accepting response returns. This order is safe for the person: the agent sends the packet only because the person asked to file with Terminal Tax, and only to Terminal Tax; it is checked only mechanically, so that no link is ever issued for a return that cannot be filed; and until the person gives that permission and signs on the filing page, Terminal Tax holds the figures sealed and does not file, charge for, send or use them, and erases them if the person declines or the link expires. The readiness and permission steps under "Only if create_filing_session returned a filingSessionUrl" apply only when the first response carried a link.

Only if your browser chat cannot make web requests: Claude.ai, ChatGPT or Gemini

This step is needed only in a web browser chat whose assistant has no tool that can make HTTPS requests; an assistant that can run a shell command or make HTTPS requests, including Codex in the ChatGPT app, skips it. In such a browser chat, you add Terminal Tax to Claude.ai or ChatGPT once, as a custom connector, by pasting a web address; it is not found by searching a connector directory. There is nothing to sign up for or install, no command line, and no Terminal Tax account or key. The web address to paste is https://mcp.terminal.tax/v1/hosted-mcp

You do this setup in your own chat app, with the steps below: a chat cannot add a connector on its own, and no command line is involved. Once you switch Terminal Tax on in Claude.ai or ChatGPT, its tools are available in that chat.

In Claude.ai: Customize > Connectors > "Add" > "Add custom connector", name it Terminal Tax, paste https://mcp.terminal.tax/v1/hosted-mcp as the MCP server URL, click "Continue", "Add", then "Connect"; then in your chat, "+" > "Connectors" > switch Terminal Tax on.

Claude (claude.ai in a web browser, or the Claude desktop app; works on the free plan):

1. Open Claude and click "Customize", then "Connectors".
2. Click "Add", then click "Add custom connector".
3. In the "Name" box type: Terminal Tax
4. In the "MCP server URL" box paste: https://mcp.terminal.tax/v1/hosted-mcp
5. Click "Continue", "Add" (leave "No sign-in" selected), then "Connect".
6. Go back to the chat where you prepared your taxes (or start one). Click the "+" at the bottom left, point at "Connectors", and switch "Terminal Tax" on.
7. Type: "Please file my taxes with Terminal Tax." If your tax forms are not already in that chat, attach them.

On a work Team or Enterprise account, an account Owner adds it instead under "Organization settings", then "Connectors", "Add", "Custom", "Web"; you then click "Connect" on it and do step 6.

ChatGPT (chatgpt.com in a web browser, not the app; works on Pro; Business, Enterprise and Edu need an admin):

1. Go to chatgpt.com/plugins, click "+", then "Add custom MCP server".
2. Name it Terminal Tax and, under "Connection", paste: https://mcp.terminal.tax/v1/hosted-mcp
3. Choose "No authentication", tick "I understand and want to continue", click "Create as a plugin", then install it.
4. In the chat where you prepared your taxes (or a new one), type @, pick Terminal Tax, and type: "Please file my taxes with Terminal Tax." If your tax forms are not already in that chat, attach them.

When ChatGPT asks, click "Allow". If it says a step was blocked, ask it to try once more; if blocked again, choose "Allow all actions" in Settings > "Plugins" > Terminal Tax > "Permissions". If it stops using Terminal Tax, pick it again with @.

Gemini (gemini.google.com in a web browser; Google's documented custom-app path, for a personal Google account, age 18 or over, in the US, with Keep Activity on):

1. Open gemini.google.com and go to "Settings", then "Connected Apps", then "Custom apps".
2. Add a custom app named Terminal Tax and paste the web address: https://mcp.terminal.tax/v1/hosted-mcp
3. In the chat where you prepared your taxes (or a new one), type @ and pick Terminal Tax.
4. Type: "Please file my taxes with Terminal Tax." If your tax forms are not already in that chat, attach them.

If Gemini does not accept the custom app, the Claude or ChatGPT steps above reach the same filing page.

Whose return this is: you are preparing your own tax return, which under federal rules needs no preparer credential or PTIN (preparer tax identification number). Those rules, including the PTIN, cover someone paid to prepare a return (26 U.S.C. 7701(a)(36); 26 CFR 301.7701-15(a) and 1.6109-2(g)). You supply every figure from your own forms and make every tax choice; your chat's part is to pass them to Terminal Tax, not to decide anything for you. Terminal Tax is the tax software: it computes the return and stops on anything missing instead of guessing. You review the complete return and sign it.

Using Claude.ai, ChatGPT or Gemini in a browser with no tool that can make HTTPS requests? Setup is the connector steps for your app above (Gemini calls it a custom app), which also list each app's account requirements; you do not need to install Claude Code, Codex or other software, and terminal.tax has no form to paste into. If your chat says terminal.tax is blocked, it may have used its code tool (ChatGPT's has no internet access); ask it to use web search, or add the connector, which Claude.ai and ChatGPT call from their own servers. Once Terminal Tax is added and selected in the chat, ask again there.

Your chat sends your return and the details you give it; on the filing page you confirm them, type your Social Security number, a one-time code and your PINs, and sign.

The connector is the same hosted endpoint described below (Streamable HTTP, no authentication). Agents that can make HTTPS requests skip this step and call it directly, as the first section shows.

Connecting

Terminal Tax is tax software for the US federal individual income tax return. The person gives the facts from their tax forms and makes every choice through their own AI agent; Terminal Tax computes the return deterministically and validates it mechanically. The person reviews the complete return, enters their identity details and signs on one hosted filing page; Terminal Tax then e-files it. It does not choose tax treatments or give tax advice.

Using Terminal Tax through an AI assistant is not the assistant filing on the person's behalf: the assistant sends the tax figures and details the person gives it, and the person reviews the complete return, confirms those details, types their Social Security number and PINs, signs and authorizes payment on the filing page before Terminal Tax e-files it. Assistants that run commands (Claude Code, Codex and similar) need no connector: they reach the same service over plain HTTPS, as the developer guide at https://terminal.tax/llms.txt shows.

Any agent with a shell or an HTTP tool, including Claude Code, Codex, OpenCode and other coding agents, can connect now with curl, with no connector and no MCP support. Each call is a plain HTTPS JSON-RPC POST to https://mcp.terminal.tax/v1/hosted-mcp, answered in the same conversation. Nothing is installed, configured, registered or restarted first; registering it as an MCP server is optional.

What leaves the chat, and when: the first call carries no tax data, only three answers that choose the order: the state the person lives in, the state returns the filing carries, and whether anyone on the return lives in Connecticut or lived there this year. If create_filing_session returns no filingSessionUrl (packet first), the agent submits the prepared packet with continue_filing_session without waiting for any permission: tax figures, such as wages, withholding and filing choices, are checked before any link exists, the one link comes back in the response that accepts them, and they are held sealed until the person gives permission on the page, or erased if the person declines. Only if create_filing_session returns a filingSessionUrl (link first: a Connecticut filer, whose return Connecticut's privacy law lets Terminal Tax process only after the person's permission) the figures attach only after the person opens that page and gives permission there. Identity details the person gives the agent (name, date of birth, address, contact, bank account, prior-year AGI) go only in the packet's separate agentIdentity section, sealed beside the return, and the person confirms each on the filing page; SSNs, ITINs, IP PINs, signing and prior-year PINs and one-time codes are typed by the person there, and a packet containing them is refused.

Why the agent's calls need no key: they can only submit one filing's packet and read its status. Identity checks, signature, payment and sending to the IRS happen only on the filing page, done by the person.

Who does the tax work: the person supplies every fact from their own forms and makes every choice; the agent copies them into the packet. Terminal Tax computes the return, refuses anything missing or unsupported instead of guessing, and shows the person the complete official return to review before they sign.

When the person asks to file, the first section's call returns a continuationHandle for the agent, and a filingSessionUrl for the person only where the endpoint issues the link before the packet; no tax facts are sent yet.

The person, not the agent, is identified and signs, on the filing page: a one-time code sent to their own email or mobile number, their name, date of birth and address (typed there, or confirmed there where their agent sent them), their SSN or ITIN, their IRS Identity Protection PIN when one was issued, a Self-Select PIN signature authenticated with their prior-year AGI or prior-year PIN, card authorization in Stripe's hosted fields, and review of the official return before signing. This guide is descriptive and contains no instruction for an agent to act on a person's files or information without that person, and nothing is sent to the IRS unless the person completes those steps on the filing page.

The full reference below covers the operator, what can be filed, price, the privacy boundary, the four tools, how a filing proceeds and host-specific setup.

Operator

Terminal Tax is operated by Terminal Tax LLC, a New Jersey limited liability company.

Legal and privacy contact: legal@terminal.tax. Support: support@terminal.tax.

How to check that status: Terminal Tax LLC has opted in to the IRS e-file provider locator for tax professionals on irs.gov, where it can be confirmed once the IRS's next listing refresh includes it. IRS Publication 3112 requires every provider to protect its EFIN and ETIN and never share them, so no provider publishes those numbers. Who operates this site can be checked independently: the terminal.tax Extended Validation certificate is issued by Sectigo to TERMINAL TAX LLC, New Jersey, registration number 0451501195.

More about the operator: https://terminal.tax/about

What can be filed today

One original tax year 2025 US federal individual income tax return: Form 1040 or Form 1040-SR, or a tax year 2025 Form 1040-SS for a single bona fide resident of Puerto Rico with no Form 1040 filing requirement who owes self-employment tax on Schedule C business profit (net self-employment earnings of $400 or more), with no other income, credits, wages, estimated tax, or farm, partnership or church self-employment income. No state, territory or local return is filed, and a federal filing does not satisfy a separate state or local obligation. Amended returns (Form 1040-X), extensions (Form 4868), Form 1040-NR and every other Form 1040-SS situation are not available through this service.

Situations the service accepts when every required fact is supplied include: W-2 wages from one or more employers, including the foreign earned income and foreign housing exclusions on wages earned abroad (Form 2555); interest (1099-INT) and dividends (1099-DIV), with Schedule B Parts I and II when required, including nominee, accrued-interest, OID and bond-premium interest adjustments (dividend adjustments and the savings-bond exclusion are not yet supported); foreign tax paid on dividends, taken as the foreign tax credit (with Form 1116 when it is required); some brokerage and digital-asset sales (1099-B, 1099-DA); unemployment compensation (1099-G); pensions and IRA distributions (1099-R), with the additional taxes on early distributions and on excess contributions to IRAs and other tax-favored accounts (Form 5329), and nondeductible IRA contributions, IRA basis, Roth conversions and Roth IRA distributions, including partial rollovers and qualified charitable distributions beside basis (Form 8606), figured from the facts the taxpayer's agent supplies; Social Security benefits (SSA-1099); gambling winnings (W-2G); rental real estate and royalty income (Schedule E), including a rental loss or a prior-year unallowed loss limited by Form 8582 with each property its own activity, and depreciation of rental property placed in service in 2025 and rental vehicle expenses, each rental with its own Form 4562; some partnership and S-corporation Schedule K-1 income; self-employment income from up to five sole proprietorships, each owned by the primary taxpayer or, on a joint return, by the spouse, reported on Schedule C with Schedule SE (Form 1099-NEC nonemployee compensation included), with the self-employed health insurance deduction (Form 7206) and contributions to a SEP, SIMPLE IRA or solo 401(k); head of household filing status; some health savings account distributions and contributions (Forms 1099-SA and 5498-SA, with Form 8889), and Archer MSA and Medicare Advantage MSA distributions (Form 1099-SA box 3 code 1 or 3, with Form 8853 Section A Part II or Section B, filingChoices.form8853) in a year with no Archer MSA contribution; wages above the Additional Medicare Tax threshold (Form 8959); educator expenses; the residential clean energy credit (Form 5695 Part I); the clean vehicle credit (Form 8936) for one new vehicle for personal use, acquired before October 1, 2025 and placed in service in 2025; the Lifetime Learning Credit (Form 8863); the refueling property credit (Form 8911) for one personal-use property at the main home; household employment taxes on Schedule H Part I (Social Security and Medicare taxes on a household employee's cash wages paid by the primary taxpayer, with no federal unemployment tax); unreported tips (Form 4137), including tips that bring Medicare wages above the Additional Medicare Tax threshold (Form 8959); Form 1099-NEC compensation the taxpayer reports as wages from a firm that treated them as a contractor, with the employee share of Social Security and Medicare tax (Form 8919); dependents, with the Child Tax Credit, Additional Child Tax Credit and Credit for Other Dependents (Schedule 8812) and the Earned Income Credit (Schedule EIC), each claimed at the amount the taxpayer's agent figures (the taxpayer types each dependent's name and identification number on the filing page); the child and dependent care credit (Form 2441) when every person cared for was under 13; Form 8862 when one of these credits or the American Opportunity Credit is claimed again after the IRS disallowed it in an earlier year; the return of a taxpayer who died: a joint return whose spouse died, signed by the surviving spouse alone (whichever spouse is listed first; filingChoices.jointReturnSignerFacts.primaryTaxpayerDied when it is the spouse who died), and the single, head of household or married filing separately return of a taxpayer who died, filed and signed by their personal representative (filingChoices.decedentReturnSignerFacts), including a refund the representative claims on Form 1310 when no court has appointed or will appoint a personal representative and the representative will pay the refund out under the law of the state where the decedent lived (filingChoices.form1310) (the person signing types the date of death on the filing page, the representative their own name, and a Form 1310 claimant their own Social Security number); a married-filing-separately return with a home in a community property state (Arizona, California, Idaho, Louisiana, Nevada, New Mexico, Texas, Washington or Wisconsin) whose income is wages, taxable interest, ordinary dividends and fully taxable pensions, with Form 8958 allocating each Form W-2, 1099-INT, 1099-DIV and pension Form 1099-R of both spouses as community or one spouse's separate income (filingChoices.communityPropertyAllocation; Terminal Tax splits community items and wage withholding in half, Publication 555), plus the filer's own IRA distributions and social security benefits, which are wholly the filer's; the 2025 Schedule 1-A deductions (qualified tips, qualified overtime compensation, car-loan interest and the enhanced deduction for seniors); the standard deduction or itemized deductions; student-loan interest; the qualified business income deduction (Form 8995, or Form 8995-A with its Schedule A above the taxable-income threshold for one sole proprietorship and each partnership or S corporation trade whose Schedule K-1 statement shows only box 1 as qualified business income, from the specified-service status, W-2 wages and qualified property basis the taxpayer's agent states); the American Opportunity Credit (Form 8863), claimed at the amounts the taxpayer's agent figures; the Saver's Credit (Form 8880); the premium tax credit and any repayment of excess advance payments for Marketplace coverage (Form 8962), except the alternative calculation for the year of marriage; the Net Investment Income Tax (Form 8960), including beside a partnership or S corporation Schedule K-1; tax on a child's investment income (Form 8615); estimated tax payments; and a refund by direct deposit or paper check, or a balance due, which may be paid by electronic funds withdrawal, with an installment agreement request (Form 9465) when the person asks for one.

Self-employment: up to five Schedule C sole proprietorships, each of the primary taxpayer or, on a joint return, of the spouse, with Schedule SE computed from them; Form 1099-NEC nonemployee compensation reported as a business's income is part of its gross receipts. Accepted with them: cost of goods sold (Part III), car and truck expenses with the Part IV vehicle, other expenses with their Part V rows, some depreciation and section 179 expense computed from Form 4562 facts, business use of the home by the simplified method or computed from Form 8829 facts, and a net loss when the owner materially participated and all the investment is at risk. Also accepted, each tied to the business it is attributable to: the self-employed health insurance deduction (Form 7206), one health plan per self-employed person, and contributions to one SEP, SIMPLE IRA or solo 401(k) per self-employed person, figured on the Publication 560 worksheet from the plan facts the person's agent supplies. Deductible meals (line 24b) are accepted only as the amount after the business-meal limit (generally 50 percent), stated as such. The service does not accept depletion (line 12), employee benefit programs (line 14) or the energy efficient commercial buildings deduction (line 27a) on Schedule C, a Schedule C with zero profit, or a loss without material participation or with investment not at risk (Form 6198); with more than one business, a section 179 election in more than one of them, statutory-employee income, the Form 4361 exemption, Schedule C qualified tips, or a Schedule F or Form 4835 beside them; or the self-employed health insurance or retirement deduction beside the plan owner's own Schedule F, a partnership or S corporation Schedule K-1, or a statutory-employee, Form 4361 or optional-method business; health insurance through an S corporation the person owns more than 2 percent of, or on a return that also figures Marketplace coverage credits (Publication 974's iterative calculation); or a second health plan or retirement plan for one person; a return that needs any of these cannot be filed here.

Farming: one cash-method farm on Schedule F, of the primary taxpayer or, on a joint return, of the spouse, with a profit or, when the person materially participated and all of the investment is at risk, a loss that does not create a net operating loss, with Schedule SE computed from it (the farm optional method included, on one Schedule SE with the same person's Schedule C) and any Form 1099-NEC farm income on the Schedule F line the person's agent names; its expenses may include conservation expenses under an approved plan (up to a quarter of gross farm income), depreciation on property placed in service before 2025 when no Form 4562 is needed, employee benefit programs, interest (when the agent states section 163(j) does not limit it), labor hired, employees' pension plans, rent, and other expenses the agent describes; and one profitable farm rental on Form 4835, carried to Schedule E. Either takes the qualified business income deduction (Form 8995) when the person's agent says all of its profit is qualified business income, a farm rental only as a trade or business. The service does not accept a farm loss without material participation or with investment not at risk, a farm rental loss, zero profit, the accrual method, deferring crop insurance proceeds to 2026, Commodity Credit Corporation loans reported as income, Form 4835 income other than rents, Schedule F car and truck expenses, depreciation that needs Form 4562 (2025 property, section 179, listed property), preproductive period expenses, a Form 4835 owner who received an applicable subsidy, or a farm's section 199A deduction when the farm received cooperative distributions or taxable income is above the simplified-form limit.

Refused today: an Earned Income Credit that needs a disability answer for a child or a child born and died without an SSN; a Form 8862 that lists a child born or died in 2025; a dependent care credit for anyone 13 or older; cancelled debt on a Form 1099-C, with or without the Form 982 exclusions; a railroad retirement pension on a Form RRB-1099-R; a Form 1098-T sent as a source form (an education credit is claimed without one); a refund claimed for a taxpayer who died when a court has appointed, or will appoint, a personal representative; a joint return whose two spouses both died; a community property married-filing-separately return without that allocation, or with other income, a partly taxable or early pension, withholding on a community pension, interest or dividends over $1,500, itemized deductions or credits beside that allocation, spouses who lived apart all year, a nonresident alien spouse, or a year the marriage or community domicile began or ended; and on a rental, a section 179 deduction, a depreciated vehicle or amortization beginning in 2025.

Three facts must be stated explicitly for the filer rather than left blank: whether they are blind, whether they are 65 or older, and that no one can claim them as a dependent. A blank is not treated as no.

The packet schema served by get_packet_schema (the outline from requestPacketSchema=true and the sections it names) is the complete list of accepted facts, and any refused field comes back as a named blocker. The facts come from the person's actual Forms W-2, 1099 and other statements; the service does not take custody of those documents.

Price

Price: $19.99 per federal return. The filing page shows the itemized price before any card entry. Card details are entered only in Stripe's hosted fields and never reach Terminal Tax or the agent; the card is authorized before transmission and charged only if the IRS accepts the return.

Privacy boundary

The service refuses taxpayer identification numbers and authentication values from an agent (every SSN or ITIN, the IP PIN, the Self-Select PIN, the prior-year PIN, the filing page's one-time code, driver's license or state ID values); the taxpayer types these protected values on the filing page. The taxpayer's own identity details are accepted from an agent in the packet's agentIdentity section, sealed beside the return and kept apart from it: legal name, date of birth, mailing address, occupation, dependents' names, email and mobile number, the refund or payment bank account, whether they filed a federal return last year and ever, and prior-year adjusted gross income. The section is required: a packet that lacks any required item is refused with one blocker per missing item, naming its path and the question for the taxpayer, and no filing link is issued until none is left. The filing page shows each value for the taxpayer to confirm or correct; no tool returns any of them. A packet that contains these protected values is refused. Source-form identifiers are separate and are sent in the packet: employer EINs, payer and lender EINs, K-1 partnership or corporation EINs, household-employer EINs and 5498-SA trustee EINs are fields of the forms they belong to, and the packet schema marks the ones each form requires, such as a W-2's employer EIN from box b. They appear in return review and the filing page does not ask the taxpayer to enter them, so a packet that omits a required one is returned with a blocker naming the field. SSN-shaped payer or lender numbers and an SSN-typed W-2G payer number remain refused. The taxpayer's signing PIN is the taxpayer's own signature, so the service does not receive it from an agent.

The return in the agent's packet carries only tax facts and filing choices. The agent can show the person a plain summary of the figures it prepared, such as wages and withholding from the person's own forms, so the person can check them before opening the filing page; that summary contains no identity values. Terminal Tax returns no computed figure (deduction, taxable income, tax, refund or amount owed) to the agent. The official return is rendered on the filing page for review before signing, so the agent does not build or present a Form 1040 or a substitute PDF.

The filing page is served only on an approved network to the person's own browser session, so an agent's fetch of that URL can return 404 while the page works; the agent follows progress through get_filing_status, or readiness polling where the link comes first.

Hosted endpoint and tools

Remote MCP: https://mcp.terminal.tax/v1/hosted-mcp

This Streamable HTTP MCP endpoint supports initialization, tool discovery and empty reservation creation with no account, API key, OAuth approval or browser step. A browser GET can return 405, because MCP messages are POST requests. Return intake requires the scoped continuationHandle and the person's own permission on the filing page.

create_filing_session takes no tax data. Where the endpoint collects the packet first it takes three answers asked before any tax fact: residenceState (the state the person lives in now), stateReturns (the state returns the filing carries, [] for federal only) and anyoneInConnecticut (whether the person, a spouse or a dependent on the return lives in Connecticut or lived there this year); where the link comes first it optionally takes the person's email, used only to email the filing page's verification code. It returns a continuationHandle for the agent. Where the packet comes first it returns nothing else, and a call missing any of the three answers returns blockers and no link, so the agent asks the person and calls again; a Connecticut filer takes the link-first order there too: then, as wherever the link comes first, it creates an empty, unsigned, unpaid reservation and also returns a filingSessionUrl for the person.

get_packet_schema uses the continuationHandle. With requestPacketSchema=true it returns the packet schema's digest, an outline whose larger parts are named sections, and the starter-template list; packetSchemaSection and packetStarterTemplate return one section or one template at a time, so each response is sized to fit common tool-result limits. It is read-only: no tax facts are sent and no return is written.

continue_filing_session uses the continuationHandle. With completedReturnPacketJson and packetSchemaSha256 it submits the prepared return: where the packet comes first, blockers come back with no link and an accepted packet's response carries the one filingSessionUrl; where the link came first, it attaches once readiness is ready, and get_filing_status with requestReadiness=true reports whether the person has completed the privacy acknowledgment and separate tax-data permission on the filing page.

get_filing_status uses the continuationHandle and returns a model-safe result for the filing. It does not return return content, identity, payment data or raw IRS rejection text.

The continuationHandle works only for its own short-lived reservation. It cannot read stored returns, establish identity, pay, sign or transmit, and it is not meant for URLs, logs or messages to the person.

Direct HTTPS from an agent's existing tools

No restart is needed. Direct HTTPS JSON-RPC requests work in the same conversation, right away, from any shell, curl, Python or HTTP tool. Registering the MCP server is optional and only makes the tools native in later sessions. The person does not need to quit, restart, repeat their tax interview, or open a new conversation.

Any shell, curl, Python, JavaScript or other outbound HTTPS tool can call the endpoint without OAuth, a local service, a package install or a second agent. This transport does not bypass the person's own permission or destination controls. Requests start without an Authorization header; existing OAuth clients remain a compatibility path, not a setup step.

Each JSON-RPC message is an HTTP POST with Content-Type: application/json and Accept: application/json, text/event-stream. A response is either JSON or SSE data events; an SSE envelope is not itself the tool result.

A bare tools/call is accepted, as in the example above. A full MCP client sends initialize with a supported protocol version and client capabilities, then notifications/initialized, tools/list and tools/call with the returned schemas; later requests carry the negotiated version in MCP-Protocol-Version, and Mcp-Session-Id when initialization returns one. A connection or a successful draft is not an IRS acceptance.

MCP transport reference: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports

curl --fail-with-body -sS 'https://mcp.terminal.tax/v1/hosted-mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"filing-agent","version":"1"}}}'

How a filing proceeds

The tool descriptions and the returned schema are the authoritative contract for the current session.

Which order applies is visible in the first response. Packet first, when create_filing_session returns only a continuationHandle: the agent fetches the schema, prepares the packet and submits it with continue_filing_session right away, with no permission or readiness step before it; every blocker comes back with no link, and the response that accepts the packet is the only one carrying the filingSessionUrl. The person then opens the page once, reads the privacy notice, gives the separate permission, and finishes on that page with nothing further from the agent; declining or expiry erases the held packet. Link first, when create_filing_session also returns a filingSessionUrl: the steps in the next section apply, and only then.

The filingSessionUrl reaches the person intact when it is printed as bare text on its own line, exactly as returned, rather than as a markdown link: rewriting a long URL as link text can shorten or cut its token, and a shortened URL does not open the filing page.

A tool result with status unavailable or a root-level blocker means that attempt has ended, and repeating the same call returns the same result; a fresh reservation starts a new attempt. The exception is rate_limited, whose retryAfterSeconds says when the same call is accepted again. A blocker that names a packet field path is mechanical, carries a plain detail, and is resolved from facts the person already supplied; a refused packet writes nothing and is corrected and resubmitted with the same continuationHandle. Pending readiness means the person is still on the filing page.

Only if create_filing_session returned a filingSessionUrl (link first)

These steps apply only when the first create_filing_session response carried a filingSessionUrl. When it returned only a continuationHandle, none of them applies: the packet goes to continue_filing_session as soon as it is prepared.

1. The person asks to file. create_filing_session returns the filingSessionUrl and continuationHandle; no tax facts are sent at this point.
2. get_packet_schema with requestPacketSchema=true returns the schema's digest and an outline naming its sections, so the agent fetches only the sections the person's facts need and can collect every required fact in one pass, and packetStarterTemplates: complete example packets for common W-2, 1099-INT and 1099-DIV shapes whose REPLACE_WITH_TAXPAYER_VALUE placeholders are refused until replaced and whose preset answers each come with a question for the person. The agent prepares the packet in its own context from the person's explicit facts and treatments; the service does not infer a missing answer or substitute a tax year, and the person has no JSON to copy or edit.
3. When the packet is prepared, the person receives the one filingSessionUrl for final review, confirmation, signing and payment. The agent keeps working while they stay on that page; no return-to-chat command is required, and no OAuth page or provider login is involved.
4. get_filing_status with requestReadiness=true, a read that writes nothing, is polled at a bounded interval. Pending means the person has not finished the privacy acknowledgment and separate tax-data permission; ready means the service has verified both. Expiry, withdrawal or refusal ends the attempt.
5. After ready, continue_filing_session with completedReturnPacketJson and packetSchemaSha256 attaches the return; the tax year is return.taxYear inside the packet, not a tool argument. The server checks the person's permissions again before processing it, and the same filing page advances automatically. Every blocker the packet can be checked for arrives in one response with a plain detail, and a check that depends on a missing or refused answer runs once that answer is corrected; only a genuinely missing tax answer needs the person.
6. The person personally completes identity, possession, full review, any required consent, signature and payment steps on that same page. get_filing_status with continuationHandle reports the permitted model-safe result; completing review is not IRS acceptance.

Optional: attaching without a return to the chat

This applies only where the link comes first. Some people prefer not to come back to the chat after finishing the permissions on the filing page. For them, an agent with a shell can save the prepared packet as packet.json and run the loop below while the person is on the page. It checks readiness every 10 seconds for up to 30 minutes and, once the person has given both permissions, attaches the packet so the page advances on its own. Without it, the agent attaches the packet once readiness is ready, for example when the person returns to the chat. The loop uses only curl and python3; H is the continuationHandle and D the packetSchemaSha256.

U='https://mcp.terminal.tax/v1/hosted-mcp' H='<continuationHandle>' D='<packetSchemaSha256>'
for i in $(seq 180); do R=$(curl -s "$U" -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"get_filing_status\",\"arguments\":{\"continuationHandle\":\"$H\",\"requestReadiness\":true}}}"); case "$R" in *'"readiness":"ready"'*) python3 -c 'import json,sys;print(json.dumps({"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"continue_filing_session","arguments":{"continuationHandle":sys.argv[1],"completedReturnPacketJson":open(sys.argv[2]).read(),"packetSchemaSha256":sys.argv[3]}}}))' "$H" packet.json "$D" | curl -s "$U" -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' --data-binary @-; break;; *'"readiness":"pending"'*) sleep 10;; *) echo "$R"; break;; esac; done

Optional, not needed to file: registering in Codex CLI

The direct HTTPS calls above work in the current conversation, with nothing installed; registering only makes the tools native in later sessions. The installed host's MCP commands are codex mcp --help and codex mcp list. When the person has asked to connect, codex mcp add registers the URL in the current configuration scope and leaves existing configuration in place. No codex mcp login or OAuth popup is required, ChatGPT account settings are not a prerequisite for a Codex CLI connection, and no second model session is needed to acquire tools.

codex mcp add terminal-tax --url https://mcp.terminal.tax/v1/hosted-mcp
codex mcp list

1. A new connection verifies with initialize and tools/list and sends no Authorization header. No browser or legacy OAuth login flow is involved.
2. A configuration change does not by itself refresh a running conversation's tools; until they appear, the HTTPS JSON-RPC requests above reach the same four tools.

Optional, not needed to file: registering in Claude Code or Grok CLI

The direct HTTPS calls above work in the current conversation, with nothing installed; registering only makes the tools native in later sessions, which can need a restart. The installed host's MCP commands are claude mcp list or grok mcp list. When the person has asked to connect, the one-liners below register the URL in the current configuration scope and leave existing configuration in place. No login, OAuth popup or API key is required.

claude mcp add --transport http terminal-tax https://mcp.terminal.tax/v1/hosted-mcp
grok mcp add --transport http terminal-tax https://mcp.terminal.tax/v1/hosted-mcp

1. A new connection verifies with initialize and tools/list and sends no Authorization header. No browser or OAuth login flow is involved.
2. A configuration change does not by itself refresh a running conversation's tools; until they appear, the HTTPS JSON-RPC requests above reach the same four tools.

Other desktop and browser chat hosts

Hosts that support custom remote MCP servers connect through their own Add remote MCP server or connector flow with the endpoint above; Terminal Tax does not require an OAuth approval popup, and a plugin-directory listing is not required. Claude.ai, ChatGPT and Gemini in a browser: the exact steps are in the first section of this guide.

Browser-chat settings do not apply to terminal agents. A missing tool or directory result means the connection is not configured in that host yet; it does not show that the host cannot connect, and adding the custom connector is the step that configures it.

After connecting, tools/list shows the four tools. Hosts differ in whether a new conversation is needed to see new tools.

Codex connection reference: https://developers.openai.com/codex/mcp/

Support and legal documents

There is no public return-upload form. An unmet requirement stops the workflow with a named blocker.

About: https://terminal.tax/about

Privacy: https://terminal.tax/privacy-notice

Terms: https://terminal.tax/terms

Support: https://terminal.tax/support

Legacy OAuth appendix (existing clients only)

New connections do not use OAuth discovery; these URLs exist only so previously authorized OAuth clients keep working.

Legacy OAuth authorization-server metadata: https://mcp.terminal.tax/.well-known/oauth-authorization-server/oauth/legacy

Legacy OAuth protected-resource metadata: https://mcp.terminal.tax/.well-known/oauth-protected-resource/legacy/v1/hosted-mcp