Common Issues

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 500 with auto-discovery

Known limitation. Always provide either an inline schema or a schema_id. The auto-discovery code path is being stabilised.

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.