MCP Advbox Server
Enables n8n workflows to automate operations on legal data from Advbox via MCP tools.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP Advbox Servershow my open lawsuits"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
📚 Documentação MCP Advbox Server
Versão: 2.2.0 (Hardened)
Última atualização: 05 de Janeiro de 2026
Autor: Jonas Sousa
📑 Índice
Related MCP server: mycase-mcp
1. Visão Geral
O que é o MCP Advbox?
O MCP Advbox Server é um servidor que implementa o protocolo Model Context Protocol (MCP) para integração com a API do Advbox, sistema de gestão jurídica. Ele permite que agentes de IA (como Claude) interajam diretamente com dados de clientes, processos, tarefas e transações financeiras do escritório.
Funcionalidades Principais
✅ 19 Tools para operações CRUD completas
✅ Autenticação segura via Bearer Token
✅ Rate Limiting para proteção contra abuso
✅ SSE (Server-Sent Events) para comunicação em tempo real
✅ Validação de entrada em todos os parâmetros
✅ Headers de segurança (HSTS, CSP, X-Frame-Options)
Casos de Uso
Caso de Uso | Descrição |
Consulta de clientes | Buscar informações de clientes por nome, telefone, email |
Gestão de processos | Criar, atualizar e consultar processos jurídicos |
Controle financeiro | Listar transações, receitas e despesas |
Agenda de compromissos | Criar e listar tarefas e compromissos |
Relatórios de equipe | Consultar pontuação e recompensas da equipe |
2. Arquitetura
Diagrama
┌─────────────────┐ HTTPS/SSE ┌──────────────────┐ HTTPS ┌─────────────────┐
│ Claude / n8n │ ◄────────────────► │ MCP Advbox API │ ◄────────────► │ Advbox API │
│ │ Bearer Token │ (Port 3847) │ API Token │ (v1) │
└─────────────────┘ └──────────────────┘ └─────────────────┘Stack Tecnológica
Componente | Tecnologia |
Runtime | Node.js 20 Alpine |
Linguagem | TypeScript |
Protocolo | MCP (Model Context Protocol) |
Transporte | HTTP + SSE |
Container | Docker |
Proxy | Traefik |
TLS | Let's Encrypt |
Estrutura de Arquivos
/opt/stacks/advbox-mcp-server/
├── src/
│ └── http-server.ts # Código principal
├── dist/
│ └── http-server.js # Código compilado
├── docs/
│ └── README.md # Esta documentação
├── docker-compose.yml
├── Dockerfile.http
├── package.json
├── tsconfig.json
└── .env3. Instalação
Pré-requisitos
Docker 24.0+
Docker Compose v2
Rede Docker
proxyconfiguradaTraefik com Let's Encrypt
Passo a Passo
# 1. Criar estrutura
mkdir -p /opt/stacks/advbox-mcp-server/src
cd /opt/stacks/advbox-mcp-server
# 2. Criar .env
cat > .env << EOF
ADVBOX_API_TOKEN=seu_token_advbox
ADVBOX_BASE_URL=https://app.advbox.com.br/api/v1
MCP_TOKEN=$(openssl rand -hex 32)
ALLOWED_ORIGINS=https://seu-dominio.com
EOF
# 3. Build e Deploy
docker compose build --no-cache advbox-api
docker compose up -d advbox-api
# 4. Verificar
curl http://localhost:3847/health4. Configuração
Variáveis de Ambiente
Variável | Obrigatório | Descrição |
| ✅ | Token de acesso à API Advbox |
| ❌ | URL base da API (default: https://app.advbox.com.br/api/v1) |
| ✅ | Token de autenticação do MCP |
| ❌ | Domínios permitidos (CORS) |
| ❌ | Porta interna (default: 3000) |
Limites de Segurança
Parâmetro | Valor | Descrição |
| 1 MB | Tamanho máximo do body |
| 100 req/min | Requests por IP |
| 100 | Conexões SSE simultâneas |
| 5 | Conexões SSE por IP |
| 1 hora | Timeout de conexão SSE |
5. Autenticação
Método
Bearer Token no header Authorization.
Header
Authorization: Bearer <MCP_TOKEN>Exemplo
curl -H "Authorization: Bearer <TOKEN>" https://<SEU_DOMINIO>/toolsErros
Status | Resposta | Causa |
401 |
| Token inválido |
429 |
| Rate limit |
6. Endpoints HTTP
Método | Endpoint | Auth | Descrição |
GET |
| ❌ | Health check |
GET |
| ✅ | Conexão SSE (MCP) |
POST |
| ✅ | Mensagem MCP |
GET |
| ✅ | Listar tools |
POST |
| ✅ | Executar tool |
GET /health
curl https://<SEU_DOMINIO>/health{"status":"healthy","version":"2.2.0","tools":19,"sse":0}POST /execute
curl -X POST \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-d '{"tool":"list_customers","arguments":{"limit":5}}' \
https://<SEU_DOMINIO>/execute7. Tools Disponíveis
Resumo (19 tools)
Categoria | Tools | Quantidade |
Customers | list, get, search, create | 4 |
Lawsuits | list, get, search, create, update | 5 |
Transactions | list, get | 2 |
Tasks | list, create | 2 |
Settings | get_settings, get_users, get_origins, get_stages, get_type_lawsuits | 5 |
Rewards | get_users_rewards | 1 |
7.1 Customers (Clientes)
list_customers
Lista e busca clientes com filtros.
Parâmetro | Tipo | Obrigatório | Descrição |
| string | ❌ | Nome do cliente (busca parcial) |
| string | ❌ | Telefone |
| string | ❌ | |
| string | ❌ | Cidade |
| number | ❌ | Máximo de resultados (default: 100, max: 500) |
| number | ❌ | Pular resultados (paginação) |
Exemplo:
{"tool":"list_customers","arguments":{"name":"Silva","limit":10}}get_customer
Obtém detalhes de um cliente pelo ID.
Parâmetro | Tipo | Obrigatório | Descrição |
| number | ✅ | ID do cliente |
Exemplo:
{"tool":"get_customer","arguments":{"customer_id":12345}}search_customers
Busca clientes por nome.
Parâmetro | Tipo | Obrigatório | Descrição |
| string | ✅* | Termo de busca |
| string | ✅* | Alternativa ao query |
create_customer
Cria um novo cliente.
Parâmetro | Tipo | Obrigatório | Descrição |
| number | ✅ | ID do usuário criando |
| number | ✅ | ID da origem do cliente |
| string | ✅ | Nome do cliente |
| string | ❌ | |
| string | ❌ | CPF/CNPJ |
| string | ❌ | RG |
| string | ❌ | Telefone |
| string | ❌ | Data nascimento (YYYY-MM-DD) |
Exemplo:
{
"tool": "create_customer",
"arguments": {
"users_id": 1,
"customers_origins_id": 2,
"name": "João da Silva",
"email": "joao@email.com",
"phone": "85999999999"
}
}7.2 Lawsuits (Processos)
list_lawsuits
Lista processos com filtros.
Parâmetro | Tipo | Obrigatório | Descrição |
| string | ❌ | Nome da pasta/cliente |
| string | ❌ | Número do processo |
| number | ❌ | ID do cliente |
| number | ❌ | ID do responsável |
| number | ❌ | ID do grupo/área |
| number | ❌ | Máximo de resultados |
| number | ❌ | Pular resultados |
get_lawsuit
Obtém detalhes de um processo.
Parâmetro | Tipo | Obrigatório | Descrição |
| number | ✅ | ID do processo |
search_lawsuits
Busca processos por nome/pasta.
Parâmetro | Tipo | Obrigatório | Descrição |
| string | ✅* | Termo de busca |
| string | ✅* | Alternativa |
create_lawsuit
Cria um novo processo.
Parâmetro | Tipo | Obrigatório | Descrição |
| number | ✅ | ID do usuário criando |
| array[number] | ✅ | IDs dos clientes |
| number | ✅ | ID do estágio |
| number | ✅ | ID do tipo de processo |
| string | ❌ | Número do processo |
| string | ❌ | Número do protocolo |
| string | ❌ | Nome da pasta |
| string | ❌ | Data (YYYY-MM-DD) |
| string | ❌ | Observações |
Exemplo:
{
"tool": "create_lawsuit",
"arguments": {
"users_id": 1,
"customers_id": [123, 456],
"stages_id": 5,
"type_lawsuits_id": 10,
"folder": "Silva vs Estado",
"process_number": "0001234-56.2026.8.06.0001"
}
}update_lawsuit
Atualiza um processo existente.
Parâmetro | Tipo | Obrigatório | Descrição |
| number | ✅ | ID do processo |
| number | ❌ | Novo estágio |
| number | ❌ | Novo tipo |
| string | ❌ | Número do processo |
| string | ❌ | Nome da pasta |
| string | ❌ | Observações |
7.3 Transactions (Transações)
list_transactions
Lista transações financeiras.
Parâmetro | Tipo | Obrigatório | Descrição |
| string | ❌ | Data pagamento início (YYYY-MM-DD) |
| string | ❌ | Data pagamento fim |
| string | ❌ | Data vencimento início |
| string | ❌ | Data vencimento fim |
| number | ❌ | Filtrar por processo |
| number | ❌ | Máximo de resultados |
| number | ❌ | Pular resultados |
Exemplo:
{
"tool": "list_transactions",
"arguments": {
"date_payment_start": "2026-01-01",
"date_payment_end": "2026-01-31"
}
}get_transaction
Obtém detalhes de uma transação.
Parâmetro | Tipo | Obrigatório | Descrição |
| number | ✅ | ID da transação |
7.4 Tasks (Tarefas)
list_tasks
Lista tarefas e compromissos.
Parâmetro | Tipo | Obrigatório | Descrição |
| string | ❌ | Data início (YYYY-MM-DD) |
| string | ❌ | Data fim |
| number | ❌ | Filtrar por usuário |
| number | ❌ | Filtrar por processo |
| number | ❌ | Filtrar por tipo de tarefa |
| number | ❌ | Máximo de resultados |
| number | ❌ | Pular resultados |
create_task
Cria uma nova tarefa/compromisso.
Parâmetro | Tipo | Obrigatório | Descrição |
| number | ✅ | ID do usuário criando |
| array[number] | ✅ | IDs dos convidados |
| number | ✅ | ID do tipo de tarefa |
| number | ✅ | ID do processo |
| string | ✅ | Data início (YYYY-MM-DD) |
| string | ❌ | Hora início (HH:MM) |
| string | ❌ | Data fim |
| string | ❌ | Hora fim |
| string | ❌ | Prazo |
| string | ❌ | Comentários |
| string | ❌ | Local |
| boolean | ❌ | Urgente |
| boolean | ❌ | Importante |
Exemplo:
{
"tool": "create_task",
"arguments": {
"from": 1,
"guests": [2, 3],
"tasks_id": 5,
"lawsuits_id": 100,
"start_date": "2026-01-10",
"start_time": "14:00",
"comments": "Reunião com cliente",
"urgent": true
}
}7.5 Settings (Configurações)
get_settings
Obtém todas as configurações do sistema (users, stages, types, origins).
get_users
Lista usuários/colaboradores.
get_origins
Lista origens de clientes. Use para obter customers_origins_id.
get_stages
Lista estágios de processos. Use para obter stages_id.
get_type_lawsuits
Lista tipos de processos. Use para obter type_lawsuits_id.
7.6 Rewards (Recompensas)
get_users_rewards
Obtém pontuação e recompensas da equipe.
Parâmetro | Tipo | Obrigatório | Descrição |
| string | ❌ | Data limite (YYYY-MM-DD) |
Exemplo:
{"tool":"get_users_rewards","arguments":{"date":"2026-01-05"}}8. Exemplos de Uso
8.1 Fluxo MCP Completo (SSE)
// 1. Conectar ao SSE
const eventSource = new EventSource('https://<SEU_DOMINIO>/sse', {
headers: { 'Authorization': 'Bearer <TOKEN>' }
});
let messageEndpoint = '';
// 2. Receber endpoint para mensagens
eventSource.addEventListener('endpoint', (e) => {
messageEndpoint = e.data;
console.log('Endpoint:', messageEndpoint);
});
// 3. Receber respostas
eventSource.addEventListener('message', (e) => {
const response = JSON.parse(e.data);
console.log('Response:', response);
});
// 4. Enviar requisição MCP
fetch(messageEndpoint, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer <TOKEN>'
},
body: JSON.stringify({
jsonrpc: '2.0',
id: 1,
method: 'tools/call',
params: {
name: 'list_customers',
arguments: { limit: 5 }
}
})
});8.2 Execução Direta (REST)
# Listar clientes
curl -X POST \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-d '{"tool":"list_customers","arguments":{"name":"Silva","limit":10}}' \
https://<SEU_DOMINIO>/execute
# Buscar processo
curl -X POST \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-d '{"tool":"get_lawsuit","arguments":{"lawsuit_id":12345}}' \
https://<SEU_DOMINIO>/execute
# Criar tarefa
curl -X POST \
-H "Authorization: Bearer <TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"tool": "create_task",
"arguments": {
"from": 1,
"guests": [1],
"tasks_id": 5,
"lawsuits_id": 100,
"start_date": "2026-01-10",
"comments": "Audiência"
}
}' \
https://<SEU_DOMINIO>/execute8.3 Paginação
# Página 1 (primeiros 100)
curl -X POST -H "Authorization: Bearer <TOKEN>" \
-d '{"tool":"list_customers","arguments":{"limit":100,"offset":0}}' \
https://<SEU_DOMINIO>/execute
# Página 2 (próximos 100)
curl -X POST -H "Authorization: Bearer <TOKEN>" \
-d '{"tool":"list_customers","arguments":{"limit":100,"offset":100}}' \
https://<SEU_DOMINIO>/execute9. Segurança
9.1 Controles Implementados
Controle | Descrição | CWE Mitigado |
Timing-safe Auth | Comparação de tokens resistente a timing attacks | CWE-208 |
Rate Limiting | 100 req/min por IP | CWE-770 |
Input Validation | Sanitização de todos os parâmetros | CWE-20 |
Body Size Limit | Máximo 1MB | CWE-400 |
SSE Limits | Max 100 conexões, 5 por IP | CWE-770 |
Prototype Pollution | Filtro de | CWE-1321 |
Path Traversal | Regex validation em endpoints | CWE-22 |
Security Headers | HSTS, CSP, X-Frame-Options | Múltiplos |
9.2 Headers de Segurança
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Content-Security-Policy: default-src 'none'
Strict-Transport-Security: max-age=31536000; includeSubDomains9.3 CORS
Domínios permitidos (configurável via ALLOWED_ORIGINS):
https://<SEU_DOMINIO>https://<SEU_DOMINIO>
9.4 Container Security
✅ Executa como usuário não-root (
advbox:1001)✅ Imagem Alpine mínima
✅ Sem shell de root
✅ Recursos limitados (512MB RAM, 1 CPU)
9.5 Boas Práticas
Rotacione o MCP_TOKEN a cada 90 dias
Monitore tentativas de autenticação falhadas
Mantenha o container atualizado
Use HTTPS sempre (via Traefik)
10. Integração com n8n
10.1 Configuração do MCP Client
No n8n, configure o nó MCP Client com:
Campo | Valor |
URL |
|
Authentication | Header Auth |
Header Name |
|
Header Value |
|
10.2 Tools Mais Usadas em Automações
Automação | Tools |
Busca de clientes |
|
Criação de processos |
|
Relatórios financeiros |
|
Agenda |
|
Gamificação |
|
11. Monitoramento
11.1 Health Check
curl https://<SEU_DOMINIO>/health
# {"status":"healthy","version":"2.2.0","tools":19,"sse":0}11.2 Logs do Container
# Ver logs em tempo real
docker logs -f advbox-mcp-api
# Últimas 100 linhas
docker logs --tail 100 advbox-mcp-api11.3 Métricas a Monitorar
Métrica | Descrição | Alerta |
| Conexões SSE ativas | > 80 |
Health status | Estado do servidor | ≠ healthy |
Response time | Tempo de resposta | > 5s |
Error rate | Taxa de erros 5xx | > 1% |
11.4 Integração com Uptime Kuma
Type: HTTP(s)
URL: https://<SEU_DOMINIO>/health
Method: GET
Expected Status: 200
Interval: 60 seconds
Retries: 312. Troubleshooting
12.1 Erros Comuns
401 Unauthorized
Causa: Token ausente ou inválido
Solução:
# Verificar token
cat /opt/stacks/advbox-mcp-server/.env | grep MCP_TOKEN
# Testar com curl
curl -H "Authorization: Bearer <TOKEN>" https://<SEU_DOMINIO>/tools429 Too Many Requests
Causa: Rate limit excedido (100 req/min)
Solução: Aguardar 60 segundos ou otimizar requisições
503 Too many connections
Causa: Limite de conexões SSE atingido (100)
Solução:
docker restart advbox-mcp-apiConnection refused
Causa: Container não está rodando
Solução:
docker ps | grep advbox
docker logs advbox-mcp-api
docker compose up -d advbox-apiAPI error 401 (Advbox)
Causa: Token do Advbox inválido
Solução:
cat /opt/stacks/advbox-mcp-server/.env | grep ADVBOX_API_TOKEN
curl -H "Authorization: Bearer <ADVBOX_TOKEN>" https://app.advbox.com.br/api/v1/settings12.2 Comandos de Diagnóstico
# Status do container
docker inspect advbox-mcp-api | jq '.[0].State'
# Uso de recursos
docker stats advbox-mcp-api --no-stream
# Verificar rede
docker exec advbox-mcp-api wget -qO- http://localhost:3000/health
# Rebuild completo
cd /opt/stacks/advbox-mcp-server
docker compose down
docker compose build --no-cache
docker compose up -d13. Changelog
v2.2.0 (05/01/2026) - HARDENED
Segurança:
✅ Timing-safe token comparison
✅ Proteção contra Prototype Pollution
✅ Rate limiting com proteção memory exhaustion
✅ Limite de conexões SSE (global e por IP)
✅ Timeout em conexões SSE (1 hora)
✅ CORS restritivo com whitelist
✅ Validação de email
✅ Headers de segurança (HSTS)
v2.1.0 (05/01/2026)
✅ Autenticação Bearer Token
✅ Rate Limiting básico
✅ Input validation
v2.0.0 (04/01/2026)
✅ Servidor HTTP standalone
✅ 19 tools funcionais
✅ Suporte SSE
v1.0.0 (03/01/2026)
Versão inicial (STDIO)
14. Referência Rápida
Credenciais de Produção
Item | Valor |
Endpoint SSE |
|
Endpoint Execute |
|
MCP Token |
|
Porta Local |
|
Comando de Teste Rápido
# Testar autenticação
curl -s -H "Authorization: Bearer <SEU_MCP_TOKEN>" \
https://<SEU_DOMINIO>/health
# Listar tools
curl -s -H "Authorization: Bearer <SEU_MCP_TOKEN>" \
https://<SEU_DOMINIO>/tools | jq '.tools[].name'Documentação gerada em 05/01/2026 - Jonas Sousa
15. Integração com Claude Desktop
15.1 Pré-requisitos
Node.js instalado (versão 18+)
Claude Desktop instalado
Verifique se o Node.js está instalado:
node --version
npx --versionSe não tiver, baixe em: https://nodejs.org/
15.2 Localização do Arquivo de Configuração
Sistema | Caminho |
Windows |
|
macOS |
|
Linux |
|
15.3 Configuração
Edite o arquivo claude_desktop_config.json e adicione:
{
"mcpServers": {
"advbox": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://<SEU_DOMINIO>/sse",
"--transport",
"sse-only",
"--header",
"Authorization:Bearer <SEU_MCP_TOKEN>"
]
}
}
}Nota: Se já existir conteúdo no arquivo, adicione apenas a seção
mcpServersmantendo as outras configurações.
Exemplo com configurações existentes:
{
"preferences": {
"chromeExtensionEnabled": true
},
"mcpServers": {
"advbox": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://<SEU_DOMINIO>/sse",
"--transport",
"sse-only",
"--header",
"Authorization:Bearer <SEU_MCP_TOKEN>"
]
}
}
}15.4 Parâmetros Explicados
Parâmetro | Descrição |
| Executor de pacotes Node.js |
| Aceita automaticamente a instalação do pacote |
| Pacote que faz ponte entre STDIO e SSE remoto |
| URL do servidor MCP Advbox |
| Força conexão via SSE (obrigatório) |
| Header de autenticação |
| Token de autenticação (sem espaço após ":") |
15.5 Ativação
Salve o arquivo
claude_desktop_config.jsonFeche completamente o Claude Desktop (incluindo na bandeja do sistema)
Abra o Claude Desktop novamente
Verifique se aparece o ícone de ferramentas/MCP na interface
15.6 Verificação
Após reiniciar, teste com um dos comandos:
"Liste as tools disponíveis do Advbox"
"Busque clientes com nome Silva no Advbox"
"Quais são os usuários do escritório?"
15.7 Troubleshooting Claude Desktop
Verificar Logs
No Claude Desktop, acesse: View → Toggle Developer Tools → Console
Erros Comuns
Erro | Causa | Solução |
| Formato JSON incorreto | Use o formato com |
| Falta | Adicione o parâmetro |
| Servidor não respondeu | Verifique se o servidor está online |
| Conexão caiu | Verifique rede e reinicie Claude Desktop |
Testar Conexão Manualmente
No terminal, execute:
npx -y mcp-remote https://<SEU_DOMINIO>/sse --transport sse-only --header "Authorization:Bearer <SEU_MCP_TOKEN>"Se conectar corretamente, você verá mensagens JSON sendo trocadas.
15.8 Múltiplos Servidores MCP
Para adicionar outros servidores MCP junto com o Advbox:
{
"mcpServers": {
"advbox": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://<SEU_DOMINIO>/sse",
"--transport",
"sse-only",
"--header",
"Authorization:Bearer <SEU_MCP_TOKEN>"
]
},
"outro-servidor": {
"command": "npx",
"args": ["-y", "outro-mcp-server"]
}
}
}Seção adicionada em 05/01/2026
This server cannot be installed
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Latest Blog Posts
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/JonasSousaAP/advbox-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server