Talonic

@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.

Status: stable, listed on the official MCP Registry 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:

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 — 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:

{

"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.

---

Client setup

Claude Desktop

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

{

"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.

Cursor

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

{

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

</details>

Cline (VS Code)

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

Continue (VS Code / JetBrains)

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

{

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

</details>

Cowork

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

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 → Add custom connector.
2. URL: https://mcp.talonic.com/mcp (no query string, no headers).
3. Click Connect → you're redirected to Talonic → sign in (Google, Microsoft, or SSO).
4. Approve the consent screen (scopes: extract:write, documents:read, schemas:read, and apps:decide for the decision-task tools). Connectors added before apps:decide existed keep working; the seven decision tools show as not invocable until you remove and re-add the connector. Pick a workspace if you have multiple.
5. You're returned to Claude.ai. All thirty-six public tools appear.

The flow uses PKCE (RFC 7636) and dynamic client registration (RFC 7591). Claude.ai stores a 1-hour access token + 30-day refresh token and refreshes automatically. No API key ever touches the connector config or any URL. Revoke by removing the connector or revoking the OAuth client in your Talonic dashboard.

Alternative — API key in URL (firewalled environments, automation, static credential):

https://mcp.talonic.com/mcp?apiKey=tlnc_your_key_here

Trade-off: the key is persisted in Claude.ai's connector store and may appear in Anthropic-side logs. Rotate it if you remove or share the connector.

Uploading files in Claude.ai? Use talonic_request_upload — see the next section. Dragging a real file straight into the chat does not work through hosted connectors (a platform limit, explained below).

---

File uploads: the browser-handoff flow

This is the most important thing to understand about running Talonic inside a hosted connector (Claude.ai web, ChatGPT).

The constraint

Hosted AI platforms cap the size of a single tool-call argument. On Claude.ai the effective ceiling is ~32 KB of decoded payload (~43 KB of base64) — measured directly against production. A real PDF is hundreds of KB to several MB, so passing it as base64 file_data gets silently truncated: the server receives a clean-but-incomplete prefix, the API registers a stub document, and extraction returns null fields. The agent never sees the truncatio