# Ferramentas · Empresas residentes

> Ferramentas MCP das empresas residentes (coworking): listar, cadastrar, editar e encerrar empresas, a sua empresa, a equipe, convidar por e-mail, os convites com aceite, marcar o admin da empresa e remover.

As [Empresas residentes](/membros/empresas-residentes) pelo assistente: cadastrar a empresa com o contrato, editar, encerrar, ver a sua empresa, a equipe, convidar por e-mail, acompanhar, aceitar e recusar convites, marcar o admin da empresa e remover. São **14 ferramentas**.

Cada ferramenta traz um selo: <span class="tool-kind tool-kind-read">Só consulta</span> não muda nada, <span class="tool-kind tool-kind-write">Altera</span> cria ou muda algo na hora, e <span class="tool-kind tool-kind-confirm">Pede confirmação</span> só age depois do seu sim a um resumo. Ver [Dinheiro e confirmação](/mcp/dinheiro-e-confirmacao).

## Em resumo

| Ferramenta | O que faz | Papel mínimo | Tipo |
|---|---|---|---|
| [`list_resident_companies`](#list-resident-companies) | As empresas, com tipo, situação e tamanho da equipe | Moderador ou financeiro | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`get_resident_company`](#get-resident-company) | Uma empresa | Moderador ou financeiro | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`get_my_resident_company`](#get-my-resident-company) | A empresa em que você está, com a equipe | Qualquer | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`create_resident_company`](#create-resident-company) | Cadastra uma empresa com o contrato | Administrador | <span class="tool-kind tool-kind-write">Altera</span> |
| [`update_resident_company`](#update-resident-company) | Edita o nome e o contrato | Administrador | <span class="tool-kind tool-kind-write">Altera</span> |
| [`close_resident_company`](#close-resident-company) | Encerra a residência, com ou sem a equipe | Administrador | <span class="tool-kind tool-kind-confirm">Pede confirmação</span> |
| [`list_resident_company_members`](#list-resident-company-members) | A equipe de uma empresa | Qualquer (a API confere o vínculo) | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`invite_resident_company_member`](#invite-resident-company-member) | Inclui alguém na equipe pelo e-mail | Qualquer (a API confere o vínculo) | <span class="tool-kind tool-kind-write">Altera</span> |
| [`update_resident_company_member`](#update-resident-company-member) | Marca ou tira o admin da empresa | Administrador | <span class="tool-kind tool-kind-write">Altera</span> |
| [`remove_resident_company_member`](#remove-resident-company-member) | Tira alguém da equipe | Qualquer (a API confere o vínculo) | <span class="tool-kind tool-kind-confirm">Pede confirmação</span> |
| [`list_resident_company_invitations`](#list-resident-company-invitations) | Os convites pendentes que o admin da empresa enviou | Qualquer (a API confere o vínculo) | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`list_my_company_invitations`](#list-my-company-invitations) | Os seus convites de empresa | Qualquer | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`accept_company_invitation`](#accept-company-invitation) | Aceita o seu convite e entra na equipe | Qualquer (o seu convite) | <span class="tool-kind tool-kind-write">Altera</span> |
| [`decline_company_invitation`](#decline-company-invitation) | Recusa o seu convite, de vez | Qualquer (o seu convite) | <span class="tool-kind tool-kind-confirm">Pede confirmação</span> |

Os papéis são os das rotas: o assistente nunca faz mais do que a pessoa conectada faria na tela. O proprietário e o administrador veem as 14; o moderador e o financeiro, 10 (as duas de leitura da equipe da comunidade e as oito abertas a qualquer papel); o membro, 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` e `decline_company_invitation`).

**Oito ferramentas aparecem para qualquer papel** porque o admin de uma empresa costuma ser um membro comum, e qualquer pessoa pode receber um convite. A API decide pelo vínculo: a equipe só é lida por quem é da equipe da comunidade ou da própria empresa, e só convida e remove o proprietário, o administrador ou o admin daquela empresa, este enquanto ela está ativa. Os outros recebem "sem permissão".

**O convite do admin da empresa depende do aceite.** Ele nunca vincula na hora, nem quem já é da comunidade: a pessoa recebe o convite por e-mail e entra na equipe só quando aceitar (`accept_company_invitation`). O proprietário e o administrador da comunidade continuam vinculando direto.

**O contrato fica com a gestão.** O valor mensal e as datas vêm para o proprietário, o administrador e o financeiro; o moderador lê as empresas sem essas chaves, e `get_my_resident_company` nunca as traz. O valor mensal é um registro, sem cobrança.

**Sair da equipe suspende a cobrança.** Ao remover alguém ou encerrar a empresa com a equipe, o resumo avisa que a cobrança da pessoa removida é suspensa; a assinatura fica registrada até o cancelamento, que se faz em [Assinaturas](/mcp/ferramentas-assinaturas).

## `list_resident_companies`

<span class="tool-kind tool-kind-read">Só consulta</span>

**As empresas residentes**, em ordem de nome, com o tipo de residência, a situação (`active`, ou `ended` quando encerrada ou com a saída no passado) e quantas pessoas há na equipe. As empresas não são membros e nunca aparecem nas listas de membros. O proprietário, o administrador e o financeiro recebem também o contrato (valor mensal, início, saída e data de encerramento); o moderador, não. *Papel mínimo: moderador (ou financeiro).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `status` | `active` ou `ended` | Não | Filtra pela situação |
| `search` | texto | Não | Parte do nome |

**Peça assim:** *"Quais empresas estão residentes hoje?"*

## `get_resident_company`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Uma empresa.** Com o contrato para o proprietário, o administrador e o financeiro. Empresa de outra comunidade: "não encontrada". O admin de uma empresa usa `get_my_resident_company`. *Papel mínimo: moderador (ou financeiro).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `company_id` | id | Sim | A empresa (de `list_resident_companies`) |

**Peça assim:** *"Até quando vai o contrato da Acme?"*

## `get_my_resident_company`

<span class="tool-kind tool-kind-read">Só consulta</span>

**A sua empresa.** A empresa em que a pessoa conectada está (sem o contrato), se ela é admin da empresa, a equipe e `canManageTeam`, verdadeiro para o admin de uma empresa ativa (falso depois de encerrada). Sem empresa, devolve `company: null`; os convites pendentes estão em `list_my_company_invitations`. *Papel mínimo: qualquer.*

Sem parâmetros.

**Peça assim:** *"Quem está na minha empresa?"*

## `create_resident_company`

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

**Cadastrar uma empresa** com o contrato. A empresa não ganha login; as pessoas entram com `invite_resident_company_member`. *Papel mínimo: administrador (proprietário ou administrador).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `name` | texto | Sim | O nome, até 120 caracteres |
| `residence_type` | `PRIVATE_OFFICE`, `FIXED_DESK` ou `VIRTUAL_OFFICE` | Sim | Sala privativa, mesa fixa ou escritório virtual |
| `monthly_value` | número | Sim | O valor mensal, zero ou mais. Registro, sem cobrança |
| `starts_at` | AAAA-MM-DD | Sim | O início do contrato |
| `ends_at` | AAAA-MM-DD | Não | A saída prevista, não antes do início |

**Peça assim:** *"Cadastre a Acme Tecnologia, sala privativa, R$ 4.800 por mês, desde 1/11."*

## `update_resident_company`

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

**Editar.** Só o que você mandar: nome, tipo, valor, início ou saída (`ends_at: null` apaga a saída). Para encerrar agora, use `close_resident_company`. *Papel mínimo: administrador (proprietário ou administrador).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `company_id` | id | Sim | A empresa |
| `name`, `residence_type`, `monthly_value`, `starts_at`, `ends_at` | vários | Não | Só o que mudar |

**Peça assim:** *"A Acme sai em 31/12. Atualize o contrato."*

## `close_resident_company`

<span class="tool-kind tool-kind-confirm">Pede confirmação</span>

**Encerrar a residência agora.** A empresa deixa de aceitar convites; o cadastro e o contrato continuam registrados. Não há reabertura. Com `remove_members` (padrão: verdadeiro), todos saem da equipe, e quem entrou na comunidade pela empresa e ainda é membro sai também da comunidade. O resumo lista quem sai e avisa que a cobrança dessas pessoas é suspensa e a assinatura fica registrada até o cancelamento. Empresa já encerrada: recusado. Na primeira chamada devolve o resumo e o código de confirmação. *Papel mínimo: administrador (proprietário ou administrador).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `company_id` | id | Sim | A empresa |
| `remove_members` | verdadeiro/falso | Não | Padrão: verdadeiro. Falso mantém a equipe vinculada à empresa encerrada |

**Peça assim:** *"Encerre a Acme e tire a equipe dela."*

## `list_resident_company_members`

<span class="tool-kind tool-kind-read">Só consulta</span>

**A equipe de uma empresa**, com os admins primeiro: nome, cargo, se é admin da empresa, se entrou pela empresa e, para a equipe da comunidade e o admin da empresa, o e-mail. Lê quem é da equipe da comunidade ou da própria empresa. *Papel mínimo: qualquer (a API confere o vínculo).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `company_id` | id | Sim | A empresa (de `list_resident_companies` ou `get_my_resident_company`) |

**Peça assim:** *"Mostre a equipe da Acme."*

## `invite_resident_company_member`

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

**Incluir na equipe pelo e-mail.** Pelo **proprietário ou administrador**, vincula na hora: quem já é da comunidade só ganha o vínculo, sem e-mail (`linked`); quem não é entra na comunidade como membro e **recebe o convite por e-mail** (`invited`): o assistente avisa antes. Pelo **admin da empresa**, nunca vincula: a resposta é sempre `invited` com `pending: true` e o `invitation_id`, seja quem for a pessoa, e o assistente diz *"Convite enviado. A pessoa entra na equipe quando aceitar."*, sem afirmar se ela já era da comunidade. Recusado se a comunidade não está aceitando novos membros, se a pessoa pediu para não participar, se ela já está nesta equipe ou se a empresa está encerrada; para o proprietário e o administrador, também se ela já está noutra empresa. Convidam o proprietário, o administrador e o admin daquela empresa enquanto ela está ativa; `is_admin` só o proprietário e o administrador. O admin da empresa manda até 30 convites por hora (acima disso, 429 com `Retry-After`); o proprietário e o administrador não têm esse limite. *Papel mínimo: qualquer (a API confere o vínculo).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `company_id` | id | Sim | A empresa |
| `email` | texto | Sim | O e-mail da pessoa |
| `name` | texto | Não | O nome, se a conta for criada agora |
| `is_admin` | verdadeiro/falso | Não | Já entra como admin da empresa (proprietário ou administrador) |

**Peça assim:** *"Convide joao@memberfy.net para a equipe da minha empresa."*

## `update_resident_company_member`

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

**Marcar ou tirar o admin da empresa.** O admin da empresa convida e remove a própria equipe. *Papel mínimo: administrador (proprietário ou administrador).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `company_id` | id | Sim | A empresa |
| `profile_id` | id | Sim | A pessoa (de `list_resident_company_members`) |
| `is_admin` | verdadeiro/falso | Sim | Verdadeiro marca; falso tira |

**Peça assim:** *"Deixe a Maria como admin da Acme."*

## `remove_resident_company_member`

<span class="tool-kind tool-kind-confirm">Pede confirmação</span>

**Tirar alguém da equipe.** Se a pessoa entrou na comunidade pela empresa e ainda é membro, sai também da comunidade e perde o acesso; se já era da comunidade, só perde o vínculo. O resumo diz qual dos dois e avisa que a cobrança da pessoa removida é suspensa e a assinatura fica registrada até o cancelamento. Removem o proprietário, o administrador e o admin daquela empresa enquanto ela está ativa. Na primeira chamada devolve o resumo e o código de confirmação. *Papel mínimo: qualquer (a API confere o vínculo).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `company_id` | id | Sim | A empresa |
| `profile_id` | id | Sim | A pessoa (de `list_resident_company_members`) |

**Peça assim:** *"Tire o João da equipe da Acme; ele saiu da empresa."*

## `list_resident_company_invitations`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Os convites pendentes da empresa**: os que o admin da empresa enviou e ninguém respondeu, do mais novo ao mais antigo, com o e-mail digitado e a data. Nunca diz quem é a pessoa nem se ela já era da comunidade. Os convites do proprietário e do administrador vinculam na hora e não aparecem aqui. Leem a equipe da comunidade e o admin daquela empresa enquanto ela está ativa. *Papel mínimo: qualquer (a API confere o vínculo).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `company_id` | id | Sim | A empresa |

**Peça assim:** *"Quem eu convidei para a minha empresa e ainda não aceitou?"*

## `list_my_company_invitations`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Os seus convites.** Os convites pendentes da pessoa conectada para entrar numa equipe (*"você foi convidado para a empresa X"*), do mais novo ao mais antigo, com a empresa, quem convidou e a data. Só empresas ativas desta comunidade; sem convites, lista vazia. *Papel mínimo: qualquer.*

Sem parâmetros.

**Peça assim:** *"Tenho algum convite de empresa?"*

## `accept_company_invitation`

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

**Aceitar o seu convite.** A pessoa entra na equipe (sem ser admin da empresa). Não pede confirmação. Convite de outra pessoa, já respondido ou de outra comunidade: "não encontrado". Empresa encerrada depois do convite, ou pessoa já na equipe de outra empresa: recusado, com a mensagem da API. *Papel mínimo: qualquer (o seu convite).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `invitation_id` | id | Sim | O convite (de `list_my_company_invitations`) |

**Peça assim:** *"Aceite o convite da Acme."*

## `decline_company_invitation`

<span class="tool-kind tool-kind-confirm">Pede confirmação</span>

**Recusar o seu convite.** Nenhum vínculo é criado e o convite some de vez: para entrar depois, só com um convite novo. Na primeira chamada devolve o resumo e o código de confirmação. *Papel mínimo: qualquer (o seu convite).*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `invitation_id` | id | Sim | O convite (de `list_my_company_invitations`) |

**Peça assim:** *"Recuse o convite da Acme."*

## Receitas sugeridas

- **Cadastrar uma empresa:** cadastrar a empresa (`create_resident_company`), convidar quem vai cuidar dela (`invite_resident_company_member`) e marcá-la como admin da empresa (`update_resident_company_member`, ou `is_admin` já no convite). Passo a passo em [Receitas](/mcp/receitas#69-cadastrar-uma-empresa-residente).
- **O admin convida e a pessoa aceita:** o admin da empresa convida o colega (`invite_resident_company_member`) e acompanha em `list_resident_company_invitations`; o colega vê o convite (`list_my_company_invitations`) e aceita (`accept_company_invitation`). Passo a passo em [Receitas](/mcp/receitas#70-convidar-um-colega-para-a-sua-empresa).

## Relacionados

- [Empresas residentes](/membros/empresas-residentes)
- [Ferramentas](/mcp/ferramentas)
- [Ferramentas · Membros](/mcp/ferramentas-membros)
- [Dinheiro e confirmação](/mcp/dinheiro-e-confirmacao)
- [Receitas](/mcp/receitas)