Known Limitations

The Talonic MCP server v0.1 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 extraction pipeline's maturity in v0.1. Schema-less extraction, certain filter operators, cost information, and per-field provenance are not yet available. These are documented here so agent developers can set accurate expectations and build appropriate fallbacks.

• Schema is required on `talonic_extract`. Schema-less extraction is unreliable in v0.1 and is rejected at the MCP layer with a validation error. Always pass a schema (full JSON Schema recommended) or a schema_id.
• 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.
• Drag-and-drop file uploads in Claude.ai are capped by Claude.ai's tool-call argument size limit. A base64-encoded real PDF (typically hundreds of KB) cannot fit through Claude.ai's connector tool-call pipe, which truncates parameters under ~1KB. The Talonic API receives a few hundred bytes, registers an empty document, and returns a response with null extracted fields. This is a Claude.ai platform limit on connectors, not a Talonic MCP server bug. Workaround for Claude.ai users: use file_url (publicly reachable URL), document_id (file uploaded at app.talonic.com), or use a local-stdio install (npx -y @talonic/mcp@latest in Claude Desktop, Cursor, Cline, etc.) which has no parameter cap. The architectural fix is pre-signed upload URLs.
• Cost, EUR price, and remaining balance are not surfaced. The API does not return them yet. Credit balance must be checked in the Talonic dashboard.

Agents should handle these limitations gracefully. For the schema requirement, always construct or reference a schema before calling talonic_extract. For the missing cost information, direct users to the Talonic dashboard at https://app.talonic.com when they ask about pricing or credit balance.

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.