Add your first client

create_client needs a name and accepts one optional currency plus contact and address fields. Without a currency the client inherits the business default, and every invoice or estimate you draft for them starts in the client currency.

Written and reviewed by the Billr team. Published 2026-09-20, last reviewed 2026-09-20.

Who this is for: People starting a Billr account, or adding a second client from an agent session.
Billr capabilities used: create_clientlist_clientsget_client

What you need first

A Billr account with at least one business. list_businesses shows which businesses the key can reach.
A key with the Read and draft profile, which can both read and write.
The client name exactly as it should print on documents. Billr matches client_name case-insensitively, but not fuzzily.

Step by step

01Create the client
Pass the name at minimum. email matters when you plan to send invoices or estimates through Billr, because sending defaults to the client email when to is omitted.
Example
```
create_client  {
  "name": "Harbor & Lane",
  "email": "accounts@harbor-lane.example",
  "currency": "USD"
}
```
02Add the address once
Address fields are optional and stored on the client. They travel with the client details on documents, so fill in only what should be printed.
03Confirm what the agent sees
list_clients returns each client with its currency plus financial rollups (total_invoiced, total_paid, outstanding_balance), which is enough to answer "what does this client owe" without reading invoices directly.
04Fetch one client in full
get_client takes a client_id and returns the record plus the five most recent invoices. Use it after list_clients when you need the id.

Worked example

Fictional account, field names as returned by the server

You say

Add Harbor & Lane as a client, they pay in dollars.

Your agent calls

create_client { "name": "Harbor & Lane", "email": "accounts@harbor-lane.example", "currency": "USD" }
list_clients { "search": "Harbor" }

Expected responses, abridged

{
  "summary": "Created client \"Harbor & Lane\".",
  "client": {
    "id": "9f2a4d18-3b7c-4a6e-8f0d-1c5b2e9a7d44",
    "name": "Harbor & Lane",
    "email": "accounts@harbor-lane.example",
    "currency": "USD",
    "app_url": "https://billr.cc/clients/9f2a4d18-3b7c-4a6e-8f0d-1c5b2e9a7d44"
  }
}

Limits and gotchas

Client names are not unique, so two clients can share a name. Pass client_id when a name is ambiguous.
An agent with a Read only key can list clients but cannot create them; the call is rejected with a permission message.
Deleting a client is a dashboard action, not an MCP tool, and a client with documents should be kept for history.

Troubleshooting

create_client is refused with a scope error: The key covers more than one business, so pass business_id. Run list_businesses first to see the ids in scope.
The agent bills the wrong Harbor & Lane: Duplicate or similar names exist. Use list_clients with a search term, then pass the exact client_id to the billing tool.
Invoices come out in the wrong currency: The client currency decides it. Update the client with update_client before drafting, and remember existing drafts keep the currency they were created in.

Sources

Reviewed 2026-09-20 against Billr's own tool implementations and the client documentation linked above.