tsafe-mcp

Bound-contract MCP server for tsafe and the Agent Authority Firewall. It speaks MCP over stdio (JSON-RPC 2.0, protocol version 2025-06-18) to MCP-aware hosts (Claude Desktop, Cursor, Continue, Windsurf, Codex) while keeping secret material out of model context.

tsafe-mcp is a companion binary used by the tsafe mcp ... command surface. It is intended to sit beside tsafe-agent in installs or bundles that include companion processes. Distribution depends on the install channel you choose; this README only describes the current crate behavior.

tsafe-mcp is stdio JSON-RPC, not a network daemon and not product telemetry. It returns plans, bounded command output, and safe authority metadata. It does not return secret values.

Install or build

cargo build -p tsafe-mcp

If your Cargo registry or install channel provides the companion crate:

cargo install tsafe-mcp

The meta-crate path can also provide companion binaries when that install channel includes them. The tsafe-cli mcp feature resolves tsafe-mcp at runtime from TSAFE_MCP_BIN, beside the tsafe executable, or from PATH.

Bind one profile, contract, and workdir per server

Each supported tsafe-mcp process is bound to exactly one tsafe profile, one authority contract, and one workdir at startup. Request-time profile, contract, or scope switching is rejected (thin-stance "one server = one authority boundary"). Run multiple processes if you need multiple profiles or contracts.

The CLI normal form is:

tsafe mcp serve --profile <profile> --contract <contract> --workdir <repo>

The direct companion-binary normal form is equivalent:

tsafe-mcp serve \

  --profile cordance \

  --contract cordance-mcp \

  --workdir <cordance-repo>

A running tsafe-agent is required when an operation needs vault unlock state. Unlock first for secret-injecting contracts:

eval $(tsafe agent unlock --ttl 8h)

Safe status can report the agent and locked state without returning secret material. Commands that require unlock state fail with a structured resolution that tells the operator to run tsafe agent unlock.

Separate server instance normal forms

Give each agent context a distinct host-visible name and server process. For example, tsafe-cordance and tsafe-cortex should be separate entries with their own profile, contract, workdir, audit stream, and process. They are not two request-time modes inside one server.

Per-host config

tsafe mcp config codex emits a safe Codex MCP entry without secret values:

tsafe mcp config codex \

  --name tsafe-cordance \

  --profile cordance \

  --contract cordance-mcp \

  --workdir <cordance-repo>

tsafe mcp config codex \

  --name tsafe-cortex \

  --profile cortex \

  --contract cortex-mcp \

  --workdir <cortex-repo>

tsafe mcp install <host> remains available for host writers that merge into existing configs. It refuses to write without an explicit --allowed-keys or --contract. Prefer the contract + workdir form for model-facing ecosystem commands.

Bound contract tool surface (3 tools)

The bound surface does not expose tsafe get, tsafe export, profile switching, contract switching, or bulk vault inspection. run_contract_command always uses --mode hardened, --redact-output, and timeout enforcement. Contracts with zero required and zero allowed secrets are valid for diagnostic commands; they inject no vault secrets while still enforcing target policy.

tsafe_mcp_status reports safe metadata about the bound profile, contract, workdir, agent state, and compiled capabilities. Current bound status returns secret counts and keeps secret-name arrays empty; it never returns secret material.

Audit

Bound command runs go through tsafe exec --contract, so successful runs and recorded failures use the same profile audit story as CLI execution. Audit append failures are currently best-effort, matching the CLI exec path. show_exec_plan is a preview path and does not yet have a separate mandatory bound-plan audit row. The legacy action-shaped tools append MCP rows to the profile's .audit.jsonl:

operation: exec | mcp.status | mcp.shutdown
source:   the --audit-source value (default: mcp:unknown:<pid>)

Audit rows reuse the existing tsafe-core::audit::AuditLog chain where the tool path writes them, so they appear in the same operator narrative as tsafe exec.

Doctrine pointers

• docs/architecture/ADR-006-mcp-server.md — decision record.
• docs/architecture/mcp-server-design.md — concrete shape (crate layout, tool schemas, error codes, host configs, test posture).
• docs/research/thin-mcp-stance-2026-05.md — thin-stance, one-profile-per-server.
• docs/decisions/agent-publish-topology.md — companion-binary publish model.

Out of scope for v1

• HTTP/SSE transport — stdio only.
• Multi-profile per process — refused at startup; run one process per profile.
• tsafe_get / tsafe_set / tsafe_delete / tsafe_export tools — direct thin-stance violation, not part of the default or opt-in surface.

License

Same as the tsafe workspace — see the repository root.