Talonic

Name: Talonic
Author: talonicdev

@talonicdev

About Talonic

Extract structured, schema-validated data from PDFs, scans, images, spreadsheets, and forms. Lets AI agents pull clean JSON out of any document via the Model Context Protocol.

#document-extraction #ocr #structured-data #pdf #forms #schema #talonic #anthropic

Basic information

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "talonic": {
      "command": "npx",
      "args": [
        "-y",
        "@talonic/mcp@latest"
      ],
      "env": {
        "TALONIC_API_KEY": "<YOUR_TALONIC_API_KEY>"
      }
    }
  }
}

Tools

STATUS: stable. List all saved schemas in the user's Talonic workspace. Returns each schema with its id (UUID), short_id (SCH-XXXXXXXX), name, description, version, field count, and full JSON Schema definition. Either id form is accepted by talonic_extract's `schema_id` parameter. USE WHEN: - The user asks what schemas they have, or asks to see existing schemas. - You want to discover existing schemas before designing a new one. - Before recommending the user create a schema, check if one already covers the use case. - The user asks to extract from a known document type and you want to find a matching schema. DO NOT USE WHEN: - The user just wants to extract data from a document and provides an inline schema (call talonic_extract directly). TIP: Pair this with talonic_extract by passing the chosen schema's id as `schema_id`.

STATUS: stable. Save a schema definition to the user's Talonic workspace so it can be reused across future extractions. Returns the saved schema with its newly assigned id and short_id. USE WHEN: - The user asks to save a schema, store a template, or reuse the schema across docs. - You have iterated on a schema with the user and they confirmed it should be saved. - The user wants to standardise extraction across many documents of the same type. DO NOT USE WHEN: - The user just wants to extract once with an inline schema (call talonic_extract directly with the schema inline). - The user has not confirmed the schema design (avoid creating clutter in their workspace). DEFINITION FORMATS: - JSON Schema (most reliable): { type: "object", properties: { vendor_name: { type: "string" } } } - Flat key-type map: { vendor_name: "string", invoice_total: "number" } -- API normalises server-side. If you get a "no fields" error from the API, fall back to JSON Schema. TIP: After saving, call talonic_extract with `schema_id` set to the returned id (UUID or SCH- short id) for consistent results.

STATUS: stable. Fetch full metadata for a single document already in the user's Talonic workspace. Returns id, filename, page count, detected document type, language, processing log, and link URLs (self, extractions, dashboard). USE WHEN: - You need details about a specific document the user already extracted or uploaded. - You have a document_id from a previous extract or search call and want more context. - The user asks 'tell me about document X' or similar. DO NOT USE WHEN: - The user wants the document's full text content (use talonic_to_markdown for OCR markdown). - The user wants extracted structured data (use talonic_extract with a schema, or fetch the extraction by id). - The user has a file but no document_id yet (call talonic_extract first to ingest the document).

STATUS: stable. Search the user's Talonic workspace for documents, fields, sources, or schemas matching a query. Returns ranked results across all entity types in one call. USE WHEN: - The user wants to find documents but does not know the exact filename or id. - The query is conceptual ('contracts mentioning indemnification', 'Acme invoices'). - You need to narrow a large workspace before calling talonic_extract or talonic_filter. - The user asks 'do I have any docs about X' or 'find anything related to X'. DO NOT USE WHEN: - The user has a specific document_id (use talonic_get_document instead). - The user wants to apply structured field-value filters like 'amount > 1000' (use talonic_filter). - The user wants to extract data from a brand-new document (use talonic_extract). TIP: The result includes documents, fieldMatches, sources, schemas, and fields. Both fields[] and fieldMatches[] include a `filterable` boolean. Only entries with filterable: true can be used with talonic_filter. Fields with filterable: false exist in a schema but have no extracted data yet. Pick the entity type the user actually needs.

STATUS: stable. Field-name resolution is server-side. The `is_not_empty` operator is intentionally not exposed in v0.1; see workaround below. Filter the user's Talonic documents by extracted field values using composable conditions. Conditions accept either a canonical field name (e.g. 'vendor.name', 'policy.0_coverage_type') or a field UUID. The Talonic API resolves names to ids server-side. USE WHEN: - The user wants documents matching specific structured criteria, like 'invoices over 1000 EUR' or 'contracts expiring before 2026-12-31' or 'COIs from Acme'. - The query is value-based on extracted fields, not a free-text concept search. - You need to retrieve a sortable, paginated list filtered by field conditions. DO NOT USE WHEN: - The user wants conceptual / free-text search across content (use talonic_search). - The user is looking for a single document by id (use talonic_get_document). - The user wants extracted data from a new document (use talonic_extract). OPERATORS: - eq, neq: equality / inequality. - gt, gte, lt, lte: numeric or date comparisons. - between: requires both `value` and `value_to`. - contains: substring match on string fields. - is_empty: presence check, no value needed. Returns documents where the field is null or missing. SCHEMA TYPING: - Numeric operators (`gt`, `gte`, `lt`, `lte`, `between`) only resolve correctly when the schema field is typed as `number`. A field typed as `string` that holds numeric content (e.g. '€1,500.00') will silently return zero matches even after extraction. Pick the right type at schema design time. NOT SUPPORTED IN v0.1: - is_not_empty: underreports against fields known to be populated. Removed from the supported operator list to keep filter results trustworthy. Workaround: filter with `eq`/`gt`/`contains` against a known value, or use `is_empty` then invert the result client-side. Tracked for a later release. TIPS: - To discover available field names, call talonic_search first with a related query. Only use fields[] entries where filterable is true — their canonicalName is what to pass as `field` here. Fields with filterable: false have no extracted data yet. - fieldMatches[].resolvedFieldId is only valid when filterable is true. Entries with filterable: false have resolvedFieldId: null and cannot be used for filtering. - Both `field` (name) and `field_id` (UUID) reach the API as `fieldId`. Either is fine.

