1.1 Available tools

In query_mdb, the tables of the MDB are referred to by their names in the data model (e.g. SELECT * FROM genes). Tables of other MDBs can be referred to as `MDB`.`table` to integrate several resources in the same query.

1.2 Read-only access

The server can only read data. It cannot write, create or delete anything and it cannot modify grants:

• The ClickHouse session is opened with the readonly = 2 setting. ClickHouse rejects any query modifying data, tables, databases, users or grants, and this setting cannot be changed during the session.
• SQL statements are checked before being sent to ClickHouse: only single SELECT queries (possibly starting with WITH) are accepted, without SETTINGS nor INTO OUTFILE clauses and without table functions accessing external resources (e.g. url(), file(), s3(), remote()).
• The server only accesses the MDBs readable by the ClickHouse user used for the connection.

2.1 Requirements

• R (>= 4.1) and the TKCat package (version >= 1.3.0) installed on the computer running the MCP client:

install.packages("TKCat")
## or the development version
devtools::install_github("patzaw/TKCat")

• The Rscript command must be available in the PATH (otherwise use its full path in the configurations below, e.g. C:\\Users\\user_name\\AppData\\Local\\Programs\\R\\R-4.6.1\\bin\\Rscript.exe on Windows).

• A chTKCat instance reachable from this computer.

2.2 ClickHouse user

The server connects to chTKCat with the credentials provided in the following environment variables:

The default user gives access to the public MDBs only. To access private MDBs, it is recommended to use a dedicated user without any admin right, created by a chTKCat administrator:

library(TKCat)
k <- chTKCat(host = "localhost", port = 9111, user = "admin_user")
create_chTKCat_user(k, login = "mcp_user", contact = NA, admin = FALSE)
## Give access to a private MDB
add_chMDB_user(k, mdb = "Private_MDB", login = "mcp_user", admin = FALSE)

2.3 Checking the server

The following command, run in a terminal, starts the server. It should write a message such as chTKCat MCP server ready and then wait for MCP requests on its standard input (stop it with Ctrl+C).

TKCAT_HOST=localhost TKCAT_PORT=9111 TKCAT_USER=default \
   Rscript -e "TKCat::chTKCat_mcp_server()"

The MCP Inspector can be used to try the tools interactively (requires Node.js):

npx @modelcontextprotocol/inspector \
   -e TKCAT_HOST=localhost -e TKCAT_PORT=9111 \
   -- Rscript -e "TKCat::chTKCat_mcp_server()"

2.4 Configuring an MCP client

claude mcp add tkcat --scope user \
   -e TKCAT_HOST=localhost -e TKCAT_PORT=9111 \
   -e TKCAT_USER=mcp_user -e TKCAT_PASSWORD=xxxxxx \
   -- Rscript -e "TKCat::chTKCat_mcp_server()"

{
  "mcpServers": {
    "tkcat": {
      "command": "Rscript",
      "args": ["-e", "TKCat::chTKCat_mcp_server()"],
      "env": {
        "TKCAT_HOST": "tkcat.example.com",
        "TKCAT_PORT": "9111",
        "TKCAT_USER": "${TKCAT_USER}",
        "TKCAT_PASSWORD": "${TKCAT_PASSWORD}"
      }
    }
  }
}

{
  "mcpServers": {
    "tkcat": {
      "command": "Rscript",
      "args": ["-e", "TKCat::chTKCat_mcp_server()"],
      "env": {
        "TKCAT_HOST": "localhost",
        "TKCAT_PORT": "9111",
        "TKCAT_USER": "mcp_user",
        "TKCAT_PASSWORD": "xxxxxx"
      }
    }
  }
}

2.5 Server parameters

The chTKCat_mcp_server() function has additional parameters which can be set in the R expression given to Rscript:

• maxRows: maximum number of rows returned by a query (default: 1000).
• maxChars: maximum number of characters returned by a tool call (default: 60000). Longer outputs are truncated.
• maxExecutionTime: maximum execution time of a query in seconds (default: 300).

For example:

Rscript -e "TKCat::chTKCat_mcp_server(maxRows = 500, maxExecutionTime = 60)"

3.1 Architecture

The remote server is run as a service on a machine which can reach the chTKCat instance (usually the same machine). A reverse proxy (nginx) provides HTTPS and forwards the requests to one or several instances of the R server listening on the local interface only:

• Authentication. Users authenticate with their own chTKCat credentials sent in an HTTP Basic Authorization header. The credentials are checked by ClickHouse and each user only accesses the MDBs they are allowed to read. The server does not store any credential on disk.
• Stateless. The server does not create MCP sessions and answers each request with a single JSON response. Several instances can thus run in parallel behind nginx: since R processes one request at a time, running several instances avoids a long query blocking the other users.
• Read-only. The same tools and the same read-only protections as for the local server are applied to each user connection.

3.2 Running the server

On the server machine, install R and TKCat in a site library (available to the user running the service). Then the server can be started with:

TKCAT_HOST=localhost TKCAT_PORT=9111 TKCAT_MCP_PORT=8801 \
   Rscript -e "TKCat::chTKCat_mcp_http_server()"

The main parameters of chTKCat_mcp_http_server() are the following (see ?chTKCat_mcp_http_server for the complete list):

