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 any MCP-compatible application, such as Claude Desktop). The client side is production-ready; server mode is beta — it works, and test reports are welcome.

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 (beta) on stdin/stdout:

aibutler mcp serve

To see exactly which tools it exposes:

aibutler mcp tools

The server speaks JSON-RPC over stdio — external clients launch it as a subprocess, discover its tools, and call them. Only tools whose capabilities are on the allow-list are exposed (see Capability Filtering below); the default allow-list is memory.read and data.read, so out of the box only read-only memory tools are visible.

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 — the tools you’ve allow-listed (memory search by default; more if you add them) are now available to Claude.

Capability Filtering

The MCP server is allow-list only. The default allow-list contains just the read-only capabilities memory.read and data.read — nothing else is visible until you add it. Capability names must match exactly:

configurations:
  mcp_server:
    allowed_capabilities:
      - memory.read
      - memory.write
      - schedule.manage
      - iot.sensor.read
      - iot.device.control

Anything not on the allow-list is invisible to MCP clients — useful when you want Claude Desktop to control the lights (iot.device.control) but never run shell commands (tool.shell.exec stays off the list).

HTTP Transport and Resources

Besides the stdio server, AI Butler mounts an MCP v2 endpoint at /mcp/v2 on the built-in web server (port 3377, bound to localhost by default). It exposes a focused butler.* tool set — butler.memory.search, butler.schedule.create, butler.channel.send, butler.agent.delegate, butler.swarm.run — plus read-only MCP resources:

• memory://search — search the memory store
• memory://entities — known entities
• schedule://tasks — scheduled tasks
• channels://list — active channels
• agent://registry — registered agents

MCP prompts are not exposed yet.

Related

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