Tools and MCP

Tools let Bestie inspect files, search local context, read logs, call approved MCP servers, and report useful progress. The important rule is simple: tools need classification, permissions, and receipts. Tool soup without guardrails is just chaos with better branding.

Internal tools

Bestie exposes internal read tools for terminal and Telegram turns. These tools are intended for local inspection tasks such as reading files, listing folders, searching text, bundling Markdown, checking logs, and inspecting memory.

Local read tools default to allow. Web reads, writes, patches, and exec tools default to ask.

Supported policy keys include:

• internal.read_url
• internal.write_file
• internal.edit_file
• internal.apply_patch
• internal.exec
• internal.list_processes

Example config:

{
  "internalTools": {
    "policies": {
      "internal.write_file": "ask",
      "internal.edit_file": "ask",
      "internal.apply_patch": "ask",
      "internal.exec": "ask",
      "internal.list_processes": "allow",
      "internal.read_url": "ask"
    },
    "exec": {
      "timeoutMs": 120000
    }
  }
}

Workspace behavior

Relative write, edit, and exec paths land in the agent workspace by default. Bestie uses .bestie/workspace so ad hoc generated files do not pollute the project root.

Explicit project paths such as src, docs, README.md, or the absolute project root still inspect the repository when the user asks for code or docs review.

Use workspace.externalPaths for trusted absolute paths outside the project root and agent workspace.

{
  "workspace": {
    "defaultPath": ".bestie/workspace",
    "externalPaths": []
  }
}

MCP servers

MCP tool calls require local tool classification. The current foundation only calls tools categorized as read unless approval flows are expanded.

Example stdio MCP server:

{
  "mcp": {
    "servers": [
      {
        "name": "local-files",
        "enabled": false,
        "transport": "stdio",
        "command": "node",
        "args": ["server.js"],
        "env": {
          "MCP_LOG_LEVEL": "warn"
        },
        "tools": [
          { "name": "read_file", "category": "read" }
        ]
      }
    ]
  }
}

Example remote HTTP MCP server:

{
  "mcp": {
    "servers": [
      {
        "name": "composio",
        "enabled": true,
        "transport": "http",
        "url": "https://connect.composio.dev/mcp",
        "headersEnv": {
          "x-consumer-api-key": "COMPOSIO_CONSUMER_API_KEY"
        },
        "tools": [
          { "name": "tool_name_from_tools_list", "category": "read" }
        ]
      }
    ]
  }
}

Sensitive header values must come from env variables through headersEnv. Do not store raw API keys or tokens in config.json.

MCP commands

Useful local commands:

bestie mcp list
bestie mcp show dry-run
bestie mcp test dry-run
bestie mcp test dry-run --connect
bestie mcp tools dry-run --connect
bestie mcp classify dry-run read_file --category read
bestie mcp call dry-run read_file --read --json '{"path":"README.md"}'
bestie mcp call dry-run read_file --read --ask --json '{"path":"README.md"}'

Use --ask to force a one-time CLI approval prompt even for a read call.

Safety checklist

• Classify every MCP tool before use.
• Start with read-only tools.
• Keep secrets in env files, not config.
• Redact secrets from logs and errors.
• Ask before local writes, external writes, destructive actions, public actions, and money/payment actions.
• Report files changed, commands run, and validation results.