Skip to main content
Glama
JonasSousaAP

MCP Advbox Server

by JonasSousaAP

📚 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

  2. Arquitetura

  3. Instalação

  4. Configuração

  5. Autenticação

  6. Endpoints HTTP

  7. Tools Disponíveis

  8. Exemplos de Uso

  9. Segurança

  10. Integração com n8n

  11. Monitoramento

  12. Troubleshooting


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
└── .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 << 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/health

4. Configuração

Variáveis de Ambiente

Variável

Obrigatório

Descrição

ADVBOX_API_TOKEN

Token de acesso à API Advbox

ADVBOX_BASE_URL

URL base da API (default: https://app.advbox.com.br/api/v1)

MCP_TOKEN

Token de autenticação do MCP

ALLOWED_ORIGINS

Domínios permitidos (CORS)

PORT

Porta interna (default: 3000)

Limites de Segurança

Parâmetro

Valor

Descrição

MAX_BODY_SIZE

1 MB

Tamanho máximo do body

RATE_LIMIT_MAX

100 req/min

Requests por IP

MAX_SSE_CONNECTIONS

100

Conexões SSE simultâneas

MAX_SSE_PER_IP

5

Conexões SSE por IP

SSE_TIMEOUT

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>/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://<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>/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

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

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.

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

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://<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>/execute

8.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>/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://<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

  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://<SEU_DOMINIO>/sse

Authentication

Header Auth

Header Name

Authorization

Header Value

Bearer <MCP_TOKEN>

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

11.3 Métricas a Monitorar

Métrica

Descrição

Alerta

sse

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: 3

12. 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>/tools

429 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-api

Connection refused

Causa: Container não está rodando

Solução:

docker ps | grep advbox
docker logs advbox-mcp-api
docker compose up -d advbox-api

API 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/settings

12.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 -d

13. 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

https://<SEU_DOMINIO>/sse

Endpoint Execute

https://<SEU_DOMINIO>/execute

MCP Token

<SEU_MCP_TOKEN>

Porta Local

3847

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 --version

Se não tiver, baixe em: https://nodejs.org/

15.2 Localização do Arquivo de Configuração

Sistema

Caminho

Windows

%APPDATA%\Claude\claude_desktop_config.json

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Linux

~/.config/Claude/claude_desktop_config.json

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 mcpServers mantendo 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

npx

Executor de pacotes Node.js

-y

Aceita automaticamente a instalação do pacote

mcp-remote

Pacote que faz ponte entre STDIO e SSE remoto

https://<SEU_DOMINIO>/sse

URL do servidor MCP Advbox

--transport sse-only

Força conexão via SSE (obrigatório)

--header

Header de autenticação

Authorization:Bearer ...

Token de autenticação (sem espaço após ":")

15.5 Ativação

  1. Salve o arquivo claude_desktop_config.json

  2. Feche completamente o Claude Desktop (incluindo na bandeja do sistema)

  3. Abra o Claude Desktop novamente

  4. 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

command is required

Formato JSON incorreto

Use o formato com command e args

transport strategy: http-first

Falta --transport sse-only

Adicione o parâmetro

Request timed out

Servidor não respondeu

Verifique se o servidor está online

Server disconnected

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

A
license - permissive license
-
quality - not tested
C
maintenance

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

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