Talonic

@talonic/mcp

Talonic 公式 MCP サーバー。 Model Context Protocol を通じて、あらゆる AI エージェントがあらゆるドキュメント（PDF、スキャン、請求書、契約書、フォームなど）から、スキーマで検証済みの構造化データを抽出できるようにします。

ステータス： 安定版です。公式 MCP Registry に io.github.talonicdev/talonic-mcp として掲載されています。公開ツールは36個、リソースは2個です。このうち、External モードの Talonic Apps 向けの意思決定タスク用ツールが7個あります（まだ本番環境での検証は完了しておらず、プラットフォームの decide ティアで動作します。アプリごとの decide 権限が付与された tlnc_ キー、または apps:decide スコープと senior_member 以上のロールを持つ OAuth セッションが必要です）。残りのツールは、本番環境でエンドツーエンドの検証が完了しており（Claude.ai ホスト型コネクターを含む）、各ツールが独自の ChatGPT Apps SDK ウィジェットカードを表示します。デスクトップ／IDE クライアント向けのローカル stdio プロセスとして実行することも、Claude.ai コネクター向けのホスト型 Streamable HTTP サーバーとして mcp.talonic.com で実行することもできます。

利用できる機能

1回インストールするだけで、エージェントはドキュメント抽出ワークフロー全体を利用できます。

• talonic://schemas — 保存済みスキーマの一覧です。
• talonic://webhooks/reference — webhook のイベントタイプ、配信セマンティクス、署名検証、再試行ポリシーです。

すべてのツールの説明には、LLM 向けに USE WHEN / DO NOT USE WHEN の指針が明記されているため、エージェントは追加のプロンプトがなくても適切なツールを選べます。

使用する理由

エージェントが PDF、スキャン画像、または書式の整っていないドキュメントから構造化データを取得する場合、一般的な方法は生の OCR と LLM の呼び出しです。しかし、結果は不安定で、表が崩れたり、日付を読み違えたり、合計が間違ったりします。代わりに talonic_extract は、フィールドごとの信頼度スコア付きのスキーマ検証済み JSON、検出されたドキュメントタイプ、後続の呼び出しに使える安定した ID を返します。パイプライン全体（アップロード → OCR → 抽出 → 検証）が、1回のリクエストでサーバー側で実行されます。

クイックスタート

1. API キーを取得する（30秒）

各ユーザーは、それぞれ専用の分離された Talonic ワークスペースを使用します。ドキュメントとスキーマはユーザー本人だけが閲覧できます。

1. app.talonic.com でサインアップします。無料プランでは1日50回まで抽出でき、クレジットカードは不要です。
2. Settings → API Keys → Create New Key を選択します。
3. tlnc_… の値を MCP クライアントの設定に貼り付けます（以下のスニペットを参照）。

Claude.ai では API キーは不要です。 ホスト型コネクターは OAuth を使用します。Claude.ai が PKCE を介して認証を処理し、短期間有効な独自のトークンを保存します。API キーが必要なのは、ローカルの stdio インストール（Claude Desktop、Cursor、Cline、Continue、Cowork）と、API キー URL のフォールバックのみです。

2. インストールする

すべてのローカルクライアントは、env ブロックにキーを設定した1行の npx 呼び出しで、同じ方法でサーバーを起動します。クローンもビルドも不要です。

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

バージョンの固定。 試すだけなら @latest で問題ありません。本番環境や CI ではバージョンを固定し（例：@talonic/[email protected]）、リリースによってエージェントが依存するツールの説明、検証ルール、レスポンス形式が予告なく変わらないようにしてください。CHANGELOG を確認してから固定するバージョンを更新してください。

クライアントの設定

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

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

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

Claude.ai の「カスタムコネクターを追加」フローでは、ローカルプロセスではなくリモート MCP URL を使用します。mcp.talonic.com でホストしています。推奨される方法は OAuth です。設定に API キーは不要です。

推奨 — OAuth（API キー不要）：

1. claude.ai/settings/connectors を開き、カスタムコネクターを追加を選択します。
2. URL：https://mcp.talonic.com/mcp（クエリー文字列やヘッダーは不要です）。
3. 接続をクリックすると Talonic にリダイレクトされるので、サインインします（Google、Microsoft、または SSO）。
4. 同意画面で承認します（スコープ：extract:write、documents:read、schemas:read、および意思決定タスクツール用の apps:decide）。apps:decide の追加前に登録したコネクターも引き続き動作しますが、コネクターを削除して再追加するまでは、7 つの意思決定ツールは呼び出し不可として表示されます。複数のワークスペースがある場合は、ワークスペースを選択します。
5. Claude.ai に戻ります。公開ツール 36 個すべてが表示されます。

