# TOTVS Protheus — how to use (mcp.ai)

TOTVS Protheus ERP through the official REST API of your own installation. You provide the REST service URL, your Protheus user and password, and the platform authenticates against your server's oAuth2 API to read your data. Read-only: branches, customers and vendors, products, stock balance, price lists, retail sales and orders, invoice totals, production orders, MRP purchasing, cost centers, sales commissions and credit limits. Since every Protheus installation publishes a different set of APIs, there is a diagnostic tool that discovers what yours answers, and another that calls any REST route, including your company's custom ones.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_protheus?ms=1788152400000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `protheus_api`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/protheus`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/protheus/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/protheus/api` — Faz um GET em qualquer rota REST da instalação Protheus conectada. Use para as APIs oficiais que não têm tool dedicada (descubra a rota com protheus_catalogo) e para os endpoints MVC customizados que 
  - body: { path: string, page?: integer, page_size?: integer, order?: string, fields?: string, filter?: string, expand?: string, sql_filter?: string, params?: object, account?: string }
- `POST https://api.mcp.ai/api/protheus/catalogo` — Consulta o catálogo das 125 APIs REST oficiais da linha Protheus (id, título, módulo e rotas de leitura), extraído da documentação pública da TOTVS. Serve para descobrir qual rota passar em protheus_a
  - body: { termo?: string, segmento?: string, limit?: integer, account?: string }
- `POST https://api.mcp.ai/api/protheus/centros/custo` — Lista os centros de custo da contabilidade, ou consulta um pelo id interno.
  - body: { id?: string, page?: integer, page_size?: integer, order?: string, fields?: string, filter?: string, expand?: string, sql_filter?: string, params?: object, account?: string, ids?: string[] }
- `POST https://api.mcp.ai/api/protheus/clientes/fornecedores` — Consulta o cadastro de clientes e fornecedores (API CustomerVendor). Sem filtro traz a coleção inteira; `tipo` separa a entidade e, junto com `id`, traz um registro específico.
  - body: { tipo?: string, id?: string, page?: integer, page_size?: integer, order?: string, fields?: string, filter?: string, expand?: string, sql_filter?: string, params?: object, account?: string, ids?: string[] }
- `POST https://api.mcp.ai/api/protheus/comissoes` — Consulta as comissões de venda, ou uma comissão pelo id interno.
  - body: { id?: string, page?: integer, page_size?: integer, order?: string, fields?: string, filter?: string, expand?: string, sql_filter?: string, params?: object, account?: string, ids?: string[] }
- `POST https://api.mcp.ai/api/protheus/compras/mrp` — Consulta os pedidos de compra ou as solicitações de compra do MRP. Aceita filtros da API em `params` (branchId, product, deliveryDate, warehouse). Com `branch_id` e `codigo` traz um registro específic
  - body: { tipo?: string, branch_id?: string, codigo?: string, page?: integer, page_size?: integer, order?: string, fields?: string, filter?: string, expand?: string, sql_filter?: string, params?: object, account?: string, branch_ids?: string[] }
- `POST https://api.mcp.ai/api/protheus/condicoes/pagamento` — Lista as condições de pagamento cadastradas, ou consulta uma pelo id interno.
  - body: { id?: string, page?: integer, page_size?: integer, order?: string, fields?: string, filter?: string, expand?: string, sql_filter?: string, params?: object, account?: string, ids?: string[] }
- `POST https://api.mcp.ai/api/protheus/contatos` — Lista os contatos do CRM, ou consulta um contato por id.
  - body: { id?: string, page?: integer, page_size?: integer, order?: string, fields?: string, filter?: string, expand?: string, sql_filter?: string, params?: object, account?: string, ids?: string[] }
- `POST https://api.mcp.ai/api/protheus/diagnostico` — Descobre quais APIs REST esta instalação Protheus realmente responde. Sonda cada API do catálogo oficial com uma consulta mínima e classifica em disponivel, ausente, sem_permissao ou erro. Rode isto p
  - body: { termo?: string, limit?: integer, account?: string }
- `POST https://api.mcp.ai/api/protheus/estoque` — Consulta o saldo em estoque. Escolha a fonte: varejo (saldo em estoque do varejo) ou mrp (estoque do MRP, com armazém, lote e saldos bloqueado, consignado e em controle de qualidade). São módulos dist
  - body: { fonte?: string, page?: integer, page_size?: integer, order?: string, fields?: string, filter?: string, expand?: string, sql_filter?: string, params?: object, account?: string }
- `POST https://api.mcp.ai/api/protheus/filiais` — Lista as empresas e filiais do grupo (API TSIBranches). É o ponto de partida prático: os códigos de empresa e filial daqui alimentam o header tenantId da conexão e os filtros branchId das demais tools
  - body: { page?: integer, page_size?: integer, order?: string, fields?: string, filter?: string, expand?: string, sql_filter?: string, params?: object, account?: string }
- `POST https://api.mcp.ai/api/protheus/limite/credito` — Consulta o limite de crédito dos clientes. Com `cliente_id` traz o limite de um cliente específico.
  - body: { cliente_id?: string, page?: integer, page_size?: integer, order?: string, fields?: string, filter?: string, expand?: string, sql_filter?: string, params?: object, account?: string, cliente_ids?: string[] }
- `POST https://api.mcp.ai/api/protheus/list/accounts` — Lista as instalações Protheus conectadas a este install, com id e label (host/usuário).
  - body: { account?: string }
