MCP tools

istok mcp runs the MCP server your coding agent talks to. This page lists its flags and every tool it exposes. To connect an agent, follow the Quick start.

Running the server

istok mcp --actor-id codex --actor-name "Codex"

The server speaks MCP over standard input and output; the MCP client starts the command and talks to the process directly. Stdout is reserved for the protocol.

A flag takes precedence over its environment variable. The MCP workflow requires a file-backed database. See Configuration.

Project scope

Each server process resolves the directory it was started in to a project and keeps that scope for its lifetime. With nested projects, the closest one wins.

Tools cannot pass another project root, filesystem root, or project selector, so an agent cannot redirect a call to a different project. That is also why one global MCP configuration works for every registered repository: each started process serves the repository it was launched in.

If the directory is not registered yet, the agent can call project_init, available in every profile. It registers the server’s startup directory, accepts an optional project name, and returns the existing project if the directory is already registered. Whether an agent may do this on its own is up to your agent instructions; the recommended ones in the Quick start register a repository only when you ask.

Actor identity

Every server process has exactly one actor: the logical agent doing the work, not a particular conversation. It is fixed at startup, and individual tool calls cannot override it.

Runs record their actor, and validations and artifacts carry it too. Give each agent its own stable ID, for example claude for Claude Code and codex for Codex, so you can tell their work apart across restarts. Without --actor-id, Istok generates a unique identity for that process only.

The actor also matters for ownership: heartbeats, recovery, and finishing a run are checked against the actor that owns the run and its current lease. See Several agents, one project.

Tools

Project

health
project_current
project_init

Tasks

task_create
task_update
task_list
task_show
task_ready
task_comment
task_progress
task_block
task_unblock
task_dependency_add
task_dependency_remove

Context

context_add
context_update
context_enable
context_disable
context_list
context_show
context_search
context_package
context_preview
context_doctor

context_preview shows the bounded context a claim of a task would receive without creating a run. context_doctor reports context growth and lifecycle issues. See istok context.

Knowledge

knowledge_catalog
knowledge_search
knowledge_show
knowledge_read
knowledge_create
knowledge_distill
knowledge_update
knowledge_review
knowledge_promote
knowledge_supersede

Catalog and search return metadata and short snippets; knowledge_show and knowledge_read return one complete item. Review, promotion, and supersession are separate explicit steps. Exporting to a file is available only through the CLI.

Code retrieval

index_status
index_rebuild
search
graph_symbol
graph_neighbors
graph_path

search and graph reads check index freshness before reading. These tools do not accept a project or repository-root override.

Runs and validation

task_claim
run_list
run_show
run_exec
run_validate
run_heartbeat
run_artifact_list
run_artifact_verify
run_recover
run_finish
task_complete

task_claim assembles bounded context (saved context, code retrieval, and a knowledge briefing) and creates the run through the same workflow as the CLI. Its response includes the run and the exact context snapshot stored for it, so the agent does not have to search and rebuild its starting context by hand.

run_exec and run_validate work like their CLI equivalents. The caller supplies the command and bounded execution options, but not an environment: managed commands get the allowlisted environment captured by the server plus Istok’s runtime variables. See istok run.

For work that did not go through run_exec or run_validate, these tools record executions and attested validations after the fact:

execution_start
execution_finish
validation_record

Profiles

Profiles control which tools an agent gets. The standard setup needs none: the default is worker.

istok mcp --profile supervisor --actor-id claude --actor-name "Claude Code"

• worker — the normal workflow: project inspection and project_init, tasks, context including preview and diagnostics, knowledge, code retrieval, claiming, execution and validation, run recovery, and task completion.
• supervisor — everything in worker, plus run_abandon to end an active run while leaving its task open.
• admin — everything in supervisor, plus:

project_list
project_rename
project_rebind
project_delete
project_restore
task_delete
task_restore
context_archive

project_rebind and project_restore bind the project to the server’s startup directory. project_delete requires the project ID to be repeated as confirmation.

Every profile can recover a run, but only when the caller is the actor that owns its lease; recovery cannot take over another actor’s run. Use elevated profiles only when the agent actually needs them.

Results

MCP results use versioned structured envelopes (schema_version: "1"); run results use "2", and retrieval and graph payloads carry their own contract versions. Empty collections are returned as [], never null. See JSON output.

Configuration versus instructions

The MCP configuration makes the tools available and fixes the project and actor. It does not tell the agent when to create a task, when a small request can go untracked, whether it may register a repository, or how to validate work. Those rules belong in your agent’s instructions; the recommended starting set is in the Quick start.