MCP Server

MCP (Model Context Protocol) is Anthropic’s open protocol for connecting LLMs to tools, data, and prompts. AI Butler is both an MCP client (it can call external MCP servers) and an MCP server (it exposes its tools to other LLM applications like Claude Desktop, Continue, or any MCP-compatible editor).

Two Modes

Mode	What it does
MCP Client	AI Butler consumes tools from external MCP servers
MCP Server	AI Butler exposes its own tools via MCP to external clients

You can run both simultaneously.

As an MCP Client

Register external MCP servers in config.yaml. Each server entry has a name, the command to launch it, its args, and optional environment variables (including vault_env for credentials that live in the vault):

configurations:
  mcp:
    servers:
      - name: filesystem
        command: npx
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/me"]

      - name: memory
        command: npx
        args: ["-y", "@modelcontextprotocol/server-memory"]

      - name: github
        command: npx
        args: ["-y", "@modelcontextprotocol/server-github"]
        vault_env:
          github_token: GITHUB_TOKEN       # vault_key -> env_var_name

      - name: clarifyprompt
        command: node
        args: ["/path/to/clarifyprompt-mcp/dist/index.js"]
        env:
          LLM_API_URL: "http://localhost:11434/v1"
          LLM_MODEL: "llama3.2:3b"

On startup, AI Butler spawns each MCP server as a subprocess over stdio, discovers their tools, and merges them into the agent’s tool registry. No code changes needed — the agent gets the tools just like native ones.

See a full hands-on walkthrough with screenshots: Integrate an MCP server →

As an MCP Server

Start the MCP server:

aibutler mcp serve

Or over HTTP for remote access:

aibutler mcp serve --http --port 8091

This exposes every enabled tool (memory, coding, IoT, channels, etc.) as MCP tools, and lets external clients discover and call them.

Connect Claude Desktop

Edit Claude Desktop’s config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "aibutler": {
      "command": "aibutler",
      "args": ["mcp", "serve"]
    }
  }
}

Restart Claude Desktop — Butler’s tools (memory search, smart home control, scheduling, etc.) are now available to Claude.

Capability Filtering

By default, the MCP server exposes all enabled tools. You can restrict it:

configurations:
  mcp_server:
    allowed_capabilities:
      - memory.search
      - memory.capture
      - iot.state
      - iot.set
      - schedule.list

Anything not on the allow-list is invisible to MCP clients — useful when you want Claude Desktop to control the lights but not run shell commands.

Resources and Prompts

Beyond tools, MCP supports resources (file-like handles you can read) and prompts (pre-defined templates). AI Butler exposes:

Resources: conversation history, memory entries, IoT device snapshots, schedule registry
Prompts: saved prompts (from aibutler schedule create), BUTLER.md, skill definitions

# Example MCP client fetching a resource
resources = await mcp_client.list_resources()
# [{"uri": "aibutler://memory/recent", "name": "Recent memory"}, ...]

content = await mcp_client.read_resource("aibutler://memory/recent")

Auth

HTTP MCP server supports bearer token auth:

configurations:
  mcp_server:
    http:
      enabled: true
      port: 8091
      auth_token_hashes:
        - "$2a$10$..."

A2A Protocol — agent-to-agent delegation
Plugins — for WASM-based extensions instead of MCP subprocesses