MCP

istok mcp starts the local MCP server that exposes Istok workflows to coding agents.

For the normal setup, start the server with a stable actor identity:

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

The actor identity lets Istok associate recorded work with the agent that performed it.

See the Quick start for setup examples for Codex, Claude Code, Antigravity CLI, and Cursor.

stdio transport

Istok exposes its MCP server over standard input and output.

The MCP client starts the configured command and communicates with that process directly.

For example:

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

The server’s stdout is reserved for the MCP protocol.

Project scope

An MCP server process is scoped to the repository it starts in.

At startup, Istok resolves and fixes the working root used by the server. Tools exposed through that process operate inside that project scope.

The agent cannot pass another project root, filesystem root, or project selector to redirect individual tool calls to another Istok project.

Conceptually:

Agent session
     ↓
MCP configuration
     ↓
istok mcp
     ↓
startup repository
     ↓
Istok project
     ↓
tasks / context / runs / retrieval

This allows the same global MCP configuration to be used across repositories. Each MCP process resolves the repository it starts in and remains scoped to that project.

Project discovery

The agent can inspect the current project through MCP.

If the repository is already registered with Istok, subsequent tools operate on that project.

A project can also be initialized through the MCP surface, but whether an agent should do this automatically is a workflow decision rather than an MCP requirement.

The recommended agent instructions in the Quick start ask the agent to request permission instead of initializing arbitrary repositories automatically.

Actor identity

Every MCP server process has one actor identity.

The actor represents the agent performing operations through that MCP process.

Set a stable actor ID with:

istok mcp --actor-id codex

or with the environment variable:

ISTOK_AGENT_ID

The actor ID remains stable across MCP restarts when you configure the same value again.

You can also provide a human-readable actor name:

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

or:

ISTOK_AGENT_NAME

The two values serve different purposes:

For example, you might configure:

Codex
actor ID: codex

Claude Code
actor ID: claude

Work performed through those MCP configurations can then remain attributable to the corresponding actor in Istok state.

A run records its actor, and validation and artifact records also carry actor identity.

Conceptually:

Task
 │
 ├── Run
 │    actor: codex
 │    └── validation
 │
 └── Run
      actor: claude
      └── validation

An actor identifies the logical agent performing the work, not a particular conversation. Reusing the same actor ID across restarts therefore keeps that identity stable while individual runs remain separate attempts.

Generated actor identities

If --actor-id or ISTOK_AGENT_ID is not provided, Istok generates a unique actor identity for the current MCP process.

That is useful when persistent attribution is not important.

For a regular coding-agent setup, a stable actor ID is easier to recognize in durable project history.

Actor scope

The actor identity is fixed when the MCP server starts.

Individual MCP tool calls cannot override the actor.

The same identity is therefore used consistently for operations performed through that process.

This also matters for run ownership. Operations such as heartbeat and finishing an active run are checked against the actor that owns the run together with its current lease.

Tool surface

MCP exposes the core Istok workflows that coding agents use.

The available tools cover several areas.

Project

Agents can inspect the current project and, when appropriate, initialize the repository.

Typical project tools include:

health
project_current
project_init

Broader project management is available through elevated MCP access.

Tasks

Task tools let an agent create and manage durable work:

task_create
task_update
task_list
task_show
task_ready
task_comment
task_progress
task_block
task_unblock
task_dependency_add
task_dependency_remove

The normal agent workflow is to inspect existing work before creating a new task, claim the task before implementation, and preserve meaningful progress while working.

Context

Agents can inspect and manage durable project context:

context_add
context_update
context_enable
context_disable
context_list
context_show
context_search
context_package

These tools operate only inside the project fixed when the MCP server starts.

Repository retrieval

MCP exposes the local repository retrieval surface:

index_status
index_rebuild
search
graph_symbol
graph_neighbors
graph_path

Retrieval tools do not accept a project or repository-root override.

search and graph reads ensure repository freshness before reading from the index.

