Tools Disponíveis
Lista completa de ferramentas MCP disponíveis no bitERP com parâmetros e exemplos.
O MCP Server expõe ferramentas (tools) que o agente de IA pode invocar para executar operações de negócio. O agente decide quando usar cada tool com base no contexto da conversa.
Fluxo padrão
Toda interação com o MCP Server segue este padrão:
get_user_data— O agente obtém o perfil do usuáriolist_tenants— O agente descobre os tenants disponíveis- Operações de negócio — O agente usa as tools de CRUD passando o
tenant_id
Dados do usuário
get_user_data
Retorna o perfil do usuário autenticado.
| Campo | Tipo | Descrição |
|---|---|---|
| — | — | Nenhum parâmetro necessário |
Resposta:
{
"id": "uuid",
"email": "usuario@empresa.com",
"name": "Nome do Usuário",
"language": "pt-BR",
"timezone": "America/Sao_Paulo"
}Tenants
list_tenants
Lista os tenants (empresas) que o usuário pode acessar. Deve ser chamada antes de qualquer operação de negócio.
| Campo | Tipo | Descrição |
|---|---|---|
| — | — | Nenhum parâmetro necessário |
Resposta:
[
{
"tenant": "minha-empresa",
"company_name": "Minha Empresa Ltda",
"role": "admin"
}
]Se o usuário tem acesso a apenas um tenant, o agente o usa automaticamente. Se há múltiplos, o agente pergunta qual usar.
Produtos
Todas as tools de produtos requerem o parâmetro tenant_id (obtido via list_tenants).
list_products
Lista todos os produtos do tenant.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
tenant_id | string (UUID) | Sim | ID do tenant |
search | string | Não | Busca por texto |
active_only | boolean | Não | Filtrar apenas ativos |
Permissão necessária: products:read
get_product
Busca um produto por ID.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
tenant_id | string (UUID) | Sim | ID do tenant |
id | string (UUID) | Sim | ID do produto |
Permissão necessária: products:read
create_product
Cria um novo produto.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
tenant_id | string (UUID) | Sim | ID do tenant |
name | string | Sim | Nome do produto |
sale_price | number | Sim | Preço de venda |
description | string | Não | Descrição |
sku | string | Não | Código SKU |
is_active | boolean | Não | Ativo (padrão: true) |
Permissão necessária: products:create
update_product
Atualiza um produto existente (partial update).
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
tenant_id | string (UUID) | Sim | ID do tenant |
id | string (UUID) | Sim | ID do produto |
name | string | Não | Novo nome |
sale_price | number | Não | Novo preço |
description | string | Não | Nova descrição |
is_active | boolean | Não | Ativar/desativar |
Permissão necessária: products:update
delete_product
Remove um produto (soft delete — pode ser recuperado).
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
tenant_id | string (UUID) | Sim | ID do tenant |
id | string (UUID) | Sim | ID do produto |
Permissão necessária: products:delete
Annotations
Cada tool inclui annotations que descrevem seu comportamento:
| Tool | Read-only | Destrutiva |
|---|---|---|
get_user_data | Sim | — |
list_tenants | Sim | — |
list_products | Sim | — |
get_product | Sim | — |
create_product | — | Não |
update_product | — | Sim |
delete_product | — | Sim |
O cliente MCP pode usar essas annotations para pedir confirmação do usuário antes de executar operações destrutivas.
Paginação por cursor
Tools de listagem que retornam muitos registros usam paginação por cursor:
| Parâmetro | Tipo | Descrição |
|---|---|---|
cursor | string | Cursor da página anterior (omitir na primeira chamada) |
limit | number | Itens por página (padrão: 20, máximo: 100) |
O agente itera automaticamente até has_next_page ser false, agregando os resultados antes de apresentar ao usuário.