Common Issues

This section covers the most frequently encountered issues when setting up and using the Talonic MCP server. Each issue includes a description, the root cause, and the fix. If your problem is not listed here, check the Known Limitations section or reach out via GitHub issues.

Most issues fall into two categories: configuration problems (the server does not start or connect) and tool errors (the server is running but a specific tool call fails). Configuration problems are almost always caused by malformed JSON, a missing API key, or not restarting the MCP client after editing the config.

Tool errors typically include a structured error message with an error type and description. Read the error message carefully — it usually tells you exactly what is wrong and how to fix it. For example, a VALIDATION_ERROR on talonic_filter means the field name is not in the API's registry.

When debugging, start by verifying the MCP server is running. Check the connected servers list in your MCP client. If Talonic is not listed, the issue is in your config or client setup. If it is listed but a tool call fails, the issue is with the tool input or API-side.

TALONIC_API_KEY environment variable is required

The env block in your MCP client config is missing or not being read. Double-check the JSON shape. After editing the config, fully restart the client (not just the conversation).

Talonic does not appear in connected servers

Make sure the command is npx and the args are exactly ["-y", "@talonic/mcp@latest"]. Sanity check: run npx -y @talonic/mcp@latest --version in any terminal — it should print a version number.

talonic_extract returns a validation error when no schema is given

By design in v0.1. Schema-less extraction is unreliable, so the MCP layer rejects calls that omit both schema and schema_id before they reach the API. Provide either an inline schema (full JSON Schema recommended) or a schema_id from talonic_list_schemas.

talonic_extract rejects with unsupported_file_type

The MIME type was inferred as application/octet-stream. The SDK infers from common file extensions; if your filename has an unusual extension, this may occur. A future tool version will expose explicit content_type passthrough.

talonic_filter VALIDATION_ERROR / "No field matches name"

The field name is not in the API's field registry. Field names must be canonical names (e.g. vendor.name, policy.0_term_end). Call talonic_search first; canonical names appear in fields[].canonicalName.

Tool descriptions look wrong in my client

Some MCP clients cache tool descriptions. Restart the client after a server update.

Authentication error on every tool call

If every tool call returns an authentication error, the credential the server is using is missing, malformed, or revoked. For the local npx option, check that the env block in your config has the correct variable name (TALONIC_API_KEY, not TALONIC_KEY or API_KEY) and that the value starts with tlnc_. For the hosted server with a custom-header client, verify the Authorization header is formatted as Bearer tlnc_... with a space after Bearer. For the Claude.ai connector OAuth flow, see the OAuth-specific entry below.

Claude.ai connector: stuck on sign-in or callback

The Claude.ai custom-connector flow uses OAuth 2.1 with PKCE against app.talonic.com. If the sign-in window opens but does not return to Claude.ai, or the connector reports disconnected after authorising, walk through these checks. Make sure you are signed in to the same Talonic account in app.talonic.com that owns the workspace you want to use. Allow third-party cookies for app.talonic.com and claude.ai; some browsers block the post-consent redirect otherwise. After granting consent, you should be redirected back to Claude.ai automatically; if the tab stays on app.talonic.com, click the Talonic logo or close the tab and reopen the connector to retry. If you have multiple Talonic accounts, sign out of app.talonic.com first, then start the connector flow again so the right account is used. As a last resort, remove the connector in Claude.ai and add it again with https://mcp.talonic.com/mcp as the URL.

Tool calls time out on large documents

Large documents (20+ pages) may take longer than some MCP clients' default timeout. The Talonic API processes documents up to 100 pages, but extraction time scales with page count. If you experience timeouts, try splitting large documents into smaller sections before uploading. Alternatively, check if your MCP client has a configurable timeout setting — increasing it to 60 seconds should accommodate most documents.

Debug checklist

// 1. Verify the MCP server installs and runs:
// Terminal: npx -y @talonic/mcp@latest --version
// Expected: prints version number (e.g., 0.1.6)

// 2. Verify your API key is valid:
// Terminal: curl -H "Authorization: Bearer tlnc_your_key" https://api.talonic.com/v1/schemas
// Expected: JSON response (even if empty schemas array)

// 3. Validate your config JSON:
// Paste your config into https://jsonlint.com
// Common errors: trailing commas, missing quotes, wrong brackets

// 4. Verify client picked up the config:
// Check the connected servers list in your MCP client
// If Talonic is missing, the config is not being read