ktx/docs-site/content/docs/integrations/agent-clients.mdx

---
title: Agent Clients
description: Set up KTX with Claude Code, Cursor, Codex, and OpenCode.
---

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.

## Agent setup matrix

Use this table to choose the setup path before editing client-specific files.

| Target | Project-scoped files | Global install | Recommended mode | Reload needed |
|--------|----------------------|----------------|------------------|---------------|
| Claude Code | `.claude/skills/ktx/SKILL.md`, `.mcp.json` | Yes | Both CLI skill and MCP | Skill reload is automatic; MCP starts on first use |
| Cursor | `.cursor/rules/ktx.mdc`, `.cursor/mcp.json` | No | Both CLI rule and MCP | Reload the Cursor window after MCP config changes |
| Codex | `.agents/skills/ktx/SKILL.md`, `.agents/mcp/ktx.json` | Yes | Both CLI skill and MCP | Start a new session after global skill changes |
| OpenCode | `.opencode/commands/ktx.md`, `.opencode/mcp.json` | No | Both CLI command and MCP | Restart OpenCode after config changes |

The safest generated command is:

```bash
ktx setup --agents --target codex --agent-install-mode both --project
```

Replace `codex` with `claude-code`, `cursor`, `opencode`, or `universal`.

## Claude Code

### Install via `ktx setup`

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

| Mode | File |
|------|------|
| CLI skills | `.claude/skills/ktx/SKILL.md` |
| MCP server | `.mcp.json` (under `mcpServers.ktx`) |

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:

```json title=".mcp.json"
{
  "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`:

```markdown title=".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:

| Mode | File |
|------|------|
| CLI rules | `.cursor/rules/ktx.mdc` |
| MCP server | `.cursor/mcp.json` (under `mcpServers.ktx`) |

Cursor supports project-scoped installation only.

### Manual MCP configuration

Create or edit `.cursor/mcp.json`:

```json title=".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:

| Mode | File |
|------|------|
| CLI skills | `.agents/skills/ktx/SKILL.md` |
| MCP server | `.agents/mcp/ktx.json` (under `mcpServers.ktx`) |

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`:

```json title=".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:

| Mode | File |
|------|------|
| CLI commands | `.opencode/commands/ktx.md` |
| MCP server | `.opencode/mcp.json` (under `mcpServers.ktx`) |

OpenCode supports project-scoped installation only.

### Manual MCP configuration

Create or edit `.opencode/mcp.json`:

```json title=".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:

| Tool | Description |
|------|-------------|
| `connection_list` | List configured database connections |
| `connection_test` | Test a database connection |
| `knowledge_search` | Semantic + full-text search across knowledge pages |
| `knowledge_read` | Read a specific knowledge page |
| `knowledge_write` | Write or update a knowledge page |
| `sl_list_sources` | List semantic layer sources |
| `sl_read_source` | Read a semantic source definition |
| `sl_write_source` | Write or update a semantic source |
| `sl_validate` | Validate a source against the database schema |
| `sl_query` | Execute a semantic layer query |
| `ingest_trigger` | Trigger an ingestion run |
| `ingest_status` | Check ingestion status |
| `ingest_report` | View an ingestion report |
| `ingest_replay` | Replay a past ingestion session |
| `scan_trigger` | Trigger a structural, enriched, or relationship scan |
| `scan_status` | Check scan status |
| `scan_report` | View a completed scan report |
| `scan_list_artifacts` | List artifacts produced by a scan |
| `scan_read_artifact` | Read a scan artifact |
| `memory_capture` | Capture reusable context from an agent conversation when memory capture is enabled |
| `memory_capture_status` | Check a memory capture run |

### Server flags

| Flag | Description | Default |
|------|-------------|---------|
| `--project-dir` | KTX project directory; otherwise KTX uses `KTX_PROJECT_DIR`, the nearest `ktx.yaml`, or the current directory | Auto-detected |
| `--mcp stdio` | Transport mode (stdio only) | Required |
| `--semantic-compute` | Enable semantic layer queries | `false` |
| `--execute-queries` | Allow read-only SQL execution | `false` |
| `--semantic-compute-url` | Remote compute endpoint URL | — |
| `--database-introspection-url` | Live schema introspection endpoint | — |
| `--memory-capture` | Record agent interactions | `false` |
| `--memory-model` | LLM model for memory processing | — |

### 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

| | Claude Code | Cursor | Codex | OpenCode |
|---|---|---|---|---|
| MCP support | Yes | Yes | Yes | Yes |
| CLI skills | Yes | Yes (.mdc) | Yes | Yes |
| Global install | Yes | No | Yes | No |
| Config location | `.mcp.json` | `.cursor/mcp.json` | `.agents/mcp/ktx.json` | `.opencode/mcp.json` |
| Skills location | `.claude/skills/` | `.cursor/rules/` | `.agents/skills/` | `.opencode/commands/` |

## Common errors

| Error or symptom | Likely cause | Recovery |
|------------------|--------------|----------|
| Agent cannot start MCP server | The config points to a missing `ktx` binary | Run `pnpm run link:dev`, rerun `ktx setup --agents`, or use an absolute command path |
| Agent sees MCP tools but queries fail | Server args omit `--semantic-compute` | Add `--semantic-compute`; add `--execute-queries` only when read-only execution is intended |
| Agent reads the wrong KTX project | `--project-dir` or `KTX_PROJECT_DIR` points at another directory | Regenerate project-scoped config from the intended project directory |
| CLI skill commands return non-JSON output | The generated command omitted `--json` or an agent changed it | Restore the generated skill/rule and ensure every `ktx agent` command includes `--json` |
| Cursor or OpenCode does not show new tools | The client has not reloaded its MCP config | Reload the app window or restart the agent client |