Skip to main content
Glama
talonicdev

talonic-mcp

Official
by talonicdev
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

Extract Data from Document

talonic_extract

Extract structured, schema-validated JSON data from documents such as PDFs and scans. Get clean fields with confidence scores for each value.

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?

Annotations show readOnlyHint=false, destructiveHint=false, openWorldHint=true. The description adds that the tool is 'stable' and 'production-safe when called with a schema', discloses that 'schema-less extraction is disabled at the MCP layer', and notes limitations like Claude.ai's parameter cap. It also describes response shape including confidence scores, markdown, and provenance. No contradiction with annotations.

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 headers, bullet points, and bold labels. It front-loads status and purpose. However, it is somewhat verbose; some points are repeated (e.g., schema requirement mentioned multiple times). A slightly more concise version would be a 5.

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 tool's complexity (10 params, multiple file sources, schema options, response shape), the description covers all necessary aspects: usage scenarios, file source selection, schema format, response fields, environment-specific advice, and references to sibling tools. Output schema is provided, so return values are not required in description.

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?

Schema coverage is 100%, so params are documented. The description adds meaning beyond the schema: recommendations for file sources (file_data vs file_url vs file_path), warnings about sandbox limitations, and clarification that schema and schema_id are mutually exclusive. It also explains the response fields (data, confidence, etc.). The added value justifies a 4.

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 'Extract structured, schema-validated data from a document using Talonic.' The verb 'extract' and resource 'data from document' are specific. It distinguishes from siblings like talonic_to_markdown (full text) and talonic_search (querying), and lists use cases (invoices, contracts, etc.).

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?

Explicit 'USE WHEN' and 'DO NOT USE WHEN' sections provide clear guidance. It details when to use this tool over alternatives (e.g., structured extraction vs markdown, querying). It also includes environment-specific advice for file sources (local vs hosted), warnings about size limits, and prerequisites (schema required).

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