tock-mcp-server

MCP server for T.O.C.K. web-connector

Building the server

make build-servers

Running the server

make run-tock-mcp

Endpoints

Both transports support all standard MCP methods including ping, initialize, and tools/call.

Configuration

The server expects a YAML configuration file with the following structure:

tock:
  # Base URL of the Tock instance (no trailing slash)
  base_url: "https://<bot-api-host>"
  # Tock namespace
  namespace: "app"
  # Bot name
  bot: "howtonet"
  # Web-connector identifier
  connector: "web"
  # User ID sent to Tock with every request
  user_id: "mcp-user-001"
  # Optional extra HTTP headers forwarded to the Tock web-connector.
  # The value is the default used when the MCP caller does not provide one.
  # Leave empty ("") to make the header optional with no default.
  # extra_headers:
  #  X-Toki-Origin: "github-copilot"   # always sent; can be overridden by the caller
  #  X-Toki-Filter: ""                 # no default — provided by the caller if needed

server:
  # HTTP listen address of the MCP server
  addr: ":8083"
  # Name of the MCP tool exposed to AI clients.
  # Defaults to "ask_tock" if empty or omitted.
  tool_name: "ask_tock"
  # Description of the MCP tool shown to AI clients.
  # This text helps the AI decide when and how to call the tool.
  # Defaults to a built-in description if empty or omitted.
  tool_description: "Ask a question to the Tock documentary chatbot (RAG). Returns the text response and links to source documents."

Tip: Customise tool_name and tool_description to match the domain of your Tock bot so that AI assistants can better decide when to invoke the tool.

Docker image (scratch)

The image is built with a scratch runtime and expects a configuration file available at /config/config.yaml.

config.yaml

tock:
  # Base URL of the Tock instance (no trailing slash)
  base_url: "https://<bot-api-endpoint>"
  # Tock namespace
  namespace: "app"
  # Bot name
  bot: "howtonet"
  # Web-connector identifier
  connector: "web"
  # User ID sent to Tock with every request
  user_id: "mcp-user-001"

server:
  # HTTP listen address of the MCP server
  addr: ":8083"
  # Name and description of the MCP tool (optional — defaults shown below)
  tool_name: "ask_tock"
  tool_description: "Ask a question to the Tock documentary chatbot (RAG). Returns the text response and links to source documents."

docker run --rm -p 8083:8083 \
  -v "$(pwd)/config.yaml:/config/config.yaml:ro" \
  ghcr.io/sacquatella/tock-mcp-server:v0.5.0

Build locally:

docker build -t tock-mcp-server:local .

Run locally with a mounted config file:

docker run --rm -p 8083:8083 \
  -v "$(pwd)/config.yaml:/config/config.yaml:ro" \
  tock-mcp-server:local

Deploying on Kubernetes (ConfigMap)

with manifest

The container does not embed config.yaml, so each environment can mount its own ConfigMap.

Use the provided manifest:

kubectl apply -f k8s/tock-mcp-server.yaml

Example (extract):

apiVersion: v1
kind: ConfigMap
metadata:
  name: tock-mcp-config
data:
  config.yaml: |
    tock:
      base_url: "https://demo.tock.ai"
      namespace: "sacquatella"
      bot: "howtonet"
      connector: "howtonetweb"
      user_id: "mcp-user-001"
    server:
      addr: ":8083"
      tool_name: "ask_tock"
      tool_description: "Ask a question to the Tock documentary chatbot (RAG). Returns the text response and links to source documents."
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: tock-mcp-server
spec:
  replicas: 1
  selector:
    matchLabels:
      app: tock-mcp-

... [View full README on GitHub](https://github.com/sacquatella/tock-mcp-server#readme)