このフローでは PKCE（RFC 7636）と動的クライアント登録（RFC 7591）を使用します。Claude.ai は有効期間 1 時間のアクセストークンと有効期間 30 日のリフレッシュトークンを保存し、自動的に更新します。API キーがコネクターの設定や URL に含まれることはありません。コネクターを削除するか、Talonic ダッシュボードで OAuth クライアントを失効させると、取り消せます。

代替方法 — URL に API キーを含める場合（ファイアウォールで保護された環境、自動化、固定の認証情報）：

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

トレードオフ：キーは Claude.ai のコネクターストアに保存され、Anthropic 側のログに記録される可能性があります。コネクターを削除または共有する場合は、キーをローテーションしてください。

Claude.ai でファイルをアップロードする場合は、talonic_request_upload を使用してください。次のセクションを参照してください。実際のファイルをチャットに直接ドラッグしても、ホスト型コネクター経由では機能しません（プラットフォーム上の制限です。詳しくは以下で説明します）。

ファイルのアップロード：ブラウザーに引き継ぐフロー

Talonic をホスト型コネクター（Claude.ai web、ChatGPT）内で実行するうえで、最も重要な点です。

制約

ホスト型 AI プラットフォームでは、1 回のツール呼び出し引数のサイズに上限があります。Claude.ai での実質的な上限はデコード後のペイロードで約 32 KB（base64 で約 43 KB）です。これは本番環境で直接測定した値です。実際の PDF は数百 KB から数 MB あるため、base64 の file_data として渡すと通知なく切り詰められます。サーバーは形式上は正しいものの不完全な先頭部分を受け取り、API はスタブ文書を登録し、抽出結果のフィールドは null になります。エージェントには切り詰められたことが分かりません。また、エージェントのサンドボックスは、別の経路でバイトデータをアップロードすることもできません。送信先が許可リストで制限されているため、ストレージへの直接の PUT はブロックされます。

これらはホスト型／サンドボックス型エージェントプラットフォームの意図的かつ構造的な特性であり、Talonic のバグではなく、設定で回避できるものでもありません。同じ制限は ChatGPT コネクターなどの環境にも適用されます。

解決方法：talonic_request_upload

ツール呼び出しのサイズ上限も送信先の許可リストも適用されない、ユーザー自身のブラウザーを経由してファイルを転送します。

1. Agent calls  talonic_request_upload(filename)
       → { document_id, upload_url: "https://app.talonic.com/u/<token>", expires_at }
2. Agent shows the upload_url to the user.
3. User opens it in a browser tab and drops the file.
4. Agent polls  talonic_get_document(document_id)  until status === "completed".
5. Agent calls  talonic_extract(document_id, schema)  — structured data comes back.

ユーザーが行うことは、クリック 1 回だけです。Slack／Stripe の「ブラウザーで開く」リンクと同じパターンで、すべてのホスト型エージェントで機能します。本番環境の Claude.ai でエンドツーエンドの動作を確認済みです。

エージェント向け： ユーザーの「完了」や「アップロードしました」という発言が示すのは、ブラウザー側のアップロードが完了したことだけです。サーバー側の OCR と処理には、さらに約 10～30 秒かかります。status が "completed" になるまで talonic_get_document をポーリングしてから、talonic_extract を呼び出してください。早く呼び出すと、ファイルが見つからないように見えるエラーが返されます。（ツールの説明でこの手順が指定されているため、通常はこれを促す必要はありません。）

必要ない場合

• ローカル stdio インストール（Claude Desktop、Cursor、Cline、Continue、Cowork）には、ツール呼び出しのサイズ上限がありません。ファイルを渡すと、エージェントが file_data を直接送信するため、talonic_request_upload は不要です。
• ファイルがすでに公開 URLにある場合 → talonic_extract に file_url を渡します。
• ファイルがすでに app.talonic.com にアップロードされている場合 → document_id を渡します。

エージェントの判断ガイド

呼び出す前に適切なツールを選びましょう。間違ったツールを選ぶと、誤ったデータが返され、クレジットを消費し、会話の進行も遅くなります。

ユーザーがファイルを持っている場合

