Advbox Mcp Server

📚 Documentação MCP Advbox Server

Versão: 2.2.0 (Hardened) Última atualização: 05 de Janeiro de 2026 Autor: Jonas Sousa

---

📑 Índice

1. [Visão Geral](#1-visão-geral)
2. [Arquitetura](#2-arquitetura)
3. [Instalação](#3-instalação)
4. [Configuração](#4-configuração)
5. [Autenticação](#5-autenticação)
6. [Endpoints HTTP](#6-endpoints-http)
7. [Tools Disponíveis](#7-tools-disponíveis)
8. [Exemplos de Uso](#8-exemplos-de-uso)
9. [Segurança](#9-segurança)
10. [Integração com n8n](#10-integração-com-n8n)
11. [Monitoramento](#11-monitoramento)
12. [Troubleshooting](#12-troubleshooting)

---

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
└── .env

---

3. Instalação

Pré-requisitos

• Docker 24.0+
• Docker Compose v2
• Rede Docker proxy configurada
• Traefik 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 

Exemplo

curl -H "Authorization: Bearer " https:///tools

Erros

| Status | Resposta | Causa | |--------|----------|-------| | 401 | {"error":"Unauthorized"} | Token inválido | | 429 | {"error":"Too Many Requests"} | Rate limit |

---

6. Endpoints HTTP

| Método | Endpoint | Auth | Descrição | |--------|----------|------|-----------| | GET | /health | ❌ | Health check | | GET | /sse | ✅ | Conexão SSE (MCP) | | POST | /message | ✅ | Mensagem MCP | | GET | /tools | ✅ | Listar tools | | POST | /execute | ✅ | Executar tool |

GET /health

curl https:///health

{"status":"healthy","version":"2.2.0","tools":19,"sse":0}

POST /execute

curl -X POST \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"tool":"list_customers","arguments":{"limit":5}}' \
  https:///execute

---

7. 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 | getsettings, getusers, getorigins, getstages, gettypelawsuits | 5 | | Rewards | getusersrewards | 1 |

7.1 Customers (Clientes)

list_customers

Lista e busca clientes com filtros.

| Parâmetro | Tipo | Obrigatório | Descrição | |-----------|------|-------------|-----------| | name | string | ❌ | Nome do cliente (busca parcial) | | phone | string | ❌ | Telefone | | email | string | ❌ | Email | | city | string | ❌ | Cidade | | limit | number | ❌ | Máximo de resultados (default: 100, max: 500) | | offset | 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 | |-----------|------|-------------|-----------| | customer_id | 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 | |-----------|------|-------------|-----------| | query | string | ✅ | Termo de busca | | name | string | ✅ | Alternativa ao query |

create_customer

Cria um novo cliente.

| Parâmetro | Tipo | Obrigatório | Descrição | |-----------|------|-------------|-----------| | users_id | number | ✅ | ID do usuário criando | | customers_origins_id | number | ✅ | ID da origem do cliente | | name | string | ✅ | Nome do cliente | | email | string | ❌ | Email | | document | string | ❌ | CPF/CNPJ | | identification | string | ❌ | RG | | phone | string | ❌ | Telefone | | birthdate | 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 | |-----------|------|-------------|-----------| | name | string | ❌ | Nome da pasta/cliente | | process_number | string | ❌ | Número do processo | | customer_id | number | ❌ | ID do cliente | | responsible_id | number | ❌ | ID do responsável | | group_id | number | ❌ | ID do grupo/área | | limit | number | ❌ | Máximo de resultados | | offset | number | ❌ | Pular resultados |

get_lawsuit

Obtém detalhes de um processo.

| Parâmetro | Tipo | Obrigatório | Descrição | |-----------|------|-------------|-----------| | lawsuit_id | number | ✅ | ID do processo |

search_lawsuits

Busca processos por nome/pasta.

| Parâmetro | Tipo | Obrigatório | Descrição | |-----------|------|-------------|-----------| | query | string | ✅ | Termo de busca | | name | string | ✅ | Alternativa |

create_lawsuit

Cria um novo processo.

| Parâmetro | Tipo | Obrigatório | Descrição | |-----------|------|-------------|-----------| | users_id | number | ✅ | ID do usuário criando | | customers_id | array[number] | ✅ | IDs dos clientes | | stages_id | number | ✅ | ID do estágio | | type_lawsuits_id | number | ✅ | ID do tipo de processo | | process_number | string | ❌ | Número do processo | | protocol_number | string | ❌ | Número do protocolo | | folder | string | ❌ | Nome da pasta | | date | string | ❌ | Data (YYYY-MM-DD) | | notes | 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 | |-----------|------|-------------|-----------| | lawsuit_id | number | ✅ | ID do processo | | stages_id | number | ❌ | Novo estágio | | type_lawsuits_id | number | ❌ | Novo tipo | | process_number | string | ❌ | Número do processo | | folder | string | ❌ | Nome da pasta | | notes | string | ❌ | Observações |

---

7.3 Transactions (Transações)

list_transactions

Lista transações financeiras.

| Parâmetro | Tipo | Obrigatório | Descrição | |-----------|------|-------------|-----------| | date_payment_start | string | ❌ | Data pagamento início (YYYY-MM-DD) | | date_payment_end | string | ❌ | Data pagamento fim | | date_due_start | string | ❌ | Data vencimento início | | date_due_end | string | ❌ | Data vencimento fim | | lawsuit_id | number | ❌ | Filtrar por processo | | limit | number | ❌ | Máximo de resultados | | offset | 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 | |-----------|------|-------------|-----------| | transaction_id | number | ✅ | ID da transação |

---

7.4 Tasks (Tarefas)

list_tasks

Lista tarefas e compromissos.

| Parâmetro | Tipo | Obrigatório | Descrição | |-----------|------|-------------|-----------| | date_start | string | ❌ | Data início (YYYY-MM-DD) | | date_end | string | ❌ | Data fim | | user_id | number | ❌ | Filtrar por usuário | | lawsuit_id | number | ❌ | Filtrar por processo | | task_id | number | ❌ | Filtrar por tipo de tarefa | | limit | number | ❌ | Máximo de resultados | | offset | number | ❌ | Pular resultados |

create_task

Cria uma nova tarefa/compromisso.

| Parâmetro | Tipo | Obrigatório | Descrição | |-----------|------|-------------|-----------| | from | number | ✅ | ID do usuário criando | | guests | array[number] | ✅ | IDs dos convidados | | tasks_id | number | ✅ | ID do tipo de tarefa | | lawsuits_id | number | ✅ | ID do processo | | start_date | string | ✅ | Data início (YYYY-MM-DD) | | start_time | string | ❌ | Hora início (HH:MM) | | end_date | string | ❌ | Data fim | | end_time | string | ❌ | Hora fim | | date_deadline | string | ❌ | Prazo | | comments | string | ❌ | Comentários | | local | string | ❌ | Local | | urgent | boolean | ❌ | Urgente | | important | 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.

gettypelawsuits

Lista tipos de processos. Use para obter type_lawsuits_id.

---

7.6 Rewards (Recompensas)

getusersrewards

Obtém pontuação e recompensas da equipe.

| Parâmetro | Tipo | Obrigatório | Descrição | |-----------|------|-------------|-----------| | date | 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:///sse', {
  headers: { 'Authorization': 'Bearer ' }
});

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 '
  },
  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 " \
  -H "Content-Type: application/json" \
  -d '{"tool":"list_customers","arguments":{"name":"Silva","limit":10}}' \
  https:///execute

# Buscar processo
curl -X POST \
  -H "Authorization: Bearer " \
  -H "Content-Type: application/json" \
  -d '{"tool":"get_lawsuit","arguments":{"lawsuit_id":12345}}' \
  https:///execute

# Criar tarefa
curl -X POST \
  -H "Authorization: Bearer " \
  -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:///execute

8.3 Paginação

# Página 1 (primeiros 100)
curl -X POST -H "Authorization: Bearer " \
  -d '{"tool":"list_customers","arguments":{"limit":100,"offset":0}}' \
  https:///execute

# Página 2 (próximos 100)
curl -X POST -H "Authorization: Bearer " \
  -d '{"tool":"list_customers","arguments":{"limit":100,"offset":100}}' \
  https:///execute

---

9. 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 __proto__, constructor | 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; includeSubDomains

9.3 CORS

Domínios permitidos (configurável via ALLOWED_ORIGINS):

• https://
• https://

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

1. Rotacione o MCP_TOKEN a cada 90 dias
2. Monitore tentativas de autenticação falhadas
3. Mantenha o container atualizado
4. 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 | https:///sse | | Authentication | Header Auth | | Header Name | Authorization | | Header Value | Bearer |

10.2 Tools Mais Usadas em Automações

| Automação | Tools | |-----------|-------| | Busca de clientes | search_customers, get_customer | | Criação de processos | get_settings, create_lawsuit | | Relatórios financeiros | list_transactions | | Agenda | list_tasks, create_task | | Gamificação | get_users_rewards |

---

11. Monitoramento

11.1 Health Check

curl https:///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-api

11.3 Métricas a Monitorar

| Métrica | Descrição | Alerta | |---------|-----

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: JonasSousaAP
• Source: JonasSousaAP/advbox-mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.