Lares MCP connector

Lares is a remote Model Context Protocol server that gives Muse read-only access to a user's household bills.

Connection

Endpoint	`https://api.uselares.com/mcp`
Transport	Streamable HTTP (stateless, JSON responses)
Authorization	OAuth 2.1 authorization code with PKCE (S256). Metadata: `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`. Access tokens are audience-bound to the MCP endpoint.
Scope	`bills:read`
Availability	U.S. households. Muse only.

Conventions

Money values are exact decimal strings in USD, e.g. "286.42". Totals are computed server-side with exact arithmetic.
Bills with low_confidence: true have values that couldn't be fully verified and should be presented as uncertain.
Category totals split combined bills (for example water, sewer, and garbage on one municipal bill) by line item, so nothing is counted twice.
Provider passwords and verification codes are never passed through tools. Tools return a secure credential_url or action_url for the user to open.
Users are identified only by the access token, never by tool arguments.

Tools (13)

`search_providers`

read-onlyidempotent

Find a household service provider (utility, internet, mobile, garbage) to connect. Returns provider_id values for start_provider_connection.

Name	Type	Required	Notes
`query`	`string`	yes	Provider name, e.g. 'PG&E' or 'Xfinity' (≤80 chars)
`category`	`"ELECTRICITY" \| "WATER" \| "INTERNET" \| "MOBILE" \| "GARBAGE" \| "SEWER" \| "NATURAL_GAS"`	no	Household bill category

Returns: providers, note

`start_provider_connection`

writes connector state

Start connecting one of the user's provider accounts. Returns a secure credential_url the user must open to enter their sign-in details. Never collect passwords in chat. Then poll get_connection_status.

Name	Type	Required	Notes
`provider_id`	`string`	no	From search_providers (preferred) (≤80 chars)
`provider_name`	`string`	no	(≤80 chars)
`provider_website`	`string`	no	Required only for providers not found by search_providers (≤200 chars)
`category`	`"ELECTRICITY" \| "WATER" \| "INTERNET" \| "MOBILE" \| "GARBAGE" \| "SEWER" \| "NATURAL_GAS"`	no	Household bill category

Returns: connection_id, provider, provider_id, status, credential_url, expires_at, instructions

`get_connection_status`

read-only

Check a provider connection. If action_url is present the user must open it (credentials, verification code, or security check).

Name	Type	Required	Notes
`connection_id`	`string`	yes

Returns: connection_id, provider, status, action_url, message, error_code, accounts, latest_run

`get_account_updates`

read-only

What needs the user's attention: connections waiting for a verification code, new sign-in details, or a security check (each with an action_url), bills retrieved since a time, and bills due within 7 days. Call this during background checks and when the user returns; notify the user only about needs_user_action items and newly due bills.

Name	Type	Required	Notes
`since`	`ISO datetime`	no	ISO timestamp of the last check (default: 7 days ago)

Returns: checked_at, since, needs_user_action, new_bills, due_within_7_days

`list_bill_accounts`

read-onlyidempotent

List the user's connected household bill accounts with each account's latest bill.

Name	Type	Required	Notes
`category`	`"ELECTRICITY" \| "WATER" \| "INTERNET" \| "MOBILE" \| "GARBAGE" \| "SEWER" \| "NATURAL_GAS"`	no	Household bill category
`status`	`"ACTIVE" \| "REAUTHENTICATION_REQUIRED" \| "ERROR" \| "DISCONNECTED"`	no

Returns: accounts

`get_current_bill`

read-onlyidempotent

Latest bill for each matching account (all accounts if no filter). Use for 'how much do I owe this month'.

Name	Type	Required	Notes
`account_id`	`string`	no
`category`	`"ELECTRICITY" \| "WATER" \| "INTERNET" \| "MOBILE" \| "GARBAGE" \| "SEWER" \| "NATURAL_GAS"`	no	Household bill category

Returns: bills, totals

`get_bill_history`

read-onlyidempotent

Bills for one account, newest first, optionally within a statement-date range.

Name	Type	Required	Notes
`account_id`	`string`	yes
`start_date`	`YYYY-MM-DD`	no	Date as YYYY-MM-DD
`end_date`	`YYYY-MM-DD`	no	Date as YYYY-MM-DD
`limit`	`integer`	no	(min 1, max 60)

Returns: account, bills, totals

`get_bill_details`

read-onlyidempotent

Full detail for one bill: line items, fees, taxes, credits, usage, and per-category split. Use to explain what a bill is for or why it changed.

Name	Type	Required	Notes
`bill_id`	`string`	yes

Returns: bill, previous_balance, payments_received, line_items, fees, taxes, credits, usage, by_category, document_available, validation

`search_bills`

read-onlyidempotent

Find bills across all accounts by date range, category, provider, account, or status, with exact totals and a per-category split (combined bills are split by line item, never double counted). Use for questions like 'what did I spend on household bills in August'.

Name	Type	Required	Notes
`start_date`	`YYYY-MM-DD`	no	Date as YYYY-MM-DD
`end_date`	`YYYY-MM-DD`	no	Date as YYYY-MM-DD
`date_basis`	`"statement_date" \| "due_date"`	no	Which date the range applies to (default statement_date)
`category`	`"ELECTRICITY" \| "WATER" \| "INTERNET" \| "MOBILE" \| "GARBAGE" \| "SEWER" \| "NATURAL_GAS"`	no	Household bill category
`provider_id`	`string`	no	(≤80 chars)
`account_id`	`string`	no
`status`	`"DUE" \| "PAID" \| "PAST_DUE" \| "UNKNOWN"`	no
`limit`	`integer`	no	(min 1, max 200)

Returns: bills, matched_count, truncated, totals, basis_note

`refresh_account`

writes connector stateidempotent

Queue a background refresh of an account's bills from the provider. Returns immediately; check progress with get_connection_status.

Name	Type	Required	Notes
`account_id`	`string`	yes

Returns: run_id, status, connection_id

`disconnect_account`

writes connector statedestructiveidempotent

Stop all future retrieval for a provider connection and delete its stored credentials. Bill history is kept. Confirm with the user first.

Name	Type	Required	Notes
`connection_id`	`string`	yes
`confirm`	`"true"`	yes	Must be true; confirm with the user before calling

Returns: connection_id, status, credentials_deleted, bill_history_retained, delete_hint

`start_account_setup`

writes connector state

Optionally add an email and password to the user's Lares account, so they can use the account page, keep their connections if they re-add Lares, and get email alerts. Sends an email with a link; show the user the returned confirmation_code, which they'll enter on that page. Only call this when the user asks or agrees.

Name	Type	Required	Notes
`email`	`string`	yes	The user's email address (≤254 chars)

Returns: status, email, confirmation_code, message

`get_account_page_link`

writes connector state

A single-use link (valid 15 minutes) to the user's Lares account page, where they can see connected providers, disconnect them, or delete all their data. Use when the user wants to manage or delete their Lares data.

No parameters.

Returns: account_url, expires_at