• ローカルクライアント（Desktop、Cursor、…）で、小～中規模のファイルの場合 → file_data と filename を指定して talonic_extract を使用します。
• ホスト型コネクター（Claude.ai）の場合 → talonic_request_upload を呼び出し、完了するまでポーリングしてから、document_id を指定して talonic_extract を使用します。（ブラウザー経由の引き渡しを参照してください。）
• ファイルが公開 URL にある場合 → file_url を指定して talonic_extract を使用します。
• 特定のフィールドが必要な場合 → schema または schema_id を指定します。全文が必要な場合 → talonic_to_markdown を使用します。両方必要な場合 → include_markdown: true を指定して talonic_extract を使用します。

既存のドキュメントについてユーザーが質問している場合

• 概念的・あいまいな質問（「補償に関するドキュメントはありますか」など） → talonic_search を使用します。
• 値に基づく質問（「1000 EUR を超える請求書」など） → talonic_filter を使用します。
• ユーザーが document_id を参照している場合 → talonic_get_document（メタデータ）、talonic_to_markdown（テキスト）、または talonic_extract（新しいスキーマで再抽出）を使用します。再アップロードするよりも、document_id を再利用するほうが低コストです。

スキーマを使用する場合

• 1 回限りの場合 → スキーマをインラインで指定します。多くのドキュメントで再利用する場合 → 一度 talonic_save_schema を呼び出し、その後 schema_id を指定して talonic_extract を使用します。既存のスキーマを確認する場合 → talonic_list_schemas を使用します。

信頼度と人によるレビュー

• confidence.overall が約 0.7 未満の場合 → 抽出結果の信頼性が低い可能性があることをユーザーに伝え、信頼度の低いフィールドを示し、後続のアクションを行う前に確認してください。
• フィールドごとの信頼度が約 0.7 未満の場合 → 「要確認」とし、計算や外部呼び出しに黙って使用しないでください。
• 重要なフィールド（金額、法的条件、氏名、日付） → 信頼度が高くても、ユーザーに確認してください。
• 出典の引用が必要な場合 → include_provenance: true を指定すると、フィールドごとのページ、セクション、出典テキストが得られます。

Talonic を呼び出さない場合

• 一般知識に関する質問や雑談の場合 — 先回りして抽出しないでください。
• 以前の呼び出しでデータがすでに会話に含まれている場合 — そのデータを再利用してください。
• コストや残高に関する質問の場合 → talonic_get_balance を使用します。1 回ごとのコストは、すべての talonic_extract／talonic_to_markdown のレスポンスで cost に記載されています。

仕組み

Agent (Claude Desktop / Cursor / Claude.ai / …)
  │  MCP protocol — stdio (local) or Streamable HTTP (hosted)
  ▼
Talonic MCP server (this package)
  │  HTTPS, Bearer auth (API key or OAuth token)
  ▼
api.talonic.com

各ツール呼び出しは、Talonic API への HTTP リクエスト 1 回分です。サーバーは、認証、一時的な障害（429、5xx）に対する再試行、MIME タイプの検出、マルチパートのシリアライズ、構造化されたエラー形式への変換を処理します。これは薄いステートレスクライアントです。プライバシーを参照してください。

設定

MCP クライアント設定の env ブロックで設定します。

トラブルシューティング

Error: TALONIC_API_KEY environment variable is required. env ブロックが不足しているか、読み取られていません。JSON の形式を確認してから、クライアントを完全に再起動してください（会話を再開するだけでは不十分です）。

接続済みサーバーの一覧に Talonic が表示されません。 command が npx で、args が正確に ["-y", "@talonic/mcp@latest"] であることを確認してください。ターミナルで動作を確認するには、npx -y @talonic/mcp@latest --version を実行します。バージョンが表示されるはずです。

talonic_extract がスキーマなしで検証エラーを返します。 これは仕様です。呼び出しでは、抽出するフィールドを指定する必要があります。エラーには、再試行がすぐに成功するように、instructions に合わせて調整された、すぐに貼り付けて使える最小限のスキーマが含まれます。対処方法は3つあります。インラインで schema（完全な JSON Schema を推奨）を指定する、talonic_list_schemas から取得した schema_id を渡す、または auto_schema: true を設定してオープンキャプチャを有効にする方法です。オープンキャプチャでは Talonic がフィールドを検出して、調整可能な推奨スキーマを返します。

Claude.ai にファイルをドラッグすると、フィールドが空または null になります。 ホスト型コネクターのツール呼び出し上限（約32 KB）により、file_data が切り詰められました。talonic_request_upload を使用してください。ブラウザーハンドオフのフローがサポート対象の方法です。ローカルの stdio インストールには影響しません。

