Skip to main content

One command contract across the CLI and MCP

Share one local Kam contract while your AgentCore application owns execution.

Local candidate · in reviewReviewed 2026-10-14 · prelaunchRead this guide as Markdown
Guide context

How local CLI and MCP tools share Kam's contracts and bounded reads while AgentCore execution stays with the application runtime.

Understand the local tools used to prepare an AgentCore State integration. The CLI and read-only MCP surface share command definitions and bounded file reads. Their local filesystem contract is separate from deployed runtime permissions, model calls and tool execution.

On this page · 3 sections

Keep development tools and runtime separate

  1. Share the command contract

    The local CLI and MCP use one definition for the same operation.

  2. Inject bounded reads

    Read handlers have no writer, credential, shell or network capability.

  3. Integrate explicitly

    AgentCore tooling and application code own the deployed connection.

The same operation has one owner#

  1. One command contract

    CLI options, help, and the explicit MCP subset come from one typed Rust catalog. This avoids maintaining separate command definitions for each interface. A new CLI command is not automatically an agent tool.

  2. One application read path

    The CLI and MCP share query handlers for local configuration, diagnostics, replay, and Atlas. Only their transport envelopes differ.

  3. One bounded operation context

    Each operation shares captured immutable file buffers and a normalized View index. The next request gets a fresh capture, not a global customer-state cache.

  4. Read-only dependency injection

    Read handlers receive a bounded ProjectReader with no writer, credential, shell, or network capability. The real Rust engine remains the decision owner.

  5. Protected generation

    Writes require --write. Planning and commit share conflict rules; changed configuration or managed guidance aborts the old plan.

  6. Two independent artifacts

    The service and native toolkit are packaged separately and tested without source or network. Local evidence is not a production release or live service guarantee.

Borrow one View; capture one operation#

A ProjectSnapshot keeps one normalized manifest and an ID-to-position index beside its ordered View payloads. Handlers borrow the selected View rather than copying it into another state store.

Each ReadSession shares immutable file buffers, misses, and errors within one operation. The limits are 128 file/presence observations, 2 MiB total captured content, and 300 KiB per file. Every subsequent MCP call gets a fresh capture.

This is not an atomic cross-file snapshot, a global tenant cache, a database migration, or a constant-time historical reconstruction guarantee. Only immutable embedded SDK/OpenAPI assets are shared process-wide.

Inject reads, not permission to do everything#

ProjectReader exposes bounded reads and presence checks. It has no writer, credential, shell, or network operation. Tests inject in-memory readers with counters and failures; production uses a checked filesystem adapter.

The canonical hashes and History/State engine are not replaceable through that interface. Local writes retain their source observations, acquire a cooperating-writer lock, recheck inputs, and re-plan against current target bytes. Changed config or guidance aborts a stale plan.

These controls protect cooperating local workflows. They do not claim an atomic multi-file transaction or a sandbox against a malicious filesystem owner.

Agent-readable documentation manifest