Keep the default mcpHost = "127.0.0.1" when the server is behind nginx on the same machine: the R server does not provide HTTPS and must not be directly reachable from the network.

Tool calls are logged on the standard error output with the time, the client address, the user and the name of the tool:

2026-10-10 14:46:51 - 10.1.2.3 - jdoe - query_mdb

3.3 Running the server as a systemd service

The following systemd template unit, saved as /etc/systemd/system/tkcat-mcp@.service, runs an instance of the server on the port given as instance name. It is run by a dedicated system user (tkcat-mcp) without any privilege.

[Unit]
Description=chTKCat MCP server (port %i)
After=network-online.target
Wants=network-online.target

[Service]
User=tkcat-mcp
Group=tkcat-mcp
Environment=TKCAT_HOST=localhost
Environment=TKCAT_PORT=9111
Environment=TKCAT_MCP_HOST=127.0.0.1
Environment=TKCAT_MCP_PORT=%i
EnvironmentFile=-/etc/tkcat-mcp.env
ExecStart=/usr/local/bin/Rscript -e "TKCat::chTKCat_mcp_http_server()"
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=read-only

[Install]
WantedBy=multi-user.target

Anonymous access is configured in the optional /etc/tkcat-mcp.env file (the leading - in EnvironmentFile=- makes it optional: without this file, authentication is required for all the requests). This file is read by systemd before dropping privileges: it can thus be readable by root only, which keeps the password out of the command line and out of the files readable by the tkcat-mcp user.

TKCAT_MCP_ANONYMOUS_USER=techuser
TKCAT_MCP_ANONYMOUS_PASSWORD=techuser_password

Create the system user, protect the environment file and start, for example, 4 instances:

sudo useradd --system --no-create-home --shell /usr/sbin/nologin tkcat-mcp
sudo chown root:root /etc/tkcat-mcp.env
sudo chmod 600 /etc/tkcat-mcp.env
sudo systemctl daemon-reload
sudo systemctl enable --now tkcat-mcp@8801 tkcat-mcp@8802 tkcat-mcp@8803 tkcat-mcp@8804
## Logs
sudo journalctl -u 'tkcat-mcp@*' -f

3.4 nginx configuration

The following configuration, saved for example as /etc/nginx/conf.d/tkcat-mcp.conf, provides HTTPS, distributes the requests among the server instances and limits the request rate by client (which also slows down password guessing attempts). Replace tkcat.example.com and the certificate paths with your own values.

limit_req_zone $binary_remote_addr zone=tkcat_mcp:10m rate=5r/s;

## R MCP server instances (see the systemd service above)
upstream tkcat_mcp_inst {
    least_conn;
    server 127.0.0.1:8801;
    server 127.0.0.1:8802;
    server 127.0.0.1:8803;
    server 127.0.0.1:8804;
    keepalive 8;
}

## Other config commands
## ...

server {

    ## Other config commands
    ## ...
    
    ## TKCat MCP server
    location = /tkcat_mcp {
        limit_req zone=tkcat_mcp burst=20 nodelay;
        client_max_body_size 1m;

        proxy_pass http://tkcat_mcp_inst/mcp;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
        ## Client address used in the logs of the R server
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;

        ## Must be longer than the maxExecutionTime of the R server
        proxy_read_timeout 330s;
        proxy_send_timeout 330s;
        proxy_buffering off;
    }

    ## ...
}

Check and reload the configuration:

sudo nginx -t && sudo systemctl reload nginx

The Authorization header is forwarded by nginx without modification. Do not enable nginx access logs with request bodies or headers: they would record the credentials and the queries of the users.

3.5 Checking the server

The server can be checked with curl (-u provides the credentials in a Basic Authorization header):

curl -u jdoe:xxxxxx https://tkcat.example.com/tkcat_mcp \
   -H "Content-Type: application/json" \
   -H "Accept: application/json, text/event-stream" \
   -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_mdbs","arguments":{}}}'

The server answers with:

• 200 and a JSON-RPC response for MCP requests;
• 202 for notifications;
• 401 if the credentials are missing or wrong;
• 403 for requests with a non-allowed Origin header;
• 405 for methods other than POST (no server-sent event stream);
• 502 if the chTKCat instance cannot be reached.

3.6 Configuring remote MCP clients

Users provide their chTKCat credentials as the Base64 encoding of user:password, which can be computed in a terminal or in R:

printf '%s' 'jdoe:xxxxxx' | base64

jsonlite::base64_enc("jdoe:xxxxxx")

claude mcp add tkcat --scope user --transport http \
   https://tkcat.example.com/tkcat_mcp \
   --header "Authorization: Basic amRvZTp4eHh4eHg="

{
  "mcpServers": {
    "tkcat": {
      "type": "http",
      "url": "https://tkcat.example.com/tkcat_mcp",
      "headers": {
        "Authorization": "Basic ${TKCAT_MCP_AUTH}"
      }
    }
  }
}

{
  "mcpServers": {
    "tkcat": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote", "https://tkcat.example.com/tkcat_mcp",
        "--header", "Authorization:${TKCAT_MCP_AUTH}"
      ],
      "env": {
        "NODE_OPTIONS": "--use-system-ca"
      }
    }
  }
}