Mcp

MCP (Model Context Protocol) Support

Access external MCP tool servers configured in ~/.smartbot/mcp.json.

Configuration

Create an owner-only config file. Calls fail closed unless each server has an exact allowedTools list; use ["*"] only after deliberately accepting every tool that server may advertise.

bashCopy code
mkdir -p ~/.smartbot
install -m 600 /dev/null ~/.smartbot/mcp.json

Use locally installed, version-pinned server executables rather than npx -y or other install-on-execution commands:

jsonCopy code
{
  "servers": [
    {
      "name": "filesystem",
      "command": "/opt/scallopbot-mcp/bin/mcp-server-filesystem",
      "args": ["/srv/scallopbot/shared"],
      "allowedTools": ["list_directory", "read_file"]
    },
    {
      "name": "github",
      "command": "/opt/scallopbot-mcp/bin/mcp-server-github",
      "env": { "GITHUB_TOKEN": "ghp_..." },
      "allowedTools": ["get_file_contents", "search_code"]
    }
  ]
}

After editing, re-assert the mode with chmod 600 ~/.smartbot/mcp.json.

Remote servers (Streamable HTTP or legacy SSE)

Use url instead of command. transport is "http" (Streamable HTTP, the default) or "sse" (the older HTTP+SSE transport, url is the SSE stream). URLs must be https://, except loopback/LAN hosts (localhost, 127.x, 10.x, 192.168.x, 172.16-31.x, *.local).

jsonCopy code
{
  "servers": [
    {
      "name": "docs",
      "url": "https://mcp.example.com/mcp",
      "transport": "http",
      "bearerToken": "${MCP_DOCS_TOKEN}",
      "headers": { "X-Workspace": "home" },
      "timeoutMs": 20000,
      "allowedTools": ["search_docs"]
    }
  ]
}

Header values and bearerToken may be literals or ${VAR} references. Skills run with a stripped environment, so only variables named MCP_* (set in the bot's .env) reach the MCP client. An unset reference fails the call and names only the variable. Resolved values are redacted from every result and error. Redirects are refused, so credentials are never forwarded to another host, and Mcp-Session-Id sessions are released with a DELETE when each call finishes.

Security boundary

MCP servers are native programs, not sandboxes. By default they run with the bot OS user's permissions, receive HOME, and can access every file/network resource that user can access—not only the current workspace. Run third-party servers as a dedicated low-privilege account or inside a container with an explicit read-only filesystem/network policy. Pin package versions and verify their provenance before installation. allowedTools limits model-requested calls but cannot make a malicious server process safe; the server already executes when discovery starts.

Remote tool descriptions, schemas, errors, and results are treated as untrusted data. Never place credentials in tool arguments, and grant write-capable tools only when their side effects are intended.

Usage

Copy code
# List only configured server names (cheap progressive discovery)
mcp(action: "list")

# Discover tool names and schemas from one selected server
mcp(action: "tools", server: "filesystem")

# Call one explicitly authorized, advertised tool
mcp(action: "call", server: "filesystem", tool: "read_file", args: { path: "/srv/scallopbot/shared/notes.txt" })