create_client
Adds a client to the team's registry, the first record Heimdall writes when a person describes a new client's project in conversation.
Create a client on the team's registry: name is required and unique within the team; legal_name, website, industry, country (a two-letter upper-case code such as LK), timezone, primary_contact_name, primary_contact_email, notes (HTML) and status (prospect, active, dormant or churned; active by default) fill in what the person said. The client is written through the same action the Clients page runs and client.created goes out.
Look the client up with list_clients first, so a client already on the registry is reused rather than created twice; create the project under it with create_project once it exists. A staff token with client:create is needed; a client guest's token is refused.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Fires one event
Delivered to every endpoint subscribed to it once the change is made.
Annotations
A client that honours annotations asks a person before running it.
Arguments
name*stringThe client's name, 2 to 100 characters, unique within the team.
legal_namestringoptionalThe registered name, up to 160 characters.
websitestringoptionalThe client's site as a full URL.
industrystringoptionalThe line of business, up to 80 characters.
countrystringoptionalA two-letter upper-case country code, such as LK.
timezonestringoptionalA timezone identifier, such as Asia/Colombo.
primary_contact_namestringoptionalWho speaks for the client.
primary_contact_emailstringoptionalTheir email address.
notesstringoptionalWhat the team should know, as HTML.
statusstringoptionalWhere the relationship stands; active by default.
prospectactivedormantchurnedWhat it returns
{ "data": { "id": "9b1f2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d", "team_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "Super Clean Laundry", "legal_name": null, "website": null, "industry": "Laundry services", "country": "LK", "timezone": "Asia/Colombo", "primary_contact_name": "Nadeesha Perera", "primary_contact_email": "nadeesha@example.test", "notes": null, "status": "active", "projects_count": 0, "archived_at": null, "created_at": "2026-10-28T09:12:00+00:00", "updated_at": "2026-10-28T09:12:00+00:00" }}How it fails
VALIDATION_FAILEDname missing or shorter than 2 characters, a country that is not a two-letter upper-case code, a status outside the four, or a name the team already uses.
FORBIDDENthe token is a client guest's, or the holder's team role does not carry client:create.
TOKEN_MISSING_ABILITYtoken lacks client:create.
How is this guide?
Last updated on