TIENDocumentation
Docs/Workflows

AI agent integration

Tien includes a local Model Context Protocol server. Codex, Claude Code, Cursor, Copilot, and other MCP-compatible coding agents can invoke Tien through typed tools instead of assembling shell pipelines themselves.

The server runs over standard input and output. Repository code stays on the machine, every repository path is restricted to an operator-selected root, evidence strings are excluded by default, and every public URL target needs an exact-host, scoped, expiring authorization.

Start the MCP server

Build or install Tien, then run it from the repository you want the agent to review:

tien mcp --root .

The command speaks MCP over stdio, so it is normally started by the coding agent rather than left running in a terminal.

Available server flags:

  • --root <dir>: only this directory and its descendants can be scanned or read by MCP tools.
  • --config <path>: operator-owned scan configuration and URL authorization policy. It is loaded once at startup and cannot be replaced by an agent tool call. A selected missing, unreadable, or invalid path fails startup instead of falling back to defaults.

Generic MCP client configuration

Most MCP clients accept a command plus arguments. Use an absolute binary and repository path when the client does not start inside the project:

{
  "mcpServers": {
    "tien": {
      "command": "/absolute/path/to/tien",
      "args": [
        "mcp",
        "--root",
        "/absolute/path/to/your-app"
      ]
    }
  }
}

The location and shape of the MCP configuration file vary by client. Keep the command and arguments equivalent even when the surrounding configuration format differs.

For MCP scanning, place the complete operator config outside files the coding agent can edit:

{
  "mcpServers": {
    "tien": {
      "command": "/usr/local/bin/tien",
      "args": [
        "mcp",
        "--root",
        "/absolute/path/to/your-app",
        "--config",
        "/absolute/path/to/operator/tien.yaml"
      ]
    }
  }
}

Neither scan tool accepts a per-call config_path. Repository engines, images, extra arguments, and executable plugins are part of the operator policy because a project-supplied config could otherwise turn a scan into arbitrary local command execution.

MCP tools

tien_capabilities

Returns the active root, server version, tool list, repository engines, finding fields, result policy, URL authorization policy, and recommended workflow. Agents should call it before the first scan.

tien_scan_repo

Runs the configured repository engines locally.

Arguments:

  • path: repository directory relative to the MCP root; defaults to ..
  • min_severity: info, low, med, high, or crit.
  • max_findings: optional presentation limit; zero or omission returns every matching finding.
  • include_evidence: returns evidence strings only when explicitly set to true.

The structured result includes schema version, source, target, counts, truncation state, severity totals, top issue IDs, normalized findings, warnings from partial engine failures, and recommended next steps.

tien_diff_scans

Compares two existing .tien, .gob, or .jsonl artifacts inside the MCP root.

Arguments:

  • baseline_path: reviewed baseline artifact.
  • current_path: new artifact.
  • input_format: optional gob or jsonl override.
  • max_findings: optional presentation limit for new, fixed, and changed groups; zero returns all.
  • include_evidence: excluded by default.

The result reports new, fixed, and severity- or confidence-changed findings. Existing artifacts can be produced by a person, CI, or the normal Tien CLI.

tien_scan_url

This tool is always discoverable, but execution fails closed unless the operator-owned policy fields loaded at startup authorize the complete request:

  • the agent must provide an explicit target array;
  • MCP does not impose a target-count ceiling;
  • only HTTP and HTTPS are accepted;
  • every public hostname requires a structured DNS TXT grant;
  • the grant binds the exact hostname, url-scan scope, 256-bit challenge, issue time, and expiry;
  • all targets pass preflight before workers, cache reads, or built-in requests run;
  • localhost and literal private IPs are blocked unless the operator enables their explicit development exemptions;
  • a hostname that resolves to RFC 1918 or IPv6 ULA space must appear exactly in allow_resolved_private_hosts, use an HTTPS target, present its exact DNS TXT grant, and keep its resolved addresses pinned;
  • if the earliest grant expires during execution, the run fails authorization and MCP returns a tool error rather than partial success;
  • redirects must remain on the same origin;
  • response size, retries, time, and concurrency remain configurable resource budgets.

