Use the same MARS actions from agents, CLI, and MCP.

Ways To Use Tools

Use tools when you want a repeatable action with the same repo path, trust rules, JSON input, and output limits that agents use.

List Tools

Use tools list when you need to see what the installed binary actually exposes. The JSON form is the best input for another model, MCP adapter, or local integration.

mars tools list

mars tools list --json

Run A Tool From The CLI

tools run executes one tool with JSON object arguments. It resolves the repository root, applies the requested trust level, enforces output limits, and returns either formatted model output or structured JSON.

mars tools run git_status \
  --repo ~/my-project \
  --args-json '{}' \
  --json

mars tools run grep \
  --repo ~/my-project \
  --args-json '{"pattern":"MarsDocSync","glob":"**/*.go"}'

mars tools run record_decision \
  --repo ~/my-project \
  --trust contributor \
  --execution-profile host \
  --acknowledge-host-execution \
  --args-json '{"title":"Use local model override","decision":"Route engineer to repo-coder for validation."}'

mars tools run file_read \
  --repo ~/my-project \
  --max-output-bytes 6000 \
  --args-json '{"path":"README.md"}'

MCP Server

mars mcp serve starts a newline-delimited JSON-RPC stdio MCP server. Configure an MCP-compatible client to launch the command locally. The server exposes tools/list and tools/call against the MARS tool registry.

mars mcp serve \
  --repo ~/my-project \
  --trust observer \
  --role mcp-client

mars mcp serve \
  --repo ~/my-project \
  --trust contributor \
  --execution-profile host \
  --acknowledge-host-execution \
  --role mcp-client \
  --allowlist file_read,grep,mars_cli,git_status,record_decision

{
  "mcpServers": {
    "mars": {
      "command": "mars",
      "args": [
        "mcp",
        "serve",
        "--repo",
        "/absolute/path/to/my-project",
        "--trust",
        "observer"
      ]
    }
  }
}

Trust And Allowlists

MARS applies three separate gates: execution profile must admit the authority, trust must permit the action, and the tool must be exposed by the allowlist. Role runs also use the role's manifest allowlist; target configuration cannot grant host authority.

mars trust --repo ~/my-project

mars trust set engineer ~/my-project contributor \
  --reason "Human approved bounded write access"

Built-In Tool Categories

The exact installed set is authoritative from mars tools list. These categories explain how users should think about the built-in surface.

Tool Selection Rules

Users and external agents should choose the most specific governed capability that fits the job. This makes runs easier to audit and keeps safety policy effective.

Tool Creation

Repeated, risky, validation-heavy, or likely-to-recur procedures should become first-class tools instead of staying as chat memory or ad hoc shell scripts. New built-in tools must originate through tool_create unless a prior durable decision explains why the meta-tool path was bypassed.

1. Confirm the trigger

   Create a tool when the process is repeated, risky, validation-heavy, or broadly reusable across foundation and deployed harnesses.

2. Run the meta-tool

   mars tools run tool_create \
     --repo . \
     --trust contributor \
     --execution-profile host \
     --acknowledge-host-execution \
     --args-json '{"tool_name":"example_tool"}'

3. Finish implementation and tests

   Complete the generated Go implementation, registration, trust policy, allowlists, tests, and documentation.

4. Validate the path

   mars tools run tool_creation_guard \
     --repo . \
     --args-json '{"tool_name":"example_tool"}'

External AI Clients

External clients should treat MARS as the source of tool truth rather than recreating local shell shortcuts. Use observer profile for read-only support and acknowledged host plus contributor trust only when the client should mutate the repo.

Troubleshooting