talonic_request_upload は成功しましたが、その直後に talonic_extract がエラーになります。 処理が完了する前に抽出を実行しています。status === "completed" になるまで talonic_get_document をポーリングしてから、抽出してください。ユーザーの「完了」はブラウザーからのアップロードが終わったことを意味するだけで、OCR が完了したという意味ではありません。

データがあるはずなのに talonic_filter が何も返しません。 原因は2つあります。（1）フィールドがまだ抽出されていないか、フィルター可能ではありません。talonic_search を呼び出し、filterable: true を確認してください。（2）スキーマの型が適切ではありません。数値演算子（gt、gte、lt、lte、between）を使うには、フィールドの型を number にする必要があります。数値を含む string フィールドは、結果を何も返さずに終わります。数値フィルターを作成する前に、talonic_search から取得した field.dataType === "number" を条件として確認してください。

更新後もツールの説明が古いまま表示されます。 一部のクライアントはツール一覧をキャッシュします。Claude.ai の場合は、コネクターを削除して再追加してください。ローカルクライアントの場合は、再起動してください。

既知の制限事項（v0.1）

• talonic_extract ではフィールドの指定が必要です。 schema（完全な JSON Schema を推奨）または schema_id を渡すか、auto_schema: true を設定してオープンキャプチャを有効にしてください。オープンキャプチャではフィールドを検出し、推奨スキーマを返します。この3つのどれも指定しない呼び出しでは、すぐに貼り付けて使える最小限のスキーマを含む検証エラーが返されます。フラットなキーと型のマップ（{ vendor_name: "string" }）で「フィールドがありません」というエラーが出る場合は、完全な JSON Schema を使用してください。

  {
    "type": "object",
    "properties": {
      "vendor_name": { "type": "string", "title": "Vendor Name" },
      "total_amount": { "type": "number", "title": "Total Amount" }
    },
    "required": ["vendor_name", "total_amount"]
  }
  

• ホスト型コネクターのツール呼び出し上限（約32 KB）。 Claude.ai／ChatGPT では、実際のファイルを file_data 経由で渡せません。talonic_request_upload を使用してください。ローカルインストールには影響しません。
• フィルターには filterable: true のフィールドが必要です。 先に talonic_search を呼び出してください。talonic_filter で使用できるのは、filterable: true の項目のみです。
• 数値フィルター演算子には、型が number のフィールドが必要です。 文字列として保存された数値（通貨記号、ロケール形式など）は、結果を何も返さずに終わります。設計時にスキーマのフィールド型を適切に設定し、クエリ時に dataType を条件として確認してください。
• 呼び出しごとのコストが発生するのは抽出のみです。 talonic_extract と talonic_to_markdown（ファイル入力パス）は、API の X-Talonic-Cost-* ヘッダーから取得した cost ブロック（costCredits、costEur、balanceCredits、cellsResolvedRegistry、cellsResolvedAi）を返します。読み取りツールはクレジットを消費せず、cost も含みません。document_id パスでの talonic_to_markdown は cost: null を返します。残高はいつでも talonic_get_balance で確認できます。

開発

git clone https://github.com/talonicdev/talonic-mcp.git
cd talonic-mcp
npm install
npm run build
npm test
node dist/server.js --version

ドキュメントへの貢献やツールの追加を行う場合は、まず AGENTS.md と docs/architecture/docs-pipeline.md をお読みください。ドキュメントの編集先が2つあり、誤った方を編集しやすいためです。

プライバシー

この MCP サーバーは薄いクライアントです。独自にデータを収集、保存、記録、送信することはありません。すべてのツール呼び出しは、お客様の認証情報を使用して api.talonic.com に直接転送され、応答はそのまま返されます。このサーバーは、1 回のツール呼び出しを超えて API キー、入力、出力、ドキュメントの内容を保持せず、分析データやテレメトリーも送信しません。また、ファイルの読み書きは、お客様が明示的に指定した file_path に対して、その呼び出しの実行中に限って行います。

アップロードされたデータの Talonic による取り扱いは、talonic.com/privacy に従います。ドキュメントは OCR と抽出のために処理され、結果は app.talonic.com 上のお客様専用のワークスペースに保存されます。ワークスペースのデータが第三者と共有されることはありません。状態を削除するには、ダッシュボードでドキュメントやスキーマを削除するか、API キーを取り消してください。この連携に関するプライバシーのご質問は、[email protected] までお問い合わせください。

ライセンス

MIT © Talonic GmbH