Connect an assistant to Hearth
Hearth has an assistant connector at /mcp, over streamable HTTP. A person adds it as a custom connector in their assistant, signs in as themselves, and every tool runs with exactly the rights that person has in Hearth. Nothing is shared, and there is no token to paste.
If you host Hearth at https://hearth.example.com, the connector address is https://hearth.example.com/mcp.
What an assistant can do
- Documents. Search, list, read, create, and update documents, including tasks and work orders.
- CRM. Read the CRM counts, find and read contacts, companies, and deals, create and update them, and log notes and calls.
Asking for something you cannot see answers "no such entity", the same as the website. An empty list means you cannot see anything, not that nothing exists.
Two ways to connect
As a person, through your sign-in provider. This needs single sign-on configured in Hearth, because the person signs in to your provider and Hearth checks the token. Hearth checks the signature, issuer, expiry, and audience on every request.
- Register a public OAuth client for the assistant in your sign-in provider. It uses PKCE, has no client secret, and allows the callback address your assistant documents for custom connectors.
- Add a client scope that puts the audience
hearth-mcpinto the token, and give the client that scope. You can use a different audience name, and then setmcp.audiencein the chart to match. - Optionally set
mcp.requiredRoleto a role a person must hold to use the connector at all. - In the assistant, add a custom connector named Hearth with the
/mcpaddress, and enter the client ID you registered. - Connect, and sign in.
A person needs a Hearth account linked to their sign-in. Signing in to Hearth in a browser once creates the link. Hearth never makes an account from a token.
As an agent, with a token. Open Settings, then Agents, and create an agent. Its token starts with hearth_agent_ and works against the same endpoint with its own grants. An agent can be set to make suggestions only, so its writes are recorded as proposals that a person accepts.
Why it is safe to turn on
The tools never bypass Hearth. They call the same services the website calls, as the person the token names. A person with read-only access cannot write through the connector, and the audit log records each call with who, which client, which tool, and how it went.