Tax tools - Finta

After connecting Finta, your assistant can read tax filing progress, R&D credits, and tracked vendor 1099 records with three tools. Each tool supports both filtered discovery and exact ID retrieval.

Tool	Reads	Public ID prefix
`search_taxes`	Income and Delaware franchise filing progress and available PDFs	`tax_income_` or `tax_franchise_`
`search_tax_credits`	Federal R&D credit amounts, their source, and payroll submission status	`tcred_`
`search_1099s`	Tracked vendor filing records, annual summaries, and available W-9/1099 documents	`f1099_`

These tools require API access: Manage and Taxes: View in the connected company. OAuth finta:read is sufficient. Permissions are checked on each call, and a public ID cannot select a different company. All three tools are read-only. Try asking:

“Have we filed our 2025 taxes?”
“What is our 2025 R&D credit, and does payroll submission need action?”
“Which 2025 1099 records still need a W-9?”

Search or retrieve by ID

For discovery, omit id and pass filters, or pass an empty argument object to search all available records. Omit year to search all available years; there is no implicit current-year default. Filters combine with AND. The examples below show the tool name and arguments your MCP client sends. Your client handles OAuth and the MCP transport.

{
  "name": "search_taxes",
  "arguments": { "year": 2025, "status": "review_required", "limit": 25 }
}

{
  "name": "search_tax_credits",
  "arguments": { "year": 2025, "claim_status": "claimed" }
}

{
  "name": "search_1099s",
  "arguments": { "year": 2025, "filing_status": "w9_required,w9_requested" }
}

To retrieve a known record, pass its public id alone:

{
  "name": "search_1099s",
  "arguments": { "id": "f1099_Example123" }
}

An ID combined with any filter or pagination argument is a tool error. Numeric IDs from the webapp are not accepted; use the public ID returned by the tool.

Filters

Every tool accepts an exact four-digit year from 1000 through 9999, limit (1–500, default 100), and starting_after for pagination. The year is the tax year for filings/credits and the reporting year for 1099s, not submission year.

Tool	Additional filter	Values and behavior
`search_taxes`	`type`	`income` or `franchise`. Omit for both.
`search_taxes`	`jurisdiction`	`US` for federal, or a supported state code such as `US-CA` or `US-DE`. Matches a code in the record’s jurisdictions.
`search_taxes`	`status`	`onboarding`, `preparing`, `review_required`, `filing`, or `filed`; filters the returned `filing_status`.
`search_tax_credits`	`type`	Currently only `research_and_development`.
`search_tax_credits`	`claim_status`	`undecided`, `not_claimed`, `pending`, or `claimed`; concerns the income-tax claim.
`search_1099s`	`filing_status`	One or comma-separated stages: `review_required`, `w9_required`, `w9_requested`, `ready_to_file`, `filing`, `filed`, `not_required`. Multiple stages combine with OR.
`search_1099s`	`pending`	Boolean. `true` selects `w9_required`, `w9_requested`, `ready_to_file`, and `filing`. `false` selects the other stages, including `review_required` and `not_required`. Omit for both.
`search_1099s`	`vendor_name`	Case-insensitive exact display-name match, ignoring surrounding whitespace. No substring search; names can repeat.
`search_1099s`	`filed_elsewhere`	Boolean. `true` selects filed records completed outside Finta. `false` selects all other records, including pending ones. Omit for both.

Use JSON booleans (true or false), rather than strings. Passing false applies the filter; it is different from omitting the argument.

Results and pagination

Successful calls include the same JSON in structuredContent and a text content block, with isError: false. Both search and ID retrieval return data, has_more, and next_cursor in a list envelope. An ID lookup returns one record, has_more: false, and next_cursor: null. A missing or inaccessible ID is an error, not an empty successful result. If has_more is true, repeat the same tool and filters, adding the returned next_cursor unchanged as starting_after. Never use a record ID as a cursor. Pagination is live, so records can change between pages. For an invalid or stale cursor, start a fresh search with the desired filters. Illustrative exact-ID structuredContent, with synthetic IDs and timestamps:

{
  "object": "list",
  "url": "/api/v1/forms/1099",
  "data": [
    {
      "id": "f1099_Example123",
      "object": "form_1099",
      "year": 2025,
      "vendor_name": "Example Consulting",
      "filing_status": "w9_requested",
      "filed_at": null,
      "filed_elsewhere": false,
      "documents": [],
      "created": 1769000000,
      "updated": 1769100000
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "summaries": []
}

Annual 1099 summaries

Only search_1099s includes summaries. Filter searches return complete annual reports selected by year, independent of other filters or pagination. For example, pending: true restricts data to pending records, while summaries still counts the year’s filed records too. Summaries repeat on each page; never add their counts across pages. Required equals pending plus filed; review-required records are counted separately. ID retrieval returns summaries: [] because no annual summary was requested. It does not establish zero annual counts. Search by year to get the summary. An absent report is unknown; an existing report with no required or unconfirmed records is not_required. These describe tracked records, not legal obligations. Counts describe filing records, not unique recipients; do not merge records by vendor name. The 1099 guide defines the record and annual-summary stages.

Interpret progress and amounts

search_taxes reads the recorded filing workflow. One income record shares a filing status across federal and recorded state jurisdictions. Preserve any unmapped_jurisdictions; recognized codes may not cover every recorded state. filed means workflow completion is recorded, without establishing authority acceptance or payment. Read filing_status even when no PDF is available. See the filing guide for status definitions. search_tax_credits returns integer USD cents. Divide by 100 for dollars, and keep null as unknown rather than converting it to zero. State amount_basis when reporting a credit: estimate, prepared_return, filed_return, or null when unknown. claimed describes a positive credit recorded in the filed income-tax return; payroll_submission.status separately describes payroll submission recorded in Finta. submitted does not establish provider acceptance, and payroll allocation is not a refund received. The credit guide defines the amounts, claim stages, and payroll stages. Available tax PDFs and W-9/1099 document links expire after five minutes. Retrieve the record again with id alone to refresh them. Keep signed links private. An empty collection does not establish that a company has no tax obligations. Treat future unknown status values as unrecognized rather than complete.

Errors and limits

A business failure returns isError: true with text content in the MCP result, even when the transport returns HTTP 200. API error codes and parameters appear in that text. They are not a REST error object in structuredContent.

Error	What to do
ID combined with other arguments	Pass `id` alone, or omit it and use filters.
`invalid_request`	Correct the malformed ID, filter, or pagination argument before retrying.
`resource_missing`	Check the public ID and connected company; for a stale cursor, restart the search.
`taxes_not_ready` or `forms_not_ready`	Retry later with bounded backoff. Persistent failures need Finta support.
`insufficient_permission`	Restore the required company permission; repeated calls will not fix access.

An expired or revoked OAuth token is a transport authentication failure. Let the client refresh it, or reconnect. Calls consume the existing MCP allowance; the internal API read does not consume an additional API call. Honor rate-limit retry guidance and wait for the reset or an allowance change after a monthly limit rejection. These tools read existing records. They do not calculate or claim credits, file returns or 1099s, send W-9 requests, or change tax records.

​Search or retrieve by ID

​Filters

​Results and pagination

​Annual 1099 summaries

​Interpret progress and amounts

​Errors and limits