Cursor & Other Agents

Any AI agent that supports the Model Context Protocol (MCP) can use shellfirm as a tool server. The configuration pattern is the same across all clients: point the MCP client at shellfirm mcp over stdio.

Generic MCP configuration

The core configuration is always:

• Command: shellfirm
• Arguments: ["mcp"]
• Transport: stdio (JSON-RPC 2.0 over stdin/stdout)

Cursor

Add shellfirm to your Cursor MCP configuration. Create or edit .cursor/mcp.json in your project root:

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

After saving the configuration, restart Cursor to activate the MCP connection.

Windsurf

For Windsurf, add shellfirm to your MCP configuration file:

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

Zed

Add shellfirm to your Zed settings.json under context_servers:

{
  "context_servers": {
    "shellfirm": {
      "command": {
        "path": "shellfirm",
        "args": ["mcp"]
      },
      "settings": {}
    }
  }
}

After saving, check the Agent Panel settings — the indicator dot next to shellfirm should turn green when the server is active.

Cline

Open the MCP Servers panel in Cline (click the MCP Servers icon in the top navigation bar), then select Advanced MCP Settings to edit cline_mcp_settings.json:

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

Continue

Add a configuration file at .continue/mcpServers/shellfirm.json in your project root:

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

MCP tools are available in Continue's agent mode.

Amazon Q Developer

Add shellfirm to your Amazon Q MCP configuration. For global setup, edit ~/.aws/amazonq/mcp.json. For per-project setup, create .amazonq/mcp.json in your project root:

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

VS Code with Copilot

If your VS Code extension or Copilot integration supports MCP tool servers, the configuration follows the same pattern. Check your extension's documentation for where to place MCP server configurations.

Custom MCP clients

If you are building your own MCP client or integrating with a custom agent, you need to:

1. Spawn the process:

shellfirm mcp

2. Send JSON-RPC 2.0 requests over stdin. Start with the initialize handshake:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}

3. Read the response from stdout:

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

4. Send the initialized notification:

{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}

5. List available tools:

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

6. Call tools as needed:

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"check_command","arguments":{"command":"rm -rf /tmp/data"}}}

Available tools

All MCP clients get access to the same four tools:

Tool	Input	Output
check_command	{"command": "..."}	Full risk assessment with allowed/denied status, matched rules, alternatives
suggest_alternative	{"command": "...", "goal": "..."}	Safer alternative commands
get_policy	{}	Current configuration, active groups, agent settings
explain_risk	{"command": "..."}	Detailed risk explanation with matched patterns and context

Tips for agent configuration

Instruct your agent to check commands

Most AI agents do not automatically check every command. You may need to instruct them via system prompts or project configuration files:

Always use the shellfirm check_command tool before executing any shell command.
If a command is denied, use suggest_alternative to find a safer approach.

Set appropriate auto-deny thresholds

For unattended agent operation, configure auto-deny in ~/.shellfirm/settings.yaml:

agent:
  auto_deny_severity: High

This ensures that even if the agent does not check commands proactively, high-severity commands are blocked by default.

Use project policies

Commit a .shellfirm.yaml to your repository so that agents working on the project inherit team safety rules:

version: 1
deny:
  - "git:force_push"
  - "kubernetes:delete_namespace"
overrides:
  - id: "fs:recursively_delete"
    challenge: Yes