Skip to main content

​
What does --mcp do?

The --mcp flag starts the CLI as a Model Context Protocol (MCP) stdio server. AI assistants connect to it over standard input/output and call Mandate commands as structured tools. No HTTP server, no port binding: the transport is stdio. 
npx @mandate.md/cli --mcp

​
Exposed tools

The MCP server exposes two tools:
ToolDescription
searchLook up validation schemas, command usage, and examples. Read-only, no auth needed.
executeCall any Mandate CLI command (validate, transfer, event, status, approve). Requires a runtime key.
The search tool helps agents discover how to use Mandate before they have credentials. The execute tool runs real commands against the API.

​
Client configuration

​
Claude Desktop

Add this to your claude_desktop_config.json: 
{
  "mcpServers": {
    "mandate": {
      "command": "npx",
      "args": ["@mandate.md/cli", "--mcp"],
      "env": {
        "MANDATE_RUNTIME_KEY": "mndt_test_abc123..."
      }
    }
  }
}
On macOS, this file lives at ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows, it is at %APPDATA%\Claude\claude_desktop_config.json.

​
Codex CLI

Add this to your .codex/config.toml: 
[mcp.mandate]
transport = "stdio"
command = ["npx", "@mandate.md/cli", "--mcp"]
Set the runtime key in your shell environment: 
export MANDATE_RUNTIME_KEY="mndt_test_abc123..."

​
Claude Code

Claude Code can connect to the MCP server directly: 
claude mcp add mandate -- npx @mandate.md/cli --mcp
Or use the dedicated Claude Code plugin for two-phase enforcement with hooks.

​
How it works

When an AI assistant sends a tool call to the MCP server, the server:
  1. Parses the tool name and arguments
  2. Routes to the corresponding CLI command
  3. Authenticates using the runtime key from environment or ~/.mandate/credentials.json
  4. Returns the result as structured JSON
The assistant sees the same output as running the CLI directly. Error responses include typed error codes and block reasons.

​
When to use MCP vs the CLI directly

Use --mcp when your AI assistant supports MCP natively (Claude Desktop, Codex CLI, Claude Code). The assistant gets structured tool definitions, typed inputs, and typed outputs without parsing CLI text. Use the CLI directly when you are scripting, running in CI, or working from a terminal. The output is the same JSON.
For a cloud-hosted MCP server on Cloudflare Workers (no local CLI needed), see the MCP Server integration. It runs as a deployed service rather than a local process.

​
Next Steps

Cloud MCP Server

Deploy Mandate as a hosted MCP server on Cloudflare Workers.

CLI Overview

Full list of commands and global options.

Agent Discovery

Use —llms for lightweight command discovery without MCP.