MCP servers

Any Model Context Protocol server can add tools to @housecall. List it under mcp in config/config.yaml.

mcp:
  - name: tickets
    command: npx
    args: ["-y", "@acme/tickets-mcp"]
    env: { TICKETS_TOKEN: "${TICKETS_TOKEN}" }
    read_only: [search_tickets, get_ticket]
  - name: remote
    url: https://mcp.example.com/mcp
    headers: { Authorization: "Bearer ${REMOTE_MCP_TOKEN}" }

Key	Meaning
`name`	Short name: lowercase letters, digits, `_` or `-`, without `__`. Tools appear to the model as `mcp__<name>__<tool>`. A tool whose name collides with another after this renaming is skipped and logged.
`command`, `args`, `env`	Start a local server over stdio.
`url`, `headers`	Connect to a remote server over streamable HTTP.
`read_only`	Tools that run without approval.

Each entry has either command or url, not both. Put secrets in .env and reference them with ${NAME}.

Stdio servers get only PATH, HOME, USER, LANG, TMPDIR and their own env, not @housecall’s secrets.

Which tools need approval

Every tool needs the requester to approve it unless it is listed in read_only. The server’s own readOnlyHint is ignored.

Approval is the requester confirming the action, not an IT sign-off; see Approvals. List only tools that are safe for everyone in read_only, and don’t connect servers with admin tools that anyone in chat could ask for.

With Docker

The image is based on node:24-slim, so servers you start with npx work inside the container.

When a server goes down

@housecall reconnects with backoff. While a server is disconnected, its tools return an error to the model instead of hanging.