# Tools · Resident companies

> MCP tools for resident companies (coworking): list, register, edit and close companies, your company, the team, invite by e-mail, mark the company admin and remove.

[Resident companies](/membros/empresas-residentes) through the assistant: register a company with its contract, edit, close, see your company, the team, invite by e-mail, follow, accept and decline invitations, mark the company admin and remove. There are **14 tools**.

Each tool has a badge: <span class="tool-kind tool-kind-read">Read-only</span> changes nothing, <span class="tool-kind tool-kind-write">Changes</span> creates or changes something right away, and <span class="tool-kind tool-kind-confirm">Asks to confirm</span> only acts after your yes to a summary. See [Money and confirmation](/mcp/dinheiro-e-confirmacao).

## At a glance

| Tool | What it does | Minimum role | Type |
|---|---|---|---|
| [`list_resident_companies`](#list-resident-companies) | The companies, with type, status and team size | Moderator or finance | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`get_resident_company`](#get-resident-company) | One company | Moderator or finance | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`get_my_resident_company`](#get-my-resident-company) | The company you are on, with the team | Any | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`create_resident_company`](#create-resident-company) | Registers a company with its contract | Admin | <span class="tool-kind tool-kind-write">Changes</span> |
| [`update_resident_company`](#update-resident-company) | Edits the name and the contract | Admin | <span class="tool-kind tool-kind-write">Changes</span> |
| [`close_resident_company`](#close-resident-company) | Ends the residence, with or without the team | Admin | <span class="tool-kind tool-kind-confirm">Asks to confirm</span> |
| [`list_resident_company_members`](#list-resident-company-members) | A company's team | Any (the API checks the link) | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`invite_resident_company_member`](#invite-resident-company-member) | Adds someone to the team by e-mail | Any (the API checks the link) | <span class="tool-kind tool-kind-write">Changes</span> |
| [`update_resident_company_member`](#update-resident-company-member) | Marks or unmarks the company admin | Admin | <span class="tool-kind tool-kind-write">Changes</span> |
| [`remove_resident_company_member`](#remove-resident-company-member) | Takes someone off the team | Any (the API checks the link) | <span class="tool-kind tool-kind-confirm">Asks to confirm</span> |
| [`list_resident_company_invitations`](#list-resident-company-invitations) | The pending invitations the company admin sent | Any (the API checks the link) | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`list_my_company_invitations`](#list-my-company-invitations) | Your company invitations | Any | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`accept_company_invitation`](#accept-company-invitation) | Accepts your invitation and joins the team | Any (their own invitation) | <span class="tool-kind tool-kind-write">Changes</span> |
| [`decline_company_invitation`](#decline-company-invitation) | Declines your invitation, for good | Any (their own invitation) | <span class="tool-kind tool-kind-confirm">Asks to confirm</span> |

The roles are the routes' roles: the assistant never does more than the connected person could do on screen. The owner and the admin see all 14; the moderator and finance, 10 (the two community-team reads and the eight open to any role); the member, 8 (`get_my_resident_company`, `list_resident_company_members`, `invite_resident_company_member`, `remove_resident_company_member`, `list_resident_company_invitations`, `list_my_company_invitations`, `accept_company_invitation` and `decline_company_invitation`).

**Eight tools appear for any role** because a company's admin is usually a regular member, and anyone can receive an invitation. The API decides by the link: the team is read only by the community team or the company's own people, and only the owner, the admin or that company's admin (while it is active) invites and removes. Everyone else gets "no permission".

**The company admin's invite depends on acceptance.** It never links right away, not even someone already in the community: the person receives the invitation by e-mail and joins the team only when they accept (`accept_company_invitation`). The community owner and admin still link directly.

**The contract stays with management.** The monthly value and the dates go to the owner, the admin and finance; the moderator reads companies without those keys, and `get_my_resident_company` never brings them. The monthly value is a record, not a charge.

**Leaving the team suspends billing.** When you remove someone or close the company with its team, the summary warns that billing for the removed person is suspended; the subscription stays on record until it is canceled, which you do in [Subscriptions](/mcp/ferramentas-assinaturas).

## `list_resident_companies`

<span class="tool-kind tool-kind-read">Read-only</span>

**The resident companies**, by name, with the residence type, the status (`active`, or `ended` when closed or past the exit date) and how many people are on the team. Companies are not members and never appear in member lists. The owner, the admin and finance also get the contract (monthly value, start, exit and closing date); the moderator does not. *Minimum role: moderator (or finance).*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `status` | `active` or `ended` | No | Filters by status |
| `search` | text | No | Part of the name |

**Ask like this:** *"Which companies are resident today?"*

## `get_resident_company`

<span class="tool-kind tool-kind-read">Read-only</span>

**One company.** With the contract for the owner, the admin and finance. A company from another community: "not found". A company admin uses `get_my_resident_company`. *Minimum role: moderator (or finance).*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `company_id` | id | Yes | The company (from `list_resident_companies`) |

**Ask like this:** *"When does Acme's contract end?"*

## `get_my_resident_company`

<span class="tool-kind tool-kind-read">Read-only</span>

**Your company.** The company the connected person is on (without the contract), whether they are its admin, the team, and `canManageTeam`, true for the admin of an active company (false once it is closed). With no company, returns `company: null`; pending invitations are in `list_my_company_invitations`. *Minimum role: any.*

No parameters.

**Ask like this:** *"Who is on my company's team?"*

## `create_resident_company`

<span class="tool-kind tool-kind-write">Changes</span>

**Register a company** with its contract. The company gets no login; people join with `invite_resident_company_member`. *Minimum role: admin (owner or admin).*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `name` | text | Yes | The name, up to 120 characters |
| `residence_type` | `PRIVATE_OFFICE`, `FIXED_DESK` or `VIRTUAL_OFFICE` | Yes | Private office, fixed desk or virtual office |
| `monthly_value` | number | Yes | The monthly value, zero or more. Record only, not charged |
| `starts_at` | YYYY-MM-DD | Yes | The contract start |
| `ends_at` | YYYY-MM-DD | No | The planned exit, not before the start |

**Ask like this:** *"Register Acme Tecnologia, private office, R$ 4,800 a month, since 11/1."*

## `update_resident_company`

<span class="tool-kind tool-kind-write">Changes</span>

**Edit.** Only what you send: name, type, value, start or exit (`ends_at: null` clears the exit). To close now, use `close_resident_company`. *Minimum role: admin (owner or admin).*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `company_id` | id | Yes | The company |
| `name`, `residence_type`, `monthly_value`, `starts_at`, `ends_at` | various | No | Only what changes |

**Ask like this:** *"Acme leaves on 12/31. Update the contract."*

## `close_resident_company`

<span class="tool-kind tool-kind-confirm">Asks to confirm</span>

**End the residence now.** The company stops accepting invites; the record and the contract stay on file. There is no reopening. With `remove_members` (default: true), everyone leaves the team, and whoever joined the community through the company and is still a member also leaves the community. The summary lists who leaves and warns that their billing is suspended and the subscription stays on record until it is canceled. An already closed company: refused. The first call returns the summary and the confirmation code. *Minimum role: admin (owner or admin).*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `company_id` | id | Yes | The company |
| `remove_members` | true/false | No | Default: true. False keeps the team linked to the closed company |

**Ask like this:** *"Close Acme and take its team off."*

## `list_resident_company_members`

<span class="tool-kind tool-kind-read">Read-only</span>

**A company's team**, admins first: name, job title, whether they are company admin, whether they joined through the company and, for the community team and the company admin, the e-mail. Readable by the community team or the company's own people. *Minimum role: any (the API checks the link).*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `company_id` | id | Yes | The company (from `list_resident_companies` or `get_my_resident_company`) |

**Ask like this:** *"Show Acme's team."*

## `invite_resident_company_member`

<span class="tool-kind tool-kind-write">Changes</span>

**Add to the team by e-mail.** By the **owner or admin**, it links right away: someone already in the community only gets the link, with no e-mail (`linked`); anyone else joins the community as a member and **receives the invite by e-mail** (`invited`): the assistant says so first. By the **company admin**, it never links: the answer is always `invited` with `pending: true` and the `invitation_id`, whoever the person is, and the assistant says *"Invitation sent. They join the team when they accept."*, without claiming whether they were already in the community. Refused if the community is not accepting new members, if the person asked not to take part, if they are already on this team or if the company is closed; for the owner and the admin, also if they are already on another company. The owner, the admin and that company's admin (while it is active) invite; `is_admin` only the owner and the admin. The company admin sends up to 30 invitations an hour (beyond that, 429 with `Retry-After`); the owner and the admin have no such limit. *Minimum role: any (the API checks the link).*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `company_id` | id | Yes | The company |
| `email` | text | Yes | The person's e-mail |
| `name` | text | No | The name, if the account is created now |
| `is_admin` | true/false | No | Joins as company admin right away (owner or admin) |

**Ask like this:** *"Invite joao@memberfy.net to my company's team."*

## `update_resident_company_member`

<span class="tool-kind tool-kind-write">Changes</span>

**Mark or unmark the company admin.** The company admin invites and removes their own team. *Minimum role: admin (owner or admin).*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `company_id` | id | Yes | The company |
| `profile_id` | id | Yes | The person (from `list_resident_company_members`) |
| `is_admin` | true/false | Yes | True marks; false unmarks |

**Ask like this:** *"Make Maria the admin of Acme."*

## `remove_resident_company_member`

<span class="tool-kind tool-kind-confirm">Asks to confirm</span>

**Take someone off the team.** If they joined the community through the company and are still a member, they also leave the community and lose access; if they were already in the community, they only lose the link. The summary says which, and warns that billing for the removed person is suspended and the subscription stays on record until it is canceled. The owner, the admin and that company's admin (while it is active) remove. The first call returns the summary and the confirmation code. *Minimum role: any (the API checks the link).*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `company_id` | id | Yes | The company |
| `profile_id` | id | Yes | The person (from `list_resident_company_members`) |

**Ask like this:** *"Take João off Acme's team; he left the company."*

## `list_resident_company_invitations`

<span class="tool-kind tool-kind-read">Read-only</span>

**The company's pending invitations**: the ones the company admin sent that nobody answered yet, newest first, with the e-mail typed and the date. It never says who the person is or whether they were already in the community. The owner's and the admin's invites link right away and do not show here. Readable by the community team and by that company's admin while it is active. *Minimum role: any (the API checks the link).*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `company_id` | id | Yes | The company |

**Ask like this:** *"Who did I invite to my company that hasn't accepted yet?"*

## `list_my_company_invitations`

<span class="tool-kind tool-kind-read">Read-only</span>

**Your invitations.** The connected person's pending invitations to join a team (*"you were invited to company X"*), newest first, with the company, who invited and the date. Only active companies of this community; with none, an empty list. *Minimum role: any.*

No parameters.

**Ask like this:** *"Do I have any company invitation?"*

## `accept_company_invitation`

<span class="tool-kind tool-kind-write">Changes</span>

**Accept your invitation.** The person joins the team (not as company admin). It does not ask for confirmation. Someone else's invitation, one already answered or from another community: "not found". A company closed after the invite, or a person already on another company's team: refused, with the API message. *Minimum role: any (their own invitation).*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `invitation_id` | id | Yes | The invitation (from `list_my_company_invitations`) |

**Ask like this:** *"Accept the invitation from Acme."*

## `decline_company_invitation`

<span class="tool-kind tool-kind-confirm">Asks to confirm</span>

**Decline your invitation.** No link is created and the invitation is gone for good: joining later needs a new invitation. The first call returns the summary and the confirmation code. *Minimum role: any (their own invitation).*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `invitation_id` | id | Yes | The invitation (from `list_my_company_invitations`) |

**Ask like this:** *"Decline the invitation from Acme."*

## Suggested recipes

- **Register a company:** register the company (`create_resident_company`), invite the person who will look after it (`invite_resident_company_member`) and mark them as company admin (`update_resident_company_member`, or `is_admin` right in the invite). Step by step in [Recipes](/mcp/receitas#69-register-a-resident-company).
- **The admin invites, the person accepts:** the company admin invites the colleague (`invite_resident_company_member`) and follows it in `list_resident_company_invitations`; the colleague sees the invitation (`list_my_company_invitations`) and accepts it (`accept_company_invitation`). Step by step in [Recipes](/mcp/receitas#70-invite-a-colleague-to-your-company).

## Related

- [Resident companies](/membros/empresas-residentes)
- [Tools](/mcp/ferramentas)
- [Tools · Members](/mcp/ferramentas-membros)
- [Money and confirmation](/mcp/dinheiro-e-confirmacao)
- [Recipes](/mcp/receitas)