Agent Clients

KTX integrates with coding agents through two channels that can be used independently or together:

• MCP server — A persistent Model Context Protocol server that exposes KTX tools (semantic queries, knowledge search, SQL execution) directly to the agent
• CLI skills — Command definitions that teach the agent how to invoke KTX via the terminal

Run ktx setup and select your agent targets, or configure manually using the snippets below.

Claude Code

Install via ktx setup

During setup, select Claude Code from the agent targets. KTX writes:

Both project-scoped and global installations are supported. Global installs write to ~/.claude/skills/ktx/SKILL.md.

Manual MCP configuration

Add KTX to .mcp.json at your project root:

{
  "mcpServers": {
    "ktx": {
      "command": "ktx",
      "args": [
        "--project-dir", "/path/to/ktx-project",
        "serve",
        "--mcp", "stdio",
        "--semantic-compute",
        "--execute-queries"
      ],
      "env": {}
    }
  }
}

Replace /path/to/ktx-project with your KTX project directory. For a pinned local checkout, use the absolute path to the built CLI as the command and arguments generated by ktx setup.

Manual CLI skills configuration

Create .claude/skills/ktx/SKILL.md:

---
name: ktx
description: Use local KTX semantic context, wiki knowledge, and safe SQL execution for this project.
---

Available commands:
- `ktx agent context --json --project-dir /path/to/project`
- `ktx agent sl list --json --project-dir /path/to/project`
- `ktx agent sl read '<sourceName>' --json --project-dir /path/to/project`
- `ktx agent sl query --json --project-dir /path/to/project --connection-id '<id>' --query-file '<path>' --execute --max-rows 100`
- `ktx agent wiki search '<query>' --json --project-dir /path/to/project`
- `ktx agent wiki read '<pageId>' --json --project-dir /path/to/project`
- `ktx agent sql execute --json --project-dir /path/to/project --connection-id '<id>' --sql-file '<path>' --max-rows 100`

Workflow tips

• Claude Code discovers skills automatically from .claude/skills/ — no restart needed after setup
• The MCP server starts on-demand when Claude Code first calls a KTX tool
• Use --semantic-compute to enable query planning and execution
• Global installation (~/.claude/skills/ktx/SKILL.md) makes KTX available in all projects without per-project setup

Cursor

Install via ktx setup

During setup, select Cursor from the agent targets. KTX writes:

Cursor supports project-scoped installation only.

Manual MCP configuration

Create or edit .cursor/mcp.json:

{
  "mcpServers": {
    "ktx": {
      "command": "ktx",
      "args": [
        "--project-dir", "/path/to/ktx-project",
        "serve",
        "--mcp", "stdio",
        "--semantic-compute",
        "--execute-queries"
      ],
      "env": {}
    }
  }
}

Manual CLI rules configuration

Create .cursor/rules/ktx.mdc with the same content structure as the Claude Code SKILL.md file — Cursor rules use the .mdc extension but support the same markdown format with command definitions.

Workflow tips

• After adding MCP config, restart Cursor or reload the window for the server to connect
• Cursor rules in .cursor/rules/ are automatically loaded into agent context
• MCP tools appear in Cursor's tool list once the server is running
• Project-scoped only — no global installation option

Codex

Install via ktx setup

During setup, select Codex from the agent targets. KTX writes:

Both project-scoped and global installations are supported. Global installs write to $CODEX_HOME/skills/ktx/SKILL.md (defaults to ~/.codex/skills/ktx/SKILL.md).

Manual MCP configuration

Create or edit .agents/mcp/ktx.json:

{
  "mcpServers": {
    "ktx": {
      "command": "ktx",
      "args": [
        "--project-dir", "/path/to/ktx-project",
        "serve",
        "--mcp", "stdio",
        "--semantic-compute",
        "--execute-queries"
      ],
      "env": {}
    }
  }
}

Manual CLI skills configuration

Create .agents/skills/ktx/SKILL.md with the same content structure as Claude Code's SKILL.md.

Workflow tips

• Set CODEX_HOME environment variable to customize the global installation directory
• Codex shares the .agents/ directory structure with the universal format — one install covers both
• Global installation makes KTX available across all Codex sessions

OpenCode

Install via ktx setup

During setup, select OpenCode from the agent targets. KTX writes:

OpenCode supports project-scoped installation only.

Manual MCP configuration

Create or edit .opencode/mcp.json:

{
  "mcpServers": {
    "ktx": {
      "command": "ktx",
      "args": [
        "--project-dir", "/path/to/ktx-project",
        "serve",
        "--mcp", "stdio",
        "--semantic-compute",
        "--execute-queries"
      ],
      "env": {}
    }
  }
}

Manual CLI commands configuration

Create .opencode/commands/ktx.md with the same command definitions as Claude Code's SKILL.md.

Workflow tips

• OpenCode reads commands from .opencode/commands/ on startup
• Project-scoped only — no global installation option
• Commands file uses standard markdown format (.md extension)

MCP server reference

All agent clients connect to the same KTX MCP server. The server exposes these tools:

Server flags

Security constraints

• SQL execution is always read-only
• Agent CLI SQL execution requires an explicit --max-rows limit from 1 to 1000; MCP semantic queries default to a 1000-row cap
• Secrets and credentials are never exposed in tool responses
• The server runs as a child process of the agent client (no network exposure)

Comparison