Tools

ECA supports 3 types of tools:

• Native tools: (edit_file, write_file, read, etc)
• MCP servers: if any configured
• User custom tools: if defined

MCP

For MCP servers configuration, use the mcpServers config, examples:

StdioHTTP (streamable or sse)

~/.config/eca/config.json

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      // optional
      "env": {"FOO": "bar"}
    }
  }
}

ECA supports OAuth authentication as well

~/.config/eca/config.json

{
  "mcpServers": {
    "cool-mcp": {
      "url": "https://my-remote-mcp.com/mcp"
    }
  }
}

Custom Tools

You can define your own command-line tools that the LLM can use. These are configured via the customTools key in your config.json.

The customTools value is an object where each key is the name of your tool. Each tool definition has the following properties:

• description: A clear description of what the tool does. This is crucial for the LLM to decide when to use it.
• command: An string representing the command and its static arguments.
• schema: An object that defines the parameters the LLM can provide.
  • properties: An object where each key is an argument name.
  • required: An array of required argument names.

Placeholders in the format {{argument_name}} within the command string will be replaced by the values provided by the LLM.

Example 1Example 2

~/.config/eca/config.json

{
  "customTools": {
    "web-search": {
      "description": "Fetches the content of a URL and returns it in Markdown format.",
      "command": "trafilatura --output-format=markdown -u {{url}}",
      "schema": {
        "properties": {
          "url": {
            "type": "string",
            "description": "The URL to fetch content from."
          }
        },
        "required": ["url"]
      }
    }
  }
}

~/.config/eca/config.json

{
  "customTools": {
    "file-search": {
      "description": "${file:tools/my-tool.md}",
      "command": "find {{directory}} -name {{pattern}}",
      "schema": {
        "properties": {
          "directory": {
            "type": "string",
            "description": "The directory to start the search from."
          },
          "pattern": {
            "type": "string",
            "description": "The search pattern for the filename (e.g., '*.clj')."
          }
        },
        "required": ["directory", "pattern"]
      }
    }
  }
}

Approval / permissions

By default, ECA asks to call any non read-only tool (default here), but that can easily be configured in several ways via the toolCall.approval config.

You can configure the default approval with byDefault and/or configure a tool in ask, allow or deny configs.

Check some examples:

Allow any tools by defaultAllow all but some toolsAsk all but all tools from some mcpsMatching by a tool argumentDenying a tool

~/.config/eca/config.json

{
  "toolCall": {
    "approval": {
      "byDefault": "allow"
    }
  }
}

~/.config/eca/config.json

{
  "toolCall": {
    "approval": {
      "byDefault": "allow",
      "ask": {
        "eca_editfile": {},
        "my-mcp__my_tool": {}
      }
    }
  }
}

~/.config/eca/config.json

{
  "toolCall": {
    "approval": {
      // "byDefault": "ask", not needed as it's eca default
      "allow": {
        "eca": {},
        "my-mcp": {}
      }
    }
  }
}

argsMatchers is a map of argument name by list of java regex.

~/.config/eca/config.json

{
  "toolCall": {
    "approval": {
      "byDefault": "allow",
      "ask": {
        "shell_command": {"argsMatchers": {"command": [".*rm.*",
                                                           ".*mv.*"]}}
      }
    }
  }
}

~/.config/eca/config.json

{
  "toolCall": {
    "approval": {
      "byDefault": "allow",
      "deny": {
        "shell_command": {"argsMatchers": {"command": [".*rm.*",
                                                       ".*mv.*"]}}
      }
    }
  }
}

Also check the plan agent which is safer.

The manualApproval setting was deprecated and replaced by the approval one without breaking changes

File Reading

You can configure the maximum number of lines returned by the eca__read_file tool:

~/.config/eca/config.json

{
  "toolCall": {
    "readFile": {
      "maxLines": 1000
    }
  }
}

Default: 2000 lines