Runs and validation

Agents can manage the execution lifecycle associated with task work:

task_claim

run_list
run_show
run_exec
run_validate
run_heartbeat
run_artifact_list
run_artifact_verify
run_recover
run_finish

task_complete

These tools allow an agent to move from a durable task to an active run, perform managed work, preserve validation evidence, and complete the task.

Lower-level execution and validation tools are also exposed for workflows that need them.

For normal coding-agent work, managed run_exec and run_validate are the preferred execution path.

Task claim and context

task_claim is an important part of the agent workflow.

When an agent claims a task, Istok prepares the relevant project and repository context and creates the run through the same application workflow used by the CLI.

The MCP response includes the created run together with the exact context snapshot stored for that attempt.

Conceptually:

task_claim
    ↓
project context
    +
repository retrieval
    ↓
Context snapshot
    +
Run
    ↓
agent starts implementation

Task state remains associated with the task itself rather than being copied into the context snapshot.

The agent therefore does not need to manually perform a search sequence and then reconstruct the starting context for the run.

Run ownership

Run operations are always scoped to the current project.

Operations that continue or finish owned work require the current actor and lease where applicable. This includes the normal execution, validation, heartbeat, recovery, and finish lifecycle.

Elevated profiles can expose additional management operations such as run_abandon.

Profiles

Istok supports MCP profiles for cases where you want to control the tool surface available to an agent:

istok mcp --profile worker
istok mcp --profile supervisor
istok mcp --profile admin

You do not need to select a profile for the standard setup described in the Quick Start.

Profiles are primarily useful when you intentionally want to expose additional management capabilities.

Actor configuration can be combined with a profile:

istok mcp \
  --profile worker \
  --actor-id codex \
  --actor-name "Codex"

Worker

Worker access covers the normal coding-agent workflow:

• current project inspection;
• task management;
• project context;
• repository retrieval;
• task claiming;
• run execution and validation;
• run recovery;
• task completion.

Supervisor

Supervisor includes the normal workflow and can additionally abandon an active run.

Abandoning a run ends that attempt while leaving the task open for another attempt.

Admin

Admin exposes broader project and destructive management operations in addition to the normal workflow.

This includes project-management operations and additional task and context maintenance tools.

Use elevated profiles only when the agent actually needs those capabilities.

Run recovery

All profiles can recover a run when the recovery belongs to the current lease-owner actor.

Recovery rotates the run lease while preserving the existing run.

The caller cannot use recovery to take over another actor’s run arbitrarily.

Managed execution

run_exec and run_validate use the same managed execution workflow as their CLI equivalents.

An MCP caller supplies the command arguments and bounded execution options, but does not provide an arbitrary process environment.

Managed commands receive the allowed environment captured by the server together with Istok runtime variables.

See run for the corresponding CLI lifecycle.

Custom database

The MCP server can use a custom Istok database:

istok mcp --database /path/to/istok.db

or:

ISTOK_DATABASE

The managed MCP workflow requires a file-backed database.

See Configuration for data paths and configuration details.

Structured results

MCP results use versioned structured envelopes.

Different Istok domains can carry their own payload schema versions, including run, retrieval, and graph results.

Collection results are represented as empty arrays when there are no items rather than null.

See JSON output for the related structured-output conventions.

MCP configuration and agent instructions

MCP configuration and agent instructions solve different problems.

MCP configuration
→ makes Istok tools available
→ establishes project and actor scope

Agent instructions
→ tell the agent when and how to use those tools

Configuring:

istok mcp --actor-id codex

does not by itself tell Codex when to create a task, when a small request can remain untracked, whether a repository may be initialized automatically, or how work should be validated.

Those workflow rules belong in the coding agent’s instructions.

The recommended starting configuration is covered in the Quick start.

Command help

Inspect the exact MCP options supported by your installed version with:

istok mcp --help

Next

Continue with Configuration for database paths and environment-based configuration.