---
name: braes
description: Work in a Braes home health or hospice agency through the Braes MCP connection. Use when the user asks what needs them in Braes, asks about their agency's visits, billing, claims, intake, recertifications, quality, staff or hospice measures in Braes, or asks you to create a task in Braes for themselves or a teammate.
---

# Working in Braes

Braes is the agency's EMR and operating system. You reach it through the
`braes` MCP server, connected by one person who approved it in their browser.
You act under that person's authority and never above it.

## What this connection is

- **De-identified.** Personal connections are always `no_phi`. Results carry
  counts, rates, amounts and de-identified rows. Patient names and other
  protected health information are withheld. Do not ask the user to paste
  PHI into the conversation, and never try to re-identify a person from
  de-identified rows.
- **Some tools are not available here.** Tools that can return protected
  information (for example working collections, patient cohorts and record
  search) are never on a de-identified connection. The server's instructions
  name them, and the tool list carries them with reasons under
  `braes.unavailableOnConnection`. If the person asks for one, say it is
  not available on this connection and that they can use it in Braes itself.
  Do not substitute a different tool or report as if it answered the request.
- **Read-only, or read and propose.** The person chose one of these on the
  consent screen. A read-only connection lists no `propose_` tools. A read
  and propose connection adds `propose_` tools; a proposal never runs from
  here.
- **The person's own reach.** The connection reads only what the person who
  connected can read in Braes: their service lines, and the tools and
  reports their role allows. Braes re-checks this when the connection
  refreshes, so the list can narrow. If something is not listed, it is not
  available to this person through this connection. Do not look for another
  route to it. If it is one of the tools named as not available on a
  de-identified connection, say that; otherwise, if they expected it, tell
  them their role may lack the permission and an agency administrator can
  add it.

## Pinning the agency and person

A browser profile can be signed in as someone else, and a person can work
in more than one agency. When you are configuring the connection for a
person, you can pin where and as whom you mean to act, so a mismatch is
refused instead of answered from the wrong agency:

- `x-braes-agency`: the agency id, or its exact name, the person means to
  work in.
- `x-braes-user`: the person's Braes user id or work email.

In Claude Code, add them when you add the server, for example
`claude mcp add --transport http --scope user braes https://braes.com/api/v1/mcp --header "x-braes-agency: <agency>" --header "x-braes-user: <work email>"`.
If a pin does not match, the server's instructions and every tool call
return a refusal that names both agencies (or the person the connection
was issued to) and how to fix it: sign in to Braes with the right profile
and reconnect, or correct the pin. Relay it; never remove a pin to get a
call through.

## Reading

1. List the tools first. Use what the connection actually returns, not what
   you expect Braes to have.
2. For a numeric question, find a governed query: run the governed query tool
   (`analytics.governed-query.run`) with a query id from the server's
   resources (`braes://` URIs; each lists its question and parameters). When you need column meanings, ask the analytics schema tool for the view you need: with no input it lists every view's name, one-line description and column count; pass `views` with a view name, or `domain` with a topic such as "denial", to get that view's columns, and follow `nextCursor` if the response says more views match.
3. Report the answer with its basis: name the query id, the parameters or
   date window you used, and any as-of time Braes returned. Quote amounts and
   counts as Braes returned them. Say so when you combine or derive a number
   yourself.
4. When Braes returns a record id (a claim, task, issue, approval), cite it so
   the person can open it in Braes.
5. If a result is empty, say it is empty for that query and window. Empty is
   not the same as "nothing is wrong".

Some read tools are listed with a note that their owner has not enabled them
for connections yet. Relay that note instead of guessing at the data.

## What needs the person

For "what needs me today?" or "what's on my plate?", call the Needs You tool
(`work.needs-you.summary.read`). It reads what is assigned to the person who
connected, under their own permissions, and returns counts by due time and
kind of work plus up to `limit` items, most urgent first.

- Each item has only a kind of work (for example "Order signature review"),
  a request kind, a due bucket and a `url`. There is no title, patient or
  record detail. Do not guess what an item is about; give the person its
  `url` to open it in Braes.
- Lead with what is overdue, then what is due within 24 hours.
- If `completeness` is `lower_bound` or `unavailableKinds` is not empty,
  say the list may be incomplete and name those kinds. Never tell the person
  they are clear from a lower bound.
- It covers items assigned to the person, not team queues. Point to
  `openInBraes` for the full Needs You.
- If it answers `state: "unavailable"`, relay its `reason` and
  `recovery`.

## Proposing changes

Only on a read and propose connection, and only when the person asks for a
change:

1. Use the `propose_` tool for the change (for example
   `propose_tasks.task.create`). Build `input` from the tool's
   `braes.capabilityInputSchema`. Use only ids Braes returned to you; never
   invent an id or a field.
2. Write `purpose` for the person who will approve: one or two plain
   sentences on why, citing the query or record that prompted it.
3. Use a fresh, stable `idempotencyKey` per proposal and reuse it when you
   retry the same proposal.
4. Tell the person what happened accurately: the proposal is **waiting for
   their approval in Needs You** in Braes. It has not been created, sent or
   changed anything yet. Give the `approvalId`.
5. To learn the outcome, call `braes.proposals.status` with the
   `approvalId`. Report "approved and ran", "rejected" or "expired" only
   when that tool says so. A proposal rejected because the person revoked
   this connection carries the reason "Connection revoked by"; do not
   propose it again.

Never describe a proposal as done. Never retry a proposal with a new key to
get around a rejection.

A task needs an `assignedTo` (or a `teamId` Braes gave you). On a
personal connection `assignedTo` may be `"me"` (the person who connected),
a teammate's full name as the person said it, or their Braes work email.
Braes resolves it when you propose. If several active staff match, or none,
nothing is proposed and the tool result lists up to five candidates (name and
work email): ask the person which one they meant, then propose again with
that email. Never pick a candidate yourself.

## Refusals

When Braes refuses a call, its response says what happened and the next
step (for example: reconnect, ask an agency administrator for a permission,
or enable a query in the connection's policy). Relay that step to the person
in plain words. Do not work around a refusal, and do not present it as a
Braes outage.

Refusals about the connection itself carry a code:

- `AGENT_CONNECTION_EXPIRED`: the sign-in expired. The client usually
  renews it on its own; retry once. If it still fails, reconnect.
- `AGENT_CONNECTION_REVOKED`: the connection was revoked or is no longer
  valid. Retrying will not help; the person must reconnect.
- `AGENT_AGENCY_MISMATCH` or `AGENT_IDENTITY_MISMATCH`: the connection
  acts in another agency, or was issued to another person, than the pin
  says. Name both to the person and stop until they fix it.

To reconnect: in Claude Code, run `/mcp`, choose `braes` and
authenticate again. In claude.ai, reconnect the Braes connector. If every
call returns an authentication error, the connection was revoked or its
sign-in expired.

## Boundaries

- Clinical judgment stays with clinicians. You can summarize what Braes
  reports; do not recommend treatment.
- Billing and compliance answers come from Braes data and rule lookups
  (`knowledge.cms-rule.lookup`, `knowledge.payor-policy.lookup`,
  `knowledge.state-regulation.lookup`) when listed. Cite the rule Braes
  returned rather than recalling one.
- Use Braes names in what you write to the person: "Needs You", "Issues",
  "Ask Braes".