- `POST https://api.mcp.ai/api/protheus/modulos` — Lista os módulos do sistema Protheus nesta instalação. Indica o que está ativo e ajuda a explicar por que uma API responde ou não.
  - body: { page?: integer, page_size?: integer, order?: string, fields?: string, filter?: string, expand?: string, sql_filter?: string, params?: object, account?: string }
- `POST https://api.mcp.ai/api/protheus/notas/totais` — Consulta os totais de notas fiscais de saída ou de entrada do varejo, incluindo a visão de notas canceladas.
  - body: { tipo?: string, canceladas?: boolean, page?: integer, page_size?: integer, order?: string, fields?: string, filter?: string, expand?: string, sql_filter?: string, params?: object, account?: string }
- `POST https://api.mcp.ai/api/protheus/oportunidades` — Lista as oportunidades comerciais do CRM, ou consulta uma oportunidade pelo id interno.
  - body: { id?: string, page?: integer, page_size?: integer, order?: string, fields?: string, filter?: string, expand?: string, sql_filter?: string, params?: object, account?: string, ids?: string[] }
- `POST https://api.mcp.ai/api/protheus/ordens/producao` — Consulta as ordens de produção do MRP. Aceita filtros da própria API em `params` (branchId, product, warehouse, deliveryDate, startDate). Com `branch_id` e `codigo` traz uma ordem específica.
  - body: { branch_id?: string, codigo?: string, page?: integer, page_size?: integer, order?: string, fields?: string, filter?: string, expand?: string, sql_filter?: string, params?: object, account?: string, branch_ids?: string[] }
- `POST https://api.mcp.ai/api/protheus/parametros` — Consulta os parâmetros de sistema do Protheus.
  - body: { page?: integer, page_size?: integer, order?: string, fields?: string, filter?: string, expand?: string, sql_filter?: string, params?: object, account?: string }
- `POST https://api.mcp.ai/api/protheus/pedidos/varejo` — Lista os pedidos de venda do varejo. Com `id`, retorna os itens daquele pedido.
  - body: { id?: string, page?: integer, page_size?: integer, order?: string, fields?: string, filter?: string, expand?: string, sql_filter?: string, params?: object, account?: string, ids?: string[] }
- `POST https://api.mcp.ai/api/protheus/produtos` — Consulta o cadastro de produtos. O Protheus expõe produto por módulo, então escolha a fonte: varejo (API de produtos do varejo) ou mrp (produto do planejamento de manufatura). São cadastros diferentes
  - body: { fonte?: string, page?: integer, page_size?: integer, order?: string, fields?: string, filter?: string, expand?: string, sql_filter?: string, params?: object, account?: string }
- `POST https://api.mcp.ai/api/protheus/propostas/comerciais` — Lista as propostas comerciais de uma oportunidade, ou consulta uma proposta específica. No Protheus a proposta vive dentro da oportunidade, então `oportunidade_id` é obrigatório.
  - body: { oportunidade_id: string, id?: string, page?: integer, page_size?: integer, order?: string, fields?: string, filter?: string, expand?: string, sql_filter?: string, params?: object, account?: string, oportunidade_ids?: string[], ids?: string[] }
- `POST https://api.mcp.ai/api/protheus/tabela/precos` — Consulta as tabelas de preço. Sem argumentos lista os cabeçalhos; com `codigo` traz uma tabela; com `codigo` e `itens` traz os itens e preços dela.
  - body: { codigo?: string, itens?: boolean, page?: integer, page_size?: integer, order?: string, fields?: string, filter?: string, expand?: string, sql_filter?: string, params?: object, account?: string }
- `POST https://api.mcp.ai/api/protheus/transportadoras` — Lista as transportadoras cadastradas, ou consulta uma pelo id interno.
  - body: { id?: string, page?: integer, page_size?: integer, order?: string, fields?: string, filter?: string, expand?: string, sql_filter?: string, params?: object, account?: string, ids?: string[] }
- `POST https://api.mcp.ai/api/protheus/usuarios` — Lista os usuários do Protheus, ou consulta um usuário por id.
  - body: { id?: string, page?: integer, page_size?: integer, order?: string, fields?: string, filter?: string, expand?: string, sql_filter?: string, params?: object, account?: string, ids?: string[] }
- `POST https://api.mcp.ai/api/protheus/vendas/varejo` — Consulta as vendas do varejo, ou uma venda pelo id interno. Exige o módulo de varejo publicado nesta instalação.
  - body: { id?: string, page?: integer, page_size?: integer, order?: string, fields?: string, filter?: string, expand?: string, sql_filter?: string, params?: object, account?: string, ids?: string[] }
- `POST https://api.mcp.ai/api/protheus/vendedores` — Lista os vendedores cadastrados, ou consulta um vendedor pelo código.
  - body: { id?: string, page?: integer, page_size?: integer, order?: string, fields?: string, filter?: string, expand?: string, sql_filter?: string, params?: object, account?: string, ids?: string[] }

## Example prompts
- "Which Protheus APIs does my installation answer?"
- "List the group's branches and company codes"
- "What is today's stock balance by product?"

## More
- Page: https://mcp.ai/protheus
- Agent spec (llms.txt): https://mcp.ai/protheus/llms.txt
- Postman collection: https://mcp.ai/protheus/postman.json