# Mercos — how to use (mcp.ai)

Sales force and rep ERP on Mercos via the official API. List orders, customers, products, price tables, payment terms, carriers, sellers and commissions, and create or update customers, products, orders and stock in natural language. Auth via a Company Token, generated in the Mercos account under My Account, System, Integration.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_mercos?ms=1782769080000`
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. `mercos_ajustar_estoque`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/mercos`
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/mercos/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/mercos/ajustar/estoque` — Ajusta o estoque de produtos em lote (POST /v1/ajustar_estoque_em_lote). `data` = array de ajustes.
  - body: { data: string, account?: string }
- `POST https://api.mcp.ai/api/mercos/create/cliente` — Inclui cliente(s) (POST /v1/clientes). `data` = objeto ou array de clientes.
  - body: { data: string, account?: string }
- `POST https://api.mcp.ai/api/mercos/create/pedido` — Inclui um pedido (POST /v2/pedidos). `data` com cliente, itens, condição de pagamento etc.
  - body: { data: string, account?: string }
- `POST https://api.mcp.ai/api/mercos/create/produto` — Inclui produto(s) (POST /v1/produtos). `data` = objeto ou array de produtos.
  - body: { data: string, account?: string }
- `POST https://api.mcp.ai/api/mercos/create/tabela/preco` — Inclui uma tabela de preço (POST /v1/tabelas_preco). `data` com os campos da tabela.
  - body: { data: string, account?: string }
- `POST https://api.mcp.ai/api/mercos/list/accounts` — Lista as empresas (CompanyToken) Mercos conectadas a este install, com id e label.
  - body: { account?: string }
- `POST https://api.mcp.ai/api/mercos/list/categorias` — Lista categorias de produtos (GET /v1/categorias).
  - body: { alterado_apos?: string, filters?: string, account?: string }
- `POST https://api.mcp.ai/api/mercos/list/clientes` — Lista clientes (GET /v1/clientes). Use `alterado_apos` pra incremental.
  - body: { alterado_apos?: string, filters?: string, account?: string }
- `POST https://api.mcp.ai/api/mercos/list/comissoes` — Lista comissões (GET /v1/comissoes). Filtre por colaborador_id ou pedido_id via `filters`.
  - body: { alterado_apos?: string, filters?: string, account?: string }
- `POST https://api.mcp.ai/api/mercos/list/condicoes/pagamento` — Lista condições de pagamento (GET /v1/condicoes_pagamento).
  - body: { alterado_apos?: string, filters?: string, account?: string }
- `POST https://api.mcp.ai/api/mercos/list/pedidos` — Lista pedidos (GET /v2/pedidos). Use `alterado_apos` pra incremental. (Pedidos vivem na v2.)
  - body: { alterado_apos?: string, filters?: string, account?: string }
- `POST https://api.mcp.ai/api/mercos/list/produtos` — Lista produtos cadastrados (GET /v1/produtos). Use `alterado_apos` pra incremental.
  - body: { alterado_apos?: string, filters?: string, account?: string }
- `POST https://api.mcp.ai/api/mercos/list/tabelas/preco` — Lista tabelas de preço (GET /v1/tabelas_preco).
  - body: { alterado_apos?: string, filters?: string, account?: string }
- `POST https://api.mcp.ai/api/mercos/list/titulos` — Lista títulos financeiros (GET /v1/titulos).
  - body: { alterado_apos?: string, filters?: string, account?: string }
- `POST https://api.mcp.ai/api/mercos/list/transportadoras` — Lista transportadoras (GET /v1/transportadoras).
  - body: { alterado_apos?: string, filters?: string, account?: string }
- `POST https://api.mcp.ai/api/mercos/list/usuarios` — Lista vendedores/usuários (GET /v1/usuarios).
  - body: { alterado_apos?: string, filters?: string, account?: string }
- `POST https://api.mcp.ai/api/mercos/update/cliente` — Altera um cliente (PUT /v1/clientes/{id}). `id` + `data` com os campos a alterar.
  - body: { id: string, data: string, account?: string, ids?: string[] }
- `POST https://api.mcp.ai/api/mercos/update/pedido` — Altera um pedido (PUT /v2/pedidos/{id}). `id` + `data` com os campos a alterar.
  - body: { id: string, data: string, account?: string, ids?: string[] }
- `POST https://api.mcp.ai/api/mercos/update/produto` — Altera um produto (PUT /v1/produtos/{id}). `id` + `data` com os campos a alterar.
  - body: { id: string, data: string, account?: string, ids?: string[] }

## Example prompts
- "List orders changed since yesterday"
- "Create a new customer from these details"
- "List commissions for the seller with colaborador_id 123"

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