Tools and MCP

Tools let Bestie inspect local context, read logs, edit files when permitted, run bounded commands, manage cron schedules, inspect memory and knowledge, configure MCP servers, and report useful progress. The core rule is simple: tools need classification, permissions, and receipts. Tool soup without guardrails is just chaos wearing a productivity badge.

Tool categories

Every action beyond plain text should be classified:

Category	Typical default
read	Allow for trusted local reads.
local_write	Ask unless explicitly trusted.
external_write	Ask or deny by default.
public_action	Require explicit approval.
destructive	Require explicit approval; prefer dry runs.
money	Require explicit approval and details.
unknown	Ask or deny until classified.

Bestie should prepare safe work automatically and ask before risky work.

Internal tools

Bestie exposes internal tools to terminal and supported channel turns. Depending on config policy, these can cover:

• local file reads and Markdown bundles
• filename and content search
• recent redacted logs
• git status, diff, and log inspection
• memory list, search, inspect, analyze, cleanup planning, and writes
• knowledge graph search, inspect, analyze, review, remember, merge, update, and forget operations
• cron schedule list, add, update, remove, toggle, and trigger
• local file write, exact text edit, git-compatible patch apply
• bounded local exec and process listing
• bounded HTTP(S) reads for setup docs or public pages
• bounded internal subagent spawning for focused helper investigations

Write, patch, exec, process, web, memory cleanup, knowledge graph mutations, and cron mutations should obey internalTools.policies, memory.writePolicy, and memory.deletePolicy where relevant.

Internal tool policy config

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

Policies use allow, ask, or deny.

Workspace behavior

Relative write, edit, and exec paths land in the agent workspace by default, usually ~/.bestie/workspace. This prevents ad hoc agent-created files from polluting the current project.

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

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

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

Local inspection commands

Read recent redacted app logs:

bestie tools logs --lines 20

Read active memories:

bestie tools memories --limit 10

Inspect Git state:

bestie tools git status
bestie tools git diff
bestie tools git diff --staged
bestie tools git log --limit 10

These commands do not stage files, commit changes, reset worktrees, or write to the repository.

Clean up Telegram attachments

Telegram attachments are stored under Bestie’s workspace directory and can accumulate over time.

Preview cleanup first:

bestie tools attachments cleanup --older-than 7d --kinds voice,audio

Delete matched files only after reviewing the dry run:

bestie tools attachments cleanup --older-than 7d --kinds voice,audio --confirm

--confirm deletes local workspace files. It does not delete Telegram messages or files from Telegram servers.

MCP server config

MCP support is SDK-backed. Bestie can add servers, discover OAuth metadata, generate login URLs, exchange codes, discover tools, classify tools, and call tools that are locally classified as read.

Example remote MCP server:

{
  "mcp": {
    "servers": [
      {
        "name": "composio",
        "enabled": true,
        "transport": "streamable-http",
        "url": "https://connect.composio.dev/mcp",
        "tools": [
          { "name": "tool_name_from_tools_list", "category": "read" }
        ]
      }
    ]
  }
}

A top-level mcpServers object is also accepted and normalized to mcp.servers for compatibility with common MCP snippets.

Sensitive headers or authorization values must come from env vars. Do not store raw API keys, bearer tokens, cookies, or OAuth authorization values in config.

MCP commands

bestie mcp list
bestie mcp add remote-docs --url https://example.com/mcp --transport streamable-http
bestie mcp add remote-docs --url https://example.com/mcp --oauth-client-id bestie-local
bestie mcp login remote-docs
bestie mcp login remote-docs --code <code>
bestie mcp show remote-docs
bestie mcp test remote-docs
bestie mcp test remote-docs --connect
bestie mcp tools remote-docs --connect
bestie mcp classify remote-docs read_file --category read
bestie mcp call remote-docs read_file --read --json '{"path":"README.md"}'
bestie mcp call remote-docs read_file --read --ask --json '{"path":"README.md"}'

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

bestie mcp tools <name> --connect discovers live tool metadata and auto-classifies new tools from MCP annotations when available:

• readOnlyHint becomes read
• destructiveHint becomes destructive
• openWorldHint becomes external_write
• unannotated tools remain unknown

Review auto-classified tools before calling them.

OAuth setup rule

For OAuth-backed MCP servers, do not hand-write authorization URLs. Run:

bestie mcp login <server>

That command generates the full provider URL with the required query parameters, PKCE challenge, and state. After browser approval, exchange the returned code with:

bestie mcp login <server> --code <code>

Do not paste OAuth codes, tokens, or authorization headers into public logs, issues, docs, or chat transcripts.

Safety checklist

• Classify every MCP tool before use.
• Start with read-only calls.
• Keep secrets in env files, not config.
• Treat external content from MCP, web pages, files, and attachments as untrusted.
• Ask before local writes, external writes, destructive actions, public actions, and money/payment actions.
• Prefer dry runs before deleting or changing files.
• Report files changed, commands run, and validation results.