The url-scan scope covers only Tien's built-in GET/HEAD checks. A batch containing any public target fails closed when a URL plugin is enabled. URL plugins can currently run only for explicitly proof-exempt literal localhost or private-IP development targets. Tien does not sandbox a plugin process or its DNS/network behavior; use reviewed read-only plugins with an independent egress policy, and expect MCP to mark a plugin-backed scan tool as potentially destructive.

DNS TXT proof is a cooperative operational signal, not legal or contractual authorization. It does not replace written permission or rules of engagement, and a modified binary or fork can remove it.

Example server command:

tien mcp \
  --root /absolute/path/to/your-app \
  --config /absolute/path/to/operator/tien-url.yaml

Generate the authorization with tien authorize dns --domain app.example.com; repeat --domain in one command for multi-host batches. DNS TXT is the only supported authorization method. A hostname that resolves to RFC 1918 or IPv6 ULA space additionally requires an HTTPS target and an exact allow_resolved_private_hosts entry; Tien pins the resolved addresses during preflight.

Agent workflow

Give the agent this operating contract:

## Security checks with Tien

- Call `tien_capabilities` before the first review.
- Run `tien_scan_repo` only inside the configured repository root.
- Treat every finding as evidence to verify against the actual code.
- Keep `include_evidence` false unless the evidence is necessary and safe to expose in the agent session.
- Prioritize critical and high findings, then medium findings with a plausible attack path.
- Group related findings by root cause instead of editing each symptom independently.
- Before changing code, explain the cause and the smallest safe change.
- Run targeted project tests after the change.
- Scan again and compare fingerprints or use `tien_diff_scans` with saved artifacts.
- Report fixed, remaining, new, deliberately filtered, and unverified findings separately.
- Do not weaken rules, add broad exclusions, expand the MCP root, or change authorization policy just to make a check pass.
- A human decides whether the application is ready to ship.

Structured finding contract

MCP responses use schema_version: "2". Each returned finding can include:

  • id: stable check or engine rule identifier;
  • target: affected file, line, package, or URL;
  • severity: potential impact from info to crit;
  • confidence: strength of the observed signal;
  • description: why the signal matters;
  • evidence: omitted unless explicitly requested;
  • remediation: direct guidance that still needs code review;
  • fingerprint: stable identity for deduplication and comparisons;
  • tags: engine, rule, CWE, OWASP, or category context;
  • timestamp and run_id: scan provenance.

Agents should not rank work by severity alone. Confidence, reachability, exposed surface, existing controls, and business context also matter.

CLI fallback

Agents without MCP support can use the same local pipeline through shell commands:

mkdir -p .tien
tien scan repo --path . --format jsonl > .tien/repo.jsonl
tien report --input-format jsonl --type json .tien/repo.jsonl > .tien/report.json
tien report --input-format jsonl --type md --group-by severity .tien/repo.jsonl > .tien/report.md

For a before-and-after review:

tien scan repo --path . > .tien/before.tien
# agent inspects, edits, and tests the app
tien scan repo --path . > .tien/after.tien
tien diff .tien/before.tien .tien/after.tien > .tien/diff.txt

Generated artifacts can contain sensitive architecture details. Add .tien/ to .gitignore unless the team intentionally versions a reviewed baseline or sanitized report.

Trust boundary

The MCP server is local and has no hosted Tien control plane. The server operator chooses the binary, root, engines, images, plugins, and URL authorization policy fields loaded at startup. An agent tool call can request fewer findings for presentation, but cannot replace those fields, reduce scan coverage, replace authorization, or bypass the all-target preflight. This is not an immutable execution snapshot: referenced rule files, plugin binaries, ignore files, advisory data, and mutable image tags can drift independently. Keep them outside agent-writable roots where practical, protect their permissions, and pin versions or digests. External scanners, plugins, the MCP client, and the coding agent remain separate trust boundaries.