Connect Housecall Pro to Codex

Codex keeps its MCP servers in a TOML config rather than JSON, and it ships a command that writes the entry for you. Either route works. The command is fewer moving parts and is the one to use unless you already keep that file by hand.

Setup

Generate a Housecall Pro API key

In Housecall Pro: My Apps, then Go to App store, then API Key Management. Choose Read-only unless you specifically want the MCP to be able to make changes. API access is a MAX-plan feature and you need an admin login.

The full walkthrough, with a direct link to the page

Register the server

One command, and Codex writes the entry into its own config for you.

codex mcp add housecall-pro --env HCP_API_KEY=your-api-key-here -- npx -y housecall-pro-mcp

Or write the config yourself

The file is ~/.codex/config.toml. A project-scoped .codex/config.toml also works, for projects you have marked trusted. Everything after the double dash above is what these two keys hold.
```
[mcp_servers.housecall-pro]
command = "npx"
args = ["-y", "housecall-pro-mcp"]

[mcp_servers.housecall-pro.env]
HCP_API_KEY = "your-api-key-here"
```

Your first ask

Ask something you already know the answer to. If it agrees with you, everything is wired correctly. If it does not, you have found something worth knowing about your book.

what did we invoice last month, grouped by service?

Worth knowing

The key is mcp_servers, with an underscore, and the file is TOML. Claude Desktop and Cursor both use a JSON mcpServers block, so a config copied across from either will not work here.
A stdio server is defined by having a command. Giving it a url instead makes it a Streamable HTTP server, which this is not.
Keep the key out of a project-level .codex/config.toml that gets committed to git.

If it does not work

The two commonest causes are the plan and the header. API access is a MAX-plan feature, so on a lower plan there is no key to generate. And if you are hand-rolling requests rather than using the MCP, the auth header is Token, not Bearer. That one accounts for most "my key does not work" reports. The API guide covers the rest.

Still stuck: hello@hcpapi.com, or read the source, which is open.

← About the MCP