# MSIO — HCP Tools for AI Agents

Madam Secretary Intelligent Operations (MSIO) is an MCP server built to assist plumbing company operators who use Housecall Pro (HCP) daily. Running it as an MCP server means operators work through the AI chat interface they are already familiar with, leveraging the power of a cloud-based subscription AI they already pay for. The purpose of MSIO is to give AI agents useful tools to do useful work by enabling them to interact with HCP. It is in daily production use at a working plumbing company.

## What it can do

MSIO gives your AI agent the ability to do the tasks that make management, evaluation, and projections easier. Most AI agents are innately good at pattern recognition, but they lack the tools to interact properly with HCP — and they lack context. MSIO provides the functions to search job history and parse information so the AI agent can read it and find the patterns. For instance, you could give it a job like:

> "Look through the jobs completed over the last 4 months. Find out which zip codes have the most activity, what types of jobs we've done, and which tech has been the most efficient with their time."

The server exposes 36 tools: reading HCP data (jobs, customers, estimates, invoices, employees, tags, leads), spotting problems (stale estimates, uninvoiced jobs, overdue receivables), business intelligence (customer history and risk signals, tech performance, revenue forecasting, job classification), estimate generation, and a small set of validated write operations (tags, notes, line items, scheduling).

## Architecture

When the MCP server connects to the user's agent, it provides the agent with descriptions of its tools for selection when needed. A user request triggers the agent to select a tool based on reasoning. The agent forms the client request for the appropriate tool, structured as MCP over stdio. `app.py` routes the request to that tool's handler, which validates the inputs and then calls HCP's REST API through `hcp_client.py`. Structured JSON is returned from HCP, parsed into a consistent response envelope (`success / data / error / metadata`, with credentials redacted), and given back to the agent. The agent then reads the information and forms the response that is given to the user.

Reasoning happens at the two ends of that chain — tool selection and the final answer — and everything in the middle is deterministic Python. The server makes no LLM calls of its own: it either works or returns a structured error, and it cannot hallucinate.

Much of the deterministic layer exists because HCP's API behaves in ways the docs don't advertise. Every monetary amount arrives in cents. Estimates are write-once — no update, no delete. And `POST /jobs` returns a 201 success while silently dropping the job's `description` field; the server works around it by creating the job, then attaching the description as a note in a second call. Each gotcha like this is encoded once in the execution layer so no user — human or AI — ever hits it again.

## Install and configuration

MSIO's intended use is with Claude Desktop, and the directions below reflect that — it's what the server was built and tested against. Because it's built on the open MCP standard, any MCP-compatible agent is viable, including private/self-hosted agents; installation and configuration guides for those will be added in future updates.

Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/). An HCP API key is only available on plan tiers that include API access (e.g. MAX) — find it in your HCP settings, where you will have HCP generate a key.

```
git clone https://github.com/brystal00/msio-server
cd msio-server
uv venv .venv --python 3.13
uv pip install -e ".[dev]"
make check
```

Then register the server in your Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "madam-secretary": {
      "command": "/path/to/msio-server/.venv/bin/python",
      "args": ["/path/to/msio-server/server.py"],
      "env": { "HCP_API_KEY": "your_key_here" }
    }
  }
}
```

Restart Claude Desktop, approve the MCP connection, and Claude will have access to the tools. (A double-click install bundle for non-technical users is planned.)

## Status and scope

This application is completely local stdio. This is deliberate: it keeps access to your HCP account and your data centralized to your computer — there is no hosted service, no third-party server, and nothing to sign up for. It is important to note that if you use a cloud-model AI agent, your data will flow through their cloud servers accordingly.

## License

Licensed under the [MIT License](LICENSE). Built on Anthropic's open [Model Context Protocol](https://modelcontextprotocol.io) standard.