Workspaces and local MCP

The ICM workspace seam materializes an authorized Vault workspace into a credential-free local directory, then commits changed files back as immutable versions in one atomic operation.

Workspace commands

tv workspace init --name <workspace-name> [--json]
tv workspace import <path|zip> --name <workspace-name> [--json]
tv workspace checkout <workspace-id|unambiguous-name> --output <directory> [--json]
tv workspace walk-test <checkout-directory> [--json]
tv workspace commit <checkout-directory> --reason <text> [--json]

init creates a workspace from the bundled two-stage ICM starter. import accepts the same safe, bounded folder and ZIP inputs as template import but classifies the result as a workspace. checkout accepts workspaces only—templates remain immutable factories—and writes .thalix-workspace.json after every authorized current version has downloaded and verified. The manifest contains file/version/checksum/path identity only: no bearer token, storage key, signed URL, or secret.

walk-test scans without following symlinks, validates the ICM tree, and prints the exact bounded change plan without network mutation. commit requires --reason, rechecks live write access and every baseline version, uploads changed bytes to server-issued staging keys, and applies all new files/folders/versions in one transaction. A failed upload, checksum mismatch, permission change, or source-version race leaves the visible Vault tree unchanged.

Local stdio MCP

tv mcp serve
tv mcp serve --workspace <workspace-root-id> --stage <direct-stage-folder-id>

The Tier 1 MCP process uses the stable MCP v2 stdio protocol and delegates every operation to tv ... --json. It reuses the existing tv credential file; it creates no new token and never writes credentials into a workspace. Stdout is reserved exclusively for MCP JSON-RPC. Diagnostics go to stderr.

Unscoped mode exposes only identity and discovery operations: who-am-I, visible template discovery, and authorized workspace checkout. Scoped mode reads the selected stage's direct CONTEXT.md and intersects its declared tools with the caller's effective inherited read, write, or manage rank. Every eventual tv command still performs normal backend authorization against its actual target; visibility never grants access.

A stage declares policy in exact YAML frontmatter:

---
mcp:
  tools:
    - vault_file_info
    - vault_file_find
    - vault_workspace_walk_test
    - vault_workspace_commit
---

Unknown, duplicate, malformed, aliased, oversized, or missing policy fails closed. Scope state is version-bound and briefly cached; the server checks state before each tool listing/call, sends a tool-list-changed notification on a real change, and refuses stale hidden calls before spawning tv. Each resolution/change writes bounded append-only scope evidence containing workspace, stage, contract version, effective rank, visible names, hidden count, result, reason, and correlation ID—never contract bytes, credentials, or local paths.

MCP client configuration

tv mcp install [--target <claude-code|claude-desktop|cursor|all>] registers the local stdio server in each host's config file (~/.claude.json, Claude Desktop's claude_desktop_config.json, ~/.cursor/mcp.json). The entry is command + args only -- never a credential. tv mcp uninstall removes it; tv mcp doctor reports registration and session state. For a host tv mcp install does not target, build or install tv, authenticate once with tv login, and point the client at the same executable with this equivalent manual entry:

{
  "mcpServers": {
    "thalix-vault": {
      "command": "tv",
      "args": [
        "mcp",
        "serve",
        "--workspace",
        "<workspace-root-id>",
        "--stage",
        "<direct-stage-folder-id>"
      ]
    }
  }
}

Omit both scope arguments for discovery-only mode. They are an all-or-nothing pair.

Security boundary

Tier 1 is local stdio only. There is no hosted agent runtime, public MCP endpoint, service account, or permanent storage credential. Hosted MCP remains a separate Tier 2 decision requiring a new auth and security review. See ADR-0007.