Skip to main content
Glama
talonicdev

talonic-mcp

Official
by talonicdev
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

Extract Data from Document

talonic_extract

Extract structured data from any document (PDF, image, scan) using a schema. Returns validated JSON with per-field confidence scores and document metadata.

Instructions

STATUS: stable. Production-safe when called with a schema. Schema-less extraction is disabled at the MCP layer.

Extract structured, schema-validated data from a document using Talonic. Returns clean JSON matching the schema, with per-field confidence scores and metadata about the document (detected type, language, page count).

USE WHEN:

  • The user has a document (PDF, image, scan, DOCX, etc.) and wants specific fields pulled out.

  • You need structured data (vendor name, total amount, dates, parties, terms) rather than free text.

  • The user uploads or references any invoice, contract, certificate, statement, or form.

  • You want validated JSON instead of trying to OCR + parse with raw LLM calls.

DO NOT USE WHEN:

  • The user just wants the full text content (use talonic_to_markdown after extracting once).

  • The user wants to find documents matching a query (use talonic_search or talonic_filter).

FILE SOURCES (provide exactly EXACTLY ONE; never combine, e.g. do NOT pass both file_data and file_path):

  • file_data + filename: base64-encoded file bytes plus the original filename (with extension). RECOMMENDED for local-stdio installs (Claude Desktop, Cursor, Cline, Continue, Cowork). WARNING for hosted-MCP via Claude.ai connectors: Claude.ai imposes a hard size limit on tool-call arguments (effectively under ~1KB), so file_data CANNOT carry a real PDF through Claude.ai's pipeline. The bytes get truncated before reaching the MCP server. For files larger than a trivial test, use file_url or document_id instead when running through Claude.ai. Local stdio installs do NOT have this limit.

  • file_path: a local path to the document. Only works if the MCP server process can read that path on its own filesystem. Chat clients (Claude Desktop, Claude.ai, Cowork) store user uploads in a sandbox the MCP server cannot access, so file_path is only useful when the agent explicitly knows a path on the same machine as the MCP server.

  • file_url: a URL the Talonic API will fetch directly. Use for documents already on the public web. Best path for Claude.ai users dealing with files larger than the parameter cap.

  • document_id: re-extract a document already in the workspace. Cheapest option when the document is already uploaded via app.talonic.com or a previous extract call.

SCHEMA (REQUIRED, provide exactly one of schema or schema_id):

  • JSON Schema (RECOMMENDED): { type: "object", properties: { vendor_name: { type: "string" } } }.

  • Flat key-type map: { vendor_name: "string", invoice_total: "number" }. Accepted, but if you get a "no fields" error, fall back to JSON Schema.

  • schema_id: id of a saved schema from talonic_list_schemas. Accepts UUID or SCH-XXXXXXXX short id.

Calls without schema or schema_id are rejected with a validation error before they hit the API, to prevent unreliable schema-free extractions reaching production.

RESPONSE SHAPE (key fields):

  • data: the structured extracted JSON, shaped by your schema.

  • confidence.overall: 0..1 confidence for the extraction as a whole.

  • confidence.fields: per-field confidence map. Treat fields below ~0.7 as needing human review.

  • document.id, document.filename, document.pages, document.type_detected, document.language_detected.

  • extraction_id, request_id: stable identifiers for support and re-fetch.

  • processing.duration_ms, processing.region: useful for debugging and capacity planning.

  • markdown: present only when include_markdown: true.

  • provenance: present only when include_provenance: true. Per-field source evidence: { field_name: { source_text, section, page } }. Useful for audit trails and citations. Cost, EUR price, and remaining credit balance are not surfaced in v0.1 and may appear in a later version.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
file_dataNoBase64-encoded file bytes. Recommended path when the agent already has the file in memory (e.g., the user attached a PDF to the conversation). Pair with `filename` so MIME type can be inferred. Works regardless of where the file lives on disk.
filenameNoOriginal filename including extension, e.g. 'invoice.pdf'. Used to infer MIME type when uploading via `file_data`. Required when `file_data` is provided.
file_pathNoLocal path to a document file. Only works if the MCP server has read access to that path. In sandboxed chat clients (Claude Desktop, Cowork) where uploads land in a host-owned directory, use `file_data` instead.
file_urlNoURL to a document file. The Talonic API fetches it server-side. Use this for documents already on the public web.
document_idNoID of a document already in the workspace, to re-extract with a new schema.
schemaNoInline schema definition. REQUIRED unless `schema_id` is provided. Recommended: full JSON Schema {type:'object', properties:{...}}. Also accepted: flat key-type map {field_name:'string', amount:'number'}. Mutually exclusive with `schema_id`.
schema_idNoID of a saved schema. REQUIRED unless `schema` is provided. Accepts UUID or SCH-XXXXXXXX short id from talonic_list_schemas. Mutually exclusive with `schema`.
instructionsNoNatural-language guidance for the extractor, e.g. 'Focus on the billing section. Amounts are in EUR.'
include_markdownNoInclude OCR-converted markdown in the response alongside structured data.
include_provenanceNoInclude per-field provenance (source_text, section, page) showing where each value was found in the document.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
extraction_idYesStable identifier for this extraction.
request_idNoServer-assigned request ID for support and debugging.
statusYesExtraction status (e.g. 'complete').
documentYesMetadata about the ingested document.
dataYesThe extracted structured data, shape determined by the schema.
schemaNoSchema metadata: which schema was used and how it can be saved.
confidenceNoExtraction confidence. Treat fields below ~0.7 as needing human review.
provenanceNoPer-field source evidence (source_text, section, page). Present only when `include_provenance: true`.
processingNoProcessing metadata: duration, pages processed, region.
linksNoURLs for self, document, and human-readable dashboard view.
markdownNoOCR-converted markdown. Present only when `include_markdown: true`.
costNoPer-call cost and post-call balance, parsed from the X-Talonic-* response headers. `null` for non-extract calls; not always present on legacy clients.

Tool Definition Quality

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes well beyond annotations, disclosing that schema-less extraction is disabled at the MCP layer, that calls without schema are rejected, and that the tool is production-safe only with a schema. It also explains response structure including confidence scores and provenance, and notes cost/credit absence.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear section headers and front-loads key info. However, it is somewhat verbose and repeats some details from the schema. Overall it balances completeness with organization, but could be trimmed slightly for better conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (10 parameters, nested objects, output schema), the description covers all essential aspects: status, usage scenarios, file source selection with caveats, schema requirements, response shape, and cost/credit absence. It accounts for multiple deployment contexts and provides comprehensive guidance.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, the baseline is 3. The description adds significant value by explaining nuances of each file source, recommending best practices, detailing schema format options, and clarifying the instructions parameter. It could be slightly more concise but provides useful context beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it extracts structured, schema-validated data from documents. It also differentiates from siblings by explicitly listing when to use vs not use alternatives like talonic_to_markdown, talonic_search, and talonic_filter.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes explicit 'USE WHEN' and 'DO NOT USE WHEN' sections, detailing conditions for various file sources and schema types. It provides concrete alternatives for sibling tools and warns about platform-specific limitations (e.g., Claude.ai file size constraints).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/talonicdev/talonic-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server