shellfirm mcp

The mcp command starts shellfirm's Model Context Protocol (MCP) server, enabling AI agents to check commands before executing them.

Usage

shellfirm mcp

Description

Starts a JSON-RPC 2.0 server over stdio. The server reads requests from stdin and writes responses to stdout. It runs until stdin is closed (typically when the parent process terminates).

Protocol

• Transport: stdio (stdin/stdout)
• Format: JSON-RPC 2.0
• Protocol version: 2024-11-05

Exposed tools

Tool	Description	Required parameters
check_command	Check if a shell command is risky	command (string)
suggest_alternative	Get safer alternatives for a risky command	command (string), optional goal (string)
get_policy	Get current configuration and active policy	(none)
explain_risk	Get detailed risk explanation for a command	command (string)

Configuration

The MCP server uses the same configuration as the CLI:

• Settings from ~/.shellfirm/settings.yaml
• Project policies from .shellfirm.yaml (based on the working directory when the server starts)
• Agent settings (agent.auto_deny_severity, agent.require_human_approval)

Agent configuration

Claude Code

{
  "mcpServers": {
    "shellfirm": {
      "command": "shellfirm",
      "args": ["mcp"]
    }
  }
}

Cursor

{
  "mcpServers": {
    "shellfirm": {
      "command": "shellfirm",
      "args": ["mcp"]
    }
  }
}

Generic MCP client

Spawn shellfirm mcp as a child process with stdin/stdout pipes. Send JSON-RPC requests as newline-delimited JSON.

Session management

Each shellfirm mcp invocation creates a unique session ID. This session ID:

• Is included in get_policy responses
• Is recorded in audit log entries
• Can be used to trace all commands from a single agent session

Example interaction

→ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"shellfirm","version":"1.0.0"}}}

→ {"jsonrpc":"2.0","method":"notifications/initialized","params":{}}
(no response - notification)

→ {"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
← {"jsonrpc":"2.0","id":2,"result":{"tools":[...]}}

→ {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"check_command","arguments":{"command":"rm -rf /"}}}
← {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"{...risk assessment JSON...}"}]}}

See the MCP Server page for detailed request/response examples.