TKCat 1.3.0 Connects Documented Knowledge Catalogs to AI Assistants
TKCat 1.3.0 gives AI assistants a structured way to work with knowledge catalogs in ClickHouse. Its new read-only Model Context Protocol (MCP) server lets compatible assistants find resources, inspect their data models and run queries. The practical value rests on a part of TKCat that predates LLMs: detailed, machine-readable documentation attached to the data itself.
Documentation becomes part of the interface
TKCat, or Tailored Knowledge Catalog, represents each knowledge resource as a modeled database (MDB), rather than treating it as a collection of tables with little context. An MDB includes a general description covering its source, version and scope. Its data model, built with ReDaMoR, carries comments on tables and fields, along with primary keys, foreign keys and indexes.
MDBs can also contain collection members: fields that refer to the same kind of concept, such as genes, diseases or tissues. Those shared definitions help connect resources and establish when records can be compared across databases.
That detail changes how an assistant can approach a question. Without documentation, an LLM may infer a field’s meaning from its name, guess how tables relate or miss the conventions behind coded values. TKCat makes that context available to the assistant, so its search and SQL generation can draw on the catalog’s stated definitions and relationships.
A standard route from assistants to data
The Model Context Protocol, introduced by Anthropic, defines a common client-server setup for connecting AI assistants to external data, tools and workflows. An MCP client can discover the tools a server offers and call them in response to a user’s request. For TKCat users, that means access through compatible clients such as Claude Desktop, Claude Code and Posit Assistant, without building a separate chat integration for every catalog.
TKCat 1.3.0 exposes modeled databases from a chTKCat instance, which runs TKCat on ClickHouse. It offers two server options, suited to different deployment needs:
chTKCat_mcp_server()starts a local server on the user’s computer and communicates over stdio. This setup is intended for MCP clients running locally.chTKCat_mcp_http_server()runs as a remote service beside the chTKCat instance and uses Streamable HTTP. Users connect without installing R or TKCat on their own computers.
The available tools reflect a sequence an analyst might follow when approaching unfamiliar data. list_mdbs and search_tkcat locate relevant resources. describe_mdb, describe_tables and list_collections provide context on their contents and connections. An assistant can use preview_table to inspect records, then answer questions with query_mdb, which runs ClickHouse SQL, or get_matrix_values.
From natural-language questions to inspectable queries
The workflow is more than a natural-language wrapper around a database. An assistant can search a catalog, read resource descriptions, check collection links, preview sample records and then construct a query across multiple MDBs. For example, a question about drugs that target genes associated with a disease’s phenotypes could involve phenotype, variant and drug databases.
Collections help establish whether identifiers in different MDBs describe the same kind of entity and what conditions apply to that comparison. A gene identifier might be comparable across resources only when the source or organism matches. Making those relationships explicit gives the assistant a basis for combining resources instead of relying on a plausible-sounding join.
The resulting answers can be checked against the SQL and the resources used to produce them. Users can inspect the queries, rerun them in R and reuse them in later analysis. That traceability matters in professional work: a useful answer needs to show where its result came from, not merely present a fluent response.
Here's the thing: the MCP server's usefulness depends on the quality of the catalog behind it. Clear field comments, accurate relationship definitions and well-described resource versions help the assistant choose data and interpret results. Documentation prepared for analysts can now also guide an AI assistant through the same resource.
Access controls and deployment
The server is read-only. An assistant can query data, but it cannot write records, create or delete objects, or change grants. In the remote setup, users authenticate with their own chTKCat credentials, and ClickHouse applies their permissions. Each person can access only the MDBs they are authorized to read.
Output limits constrain the number of returned rows, the size of responses and query execution time. The remote service is stateless, allowing multiple instances to run behind a reverse proxy such as nginx; tool calls are logged. These choices make the remote option relevant to organizations hosting shared resources, while keeping access tied to individual credentials.
Organizations still need to decide which MDBs can be shared with an AI assistant under their own policies. The server’s access controls govern which resources a user can query; they don’t determine whether a resource’s contents are appropriate to expose to a particular assistant.
Documentation and setup
The project’s TKCat End-to-End vignette walks through setting up ClickHouse, preparing example MDBs for HPO, ClinVar and ChEMBL, loading them into ClickHouse, and querying them from R. It also covers local and remote MCP deployment, including systemd and nginx, and configuration for Claude Code, Claude Desktop and Posit Assistant.
For server tools and parameters, the MCP server vignette provides reference material. The main vignette introduces TKCat, and the project welcomes feedback and issue reports on GitHub.
TKCat’s MCP server turns catalog documentation into a working guide for AI-assisted analysis. For teams with carefully modeled resources, the next practical step is to test whether those descriptions and cross-database relationships are specific enough to support useful, verifiable queries.
