talonic-mcp

# @talonic/mcp

**Official Talonic MCP server.** Give any AI agent the ability to extract structured, schema-validated data from any document — PDFs, scans, invoices, contracts, forms — via the [Model Context Protocol](https://modelcontextprotocol.io).

[![talonic-mcp MCP server](https://glama.ai/mcp/servers/talonicdev/talonic-mcp/badges/score.svg)](https://glama.ai/mcp/servers/talonicdev/talonic-mcp)
[![smithery badge](https://smithery.ai/badge/talonic/talonic)](https://smithery.ai/servers/talonic/talonic)

> **Status:** stable, listed on the [official MCP Registry](https://registry.modelcontextprotocol.io/) as `io.github.talonicdev/talonic-mcp`. Thirty-six public tools and two resources, including seven decision-task tools for External-mode Talonic Apps (not yet production-verified, running at the platform's `decide` tier — a `tlnc_` key with a per-app `decide` grant, or an OAuth session with the `apps:decide` scope and a `senior_member` role or above); the rest are verified end-to-end against production (including the Claude.ai hosted connector), each tool rendering its own ChatGPT Apps SDK widget card. Runs as a local stdio process for desktop/IDE clients or as the hosted Streamable HTTP server at `mcp.talonic.com` for Claude.ai connectors.

---

## What you get

One install gives an agent the whole document-extraction workflow:

| Tool | What it does |
| --- | --- |
| **`talonic_extract`** | Extract schema-validated JSON from a document, with per-field confidence scores. The primary tool. |
| **`talonic_request_upload`** | Get a browser upload link for files too large to pass through a hosted connector (e.g. Claude.ai). The robust path for real-world documents. |
| **`talonic_to_markdown`** | OCR a document to clean markdown. |
| **`talonic_search`** | Omnisearch across documents, fields, sources, and schemas. |
| **`talonic_filter`** | Filter documents by extracted field values (`eq`, `gt`, `between`, `contains`, …). |
| **`talonic_get_document`** | Fetch a document's metadata, processing status, and links. |
| **`talonic_list_schemas`** | List saved schemas (with definitions). |
| **`talonic_save_schema`** | Save a reusable schema to the workspace. |
| **`talonic_get_balance`** | Read credit balance, EUR value, burn rate, and runway for budget-aware behaviour. |
| **`talonic_get_pricing`** | Read the public per-unit credit pricing catalog and multipliers to predict spend before running a job. |
| **`talonic_get_usage`** | Break down credit consumption per function over a trailing window (default 30 days). |
| **`talonic_list_fields`** | List the Field Registry — every canonical concept with a stable id, maturity (`core` / `proven` / `candidate`), synonyms and occurrence counts. |
| **`talonic_get_field`** | Concept card for one field (by id or by NAME): definition, aliases, maturity, occurrence stats, value distribution with examples, schema usage, identity links. |
| **`talonic_field_values`** | One concept's current values across all documents, with provenance (document, source text, resolution band). |
| **`talonic_find_data`** | Resolve a concept in the user's words to the fields, values, documents and passages that carry it — by meaning, not by name. |
| **`talonic_list_agent_tools`** | The platform's agent tool registry (`query_data` SQL, `describe_data`, document markdown, …) with schemas and per-credential invocability. |
| **`talonic_invoke_agent_tool`** | Run one platform agent tool directly with your own arguments — no model in the loop. |
| **`talonic_list_agent_tasks`** | Metadata worklist for documents parked at Agent stages. |
| **`talonic_get_agent_task`** | Audited fetch of one Agent task's immutable input snapshot and output contract. |
| **`talonic_claim_agent_task`** | Acquire or reclaim a leased Agent task and its execution epoch. |
| **`talonic_heartbeat_agent_task`** | Extend the current claim lease on an Agent task using its epoch. |
| **`talonic_submit_agent_task`** | Submit an Agent task's declared typed outputs transactionally and resume the document. |
| **`talonic_list_specs`** | List the workspace's configured Specs (pipelines) — name, schema, version, field/node counts. |
| **`talonic_get_spec`** | Get one Spec's full structure: nodes, compiled phases, fields, and (optionally) its version history. |
| **`talonic_run_spec`** | Run a Spec over documents already in the workspace or public file URLs — one call, either backend. |
| **`talonic_get_run`** | Poll a Spec run's status and progress until it completes. |
| **`talonic_get_run_results`** | Read a Spec run's structured rows, one per document, with column definitions. |
| **`talonic_ask`** | Ask a natural-language question over the workspace's documents and get a cited, verified answer. |
| **`talonic_get_answer`** | Poll a long-running `talonic_ask` for its finished answer. |
| **`talonic_list_decision_tasks`** | One External-mode App's decision inbox: runs parked for an outside agent to decide (`decide` tier: per-app grant on a `tlnc_` key, or the `apps:decide` OAuth scope). |
| **`talonic_claim_decision_task`** | Lease a decision task; the claim returns the output contract, precedents and the input-package descriptor. |
| **`talonic_read_decision_package`** | Page through the claimed run's frozen input package with its provenance locators. |
| **`talonic_heartbeat_decision_task`** | Extend a decision-task lease, never past its SLA deadline. |
| **`talonic_submit_decision_task`** | Submit the decision: `outcome` against the contract, verbatim `evidence` locators, a short `rationale`. |
| **`talonic_release_decision_task`** | Give a decision task back to `available` undecided. |
| **`talonic_fail_decision_task`** | Declare a decision task undecidable: raises a Human Review and applies the app's fallback policy. |

Plus two resources for clients that browse them (Claude Desktop, Cowork render these in-UI):

- **`talonic://schemas`** — the saved-schemas list.
- **`talonic://webhooks/reference`** — webhook event types, delivery semantics, signature verification, and retry policy.

Every tool description is written for an LLM, with explicit **USE WHEN / DO NOT USE WHEN** guidance, so agents pick the right tool without extra prompting.

## Why use it

When an agent needs structured data out of a PDF, scan, or messy document, the usual approach is raw OCR plus an LLM call — and the results drift: tables get mangled, dates get misread, totals come out wrong. `talonic_extract` instead returns **schema-validated JSON with per-field confidence scores**, a detected document type, and stable IDs for follow-up calls. The full pipeline (upload → OCR → extraction → validation) runs server-side in one request.

---

## Quick start

### 1. Get an API key (30 seconds)

Each user runs against their own isolated Talonic workspace — your documents and schemas are private to you.

1. Sign up at **[app.talonic.com](https://app.talonic.com)** — free tier, 50 extractions/day, no credit card.
2. Settings → API Keys → **Create New Key**.
3. Copy the `tlnc_…` value into your MCP client config (snippets below).

> **You don't need an API key for Claude.ai.** The hosted connector uses [OAuth](#claudeai-hosted-connector) — Claude.ai handles auth via PKCE and stores its own short-lived tokens. The API key is only needed for **local-stdio installs** (Claude Desktop, Cursor, Cline, Continue, Cowork) and the API-key URL fallback.

### 2. Install

Every local client launches the server the same way — a one-line `npx` invocation with your key in the `env` block. No clone, no build:

```jsonc
{
  "command": "npx",
  "args": ["-y", "@talonic/mcp@latest"],
  "env": { "TALONIC_API_KEY": "tlnc_..." }
}
```

**Version pinning.** `@latest` is fine for trying things out. For production and CI, pin a version (e.g. `@talonic/mcp@0.1.52`) so a release can't silently change tool descriptions, validation rules, or response shapes your agent depends on. Bump the pin after reviewing the [CHANGELOG](CHANGELOG.md).

---

## Client setup

<details>
<summary><strong>Claude Desktop</strong></summary>

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "talonic": {
      "command": "npx",
      "args": ["-y", "@talonic/mcp@latest"],
      "env": { "TALONIC_API_KEY": "tlnc_your_key_here" }
    }
  }
}
```

Fully restart Claude Desktop (Cmd+Q on macOS — not just close the window). Talonic appears in the connected-servers list with all thirty-six public tools.
</details>

<details>
<summary><strong>Cursor</strong></summary>

Edit `~/.cursor/mcp.json` (or Cursor settings → MCP → edit config):

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

<details>
<summary><strong>Cline (VS Code)</strong></summary>

Open the Cline panel → settings (gear) → MCP Servers → Edit. Add the entry above. Save and restart the panel.
</details>

<details>
<summary><strong>Continue (VS Code / JetBrains)</strong></summary>

Edit `~/.continue/config.json`, add to the `mcpServers` array:

```json
{
  "name": "talonic",
  "command": "npx",
  "args": ["-y", "@talonic/mcp@latest"],
  "env": { "TALONIC_API_KEY": "tlnc_your_key_here" }
}
```
</details>

<details>
<summary><strong>Cowork</strong></summary>

Open Cowork settings → MCP Servers → Add. Use the same shape as Claude Desktop above.
</details>

### Claude.ai (hosted connector)

Claude.ai's "Add custom connector" flow uses a remote MCP URL instead of a local process. We host one at `mcp.talonic.com`. **OAuth is the recommended path** — no API key in the config.

**Recommended — OAuth (no API key):**

1. Open [claude.ai/settings/connectors](https://claude.ai/settings/connectors) → **Add custom connector**.
2. URL: `https://mcp.talonic.com/mcp` (no query string, no headers).
3. Click **Conne