Known Limitations

The Talonic MCP server is production-ready but has a number of known limitations that are planned for future releases. Understanding these limitations helps agents make better decisions about when and how to use each tool.

Most limitations relate to the maturity of the extraction pipeline. Certain filter operators, cost reporting, and per-field provenance have constraints. These are documented here so agent developers can set accurate expectations and build appropriate fallbacks.

• `talonic_extract` needs to know which fields to pull. Pass a schema (full JSON Schema recommended) or a schema_id — or set auto_schema: true for open capture, where Talonic discovers the fields and returns a suggested schema. A call that gives none of the three returns a validation error that hands back a ready-to-paste minimal schema, so the retry succeeds immediately.
• Schema definition: prefer full JSON Schema. The flat key-type map is documented as accepted; if you get a 'no fields' error from the API, fall back to JSON Schema.
• Filter requires `filterable: true` fields. Call talonic_search first; only entries in the response where filterable: true can be used as field (or field_id) on talonic_filter. Entries with filterable: false exist in the schema but have no extracted data yet.
• Schema field type affects filter operators. Numeric operators (gt, gte, lt, lte, between) only work on fields typed as number in the schema. Numeric values stored as strings (with currency symbols, locale formatting, etc.) silently return zero results. Type your schema fields appropriately at design time.
• `is_not_empty` filter checks materialized data. Results reflect values within seconds of extraction completing. For batch-mode documents, values are materialized after the batch poll cycle completes.
• Dragging a file directly into a Claude.ai chat does not work through the hosted connector — use talonic_request_upload instead. A base64-encoded real PDF exceeds Claude.ai's tool-call argument cap (~32 KB decoded / ~43 KB base64, measured against production), so file_data is silently truncated and the API returns null fields. This is a structural platform limit, not a Talonic bug. The supported path is the browser-handoff flow: talonic_request_upload returns an app.talonic.com/u/<token> link the user opens to drop the file; poll talonic_get_document until status is completed, then talonic_extract by document_id. Alternatives: file_url or a pre-uploaded document_id. Local-stdio installs (Claude Desktop, Cursor, Cline, Continue, Cowork) have no cap and use file_data directly.
• Cost reporting depends on response headers. talonic_extract returns a cost object (costCredits, costEur, balanceCredits, and the registry-vs-AI cell split) parsed from the X-Talonic-* response headers. It is null for non-extract calls and may be absent against older API deployments that do not send those headers, so treat it as optional and fall back to talonic_get_balance rather than assuming it is present.

Agents should handle these limitations gracefully. For the schema requirement, always construct or reference a schema before calling talonic_extract. When a user asks what a run cost, read the cost object off the extract response and fall back to talonic_get_balance if it is absent; for rates and historical spend, use talonic_get_pricing and talonic_get_usage rather than guessing.

The is_not_empty operator is now available and checks the materialized values index, which updates within seconds of extraction completing. For batch-mode documents, materialization occurs after the batch poll cycle applies results.

Workarounds summary

// Schema required on talonic_extract
// → Always pass schema (JSON Schema) or schema_id

// is_not_empty checks materialized values (updated within seconds of extraction)

// Drag-and-drop stalls on Claude.ai (hosted connector)
// → Use file_url, document_id, or local stdio install

// Numeric filter on string-typed field returns zero results
// → Define numeric fields as type "number" in the schema

// Filter on non-filterable field returns VALIDATION_ERROR
// → Call talonic_search first, use fields where filterable: true

When building agent workflows that will run unattended, design for these limitations explicitly. Check that every talonic_extract call includes a schema or schema_id. Validate filter field names against talonic_search results before constructing conditions. For file uploads in hosted connectors with size limits, prefer file_url or document_id over file_data. These defensive patterns ensure the agent handles edge cases gracefully instead of failing with cryptic errors.

The Talonic team actively tracks these limitations and publishes fixes in minor version updates. Subscribe to the @talonic/mcp npm package changelog or watch the GitHub repository for release notes. Limitations that are resolved in newer versions are removed from this list. If you encounter a limitation not documented here, report it via GitHub issues with the MCP server version and a minimal reproduction case.