STATUS: stable. Get the OCR-converted markdown for a document. Accepts an existing document_id, raw file bytes (base64), a local file path, or a URL. When given a raw file, the tool ingests it via extract first and then returns the markdown. USE WHEN: - The user wants the full text content of a document for summarisation, translation, or analysis. - A previous tool call returned a document_id and you want to inspect its content. - The user asks 'what does the document say' or 'summarise this PDF' (you call this then summarise). - The user has a raw PDF / scan / image and wants markdown directly without designing a schema first. DO NOT USE WHEN: - The user wants specific structured fields (use talonic_extract with a schema). INPUTS (provide exactly one): - document_id: id of an already-ingested document (cheapest path; one API call) - file_data + filename (RECOMMENDED for chat clients): base64-encoded file bytes plus the original filename (with extension). Use this whenever you already have the file in memory, e.g. the user attached it to the conversation. Works in every MCP client. - file_path: local path to a document file. Only works if the MCP server has read access to that path; in sandboxed chat clients use file_data instead. - file_url: URL to a document file (the Talonic API fetches it server-side)

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 one): - file_data + filename (RECOMMENDED for chat clients): base64-encoded file bytes plus the original filename (with extension). Use this whenever you already have the file in memory, e.g. the user attached it to the conversation. Works in every MCP client regardless of where the file lives on disk. - file_path: a local path to the document. Only works if the MCP server process can read that path on its own filesystem; many chat clients (Claude Desktop, Cowork) store user uploads in a sandbox the MCP server cannot access, in which case use file_data instead. - file_url: a URL the Talonic API will fetch directly. Use for documents already on the public web. - document_id: re-extract a document already in the workspace. 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.

Overview

What is Talonic?

Talonic is the official Model Context Protocol (MCP) server for extracting structured, schema-validated data from messy documents—PDFs, scans, images, DOCX, spreadsheets, and forms. It provides AI agents with a reliable alternative to raw OCR plus LLM calls, returning JSON with per-field confidence scores and a detected document type.

How to use Talonic?

Install locally in any stdio-compatible MCP client (Claude Desktop, Cursor, Cline, Continue, Cowork) by adding a JSON config with "command": "npx", "args": ["-y", "@talonic/mcp@latest"], and the TALONIC_API_KEY environment variable. For the hosted path (Claude.ai), connect via OAuth at https://mcp.talonic.com/mcp or fall back to an API key in the URL. Get a free API key at https://app.talonic.com (50 extractions/day, no credit card required).

Key features of Talonic

talonic_extract tool: schema-validated JSON with per-field confidence scores and cost tracking
talonic_search: conceptual search across documents, fields, sources, and schemas
talonic_filter: filter documents by extracted field values with smart operator warnings
talonic_get_document and talonic_to_markdown: fetch full metadata or OCR markdown
talonic_list_schemas, talonic_save_schema: manage reusable extraction schemas
talonic_get_balance: read credit balance, burn rate, runway, and tier info
Two resources: talonic://schemas and talonic://webhooks/reference

Use cases of Talonic

Extract structured data from invoices, receipts, or contracts into a known schema
Search across a workspace of documents by conceptual content, not just keywords
Filter documents by extracted field values (e.g., amount > $500) with schema-aware feedback
Monitor extraction costs and credit balance before processing large batches

FAQ from Talonic

What makes Talonic different from raw OCR plus an LLM call?

Raw OCR combined with an LLM call produces unreliable results. Talonic returns schema-validated JSON with per-field confidence scores and a detected document type, giving agents structured, validated data.

What runtime does Talonic require?

The local installation uses npx, which requires Node.js. The hosted endpoint works through any MCP-capable client without local dependencies.

Where does my data live?

Documents are processed and stored in your Talonic workspace. The server interacts with the Talonic API and returns data to the client; no data is stored on the client machine.

Which transports and authentication methods are supported?

Local installations use stdio transport; the hosted endpoint uses HTTP with Server-Sent Events (SSE). Authentication can be an API key (for stdio or URL-based hosted) or OAuth via PKCE (for the Claude.ai connector).

Are there any usage limits?

Yes. The free tier allows 50 extractions per day. The talonic_get_balance tool provides credit balance, 30-day burn rate, projected runway, tier, and next-tier-reset timestamp for budget-aware behaviour.

Comments

More Other MCP servers

Activepieces

activepieces

AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents

23.2K