MeFirst Developers — API + MCP

1. Quickstart

Vá em Configurações → API & MCP dentro da plataforma MeFirst.
Clique em Gerar nova API key, escolha os scopes e copie o token (formato mef_live_xxx). Ele só aparece uma vez.
Use no header Authorization: Bearer <token> em qualquer chamada REST ou MCP.

2. API REST

Base URL: /api/v1

# Listar colaboradores ativos curl -H "Authorization: Bearer mef_live_xxx" \ https://app.mefirst.com.br/api/v1/employees?status=ativo&limit=50 # Detalhe curl -H "Authorization: Bearer mef_live_xxx" \ https://app.mefirst.com.br/api/v1/employees/<id> # OpenAPI 3.1 (importe no Postman / Stoplight / Swagger) curl https://app.mefirst.com.br/api/v1/openapi > mefirst.json

Erros padronizados: 401 chave inválida · 403 scope insuficiente · 4xx validação · 5xx erro interno.

3. MCP Server Diferencial

Nenhuma plataforma BR de RH tem MCP nativo. Conecte agentes Claude / Cursor / Continue / Cline diretamente aos seus dados, sem ETL.

Conectar ao Claude Code

# .claude/mcp.json (ou via comando `claude mcp add`) { "mcpServers": { "mefirst": { "url": "https://app.mefirst.com.br/api/mcp", "headers": { "Authorization": "Bearer mef_live_xxx" } } } }

Tools disponíveis

list_employees

Lista colaboradores ativos/desligados

get_employee

Detalha 1 colaborador por ID

list_admissions

Processos de admissão

list_terminations

Rescisões (TRCT)

list_payroll_runs

Folhas mensais por colaborador

list_time_punches

Marcações de ponto (Portaria 671)

list_esocial_events

Eventos S-2200/S-2299/S-1200…

cfo_overview

Painel CFO: CTCH, turnover, custo evitado

analytics_overview

People analytics agregado

Chamada raw JSON-RPC

curl -X POST https://app.mefirst.com.br/api/mcp \ -H "Authorization: Bearer mef_live_xxx" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call", "params":{"name":"cfo_overview","arguments":{"months":12}}}'

4. Webhooks

Receba eventos em tempo real: employee.admitted, employee.terminated, payroll.closed, esocial.accepted, esocial.rejected, turnover_risk.critical.

Cada entrega traz HMAC-SHA256 no header X-MeFirst-Signature: sha256=<hex>. Falhas têm retry exponencial (1m, 5m, 15m, 1h, 6h) e Dead Letter após 5 tentativas.

// Validação do webhook (Node.js) import crypto from 'node:crypto'; const sig = req.headers['x-mefirst-signature']?.replace('sha256=',''); const expected = crypto.createHmac('sha256', WEBHOOK_SECRET) .update(req.rawBody).digest('hex'); if (sig !== expected) return res.status(401).send('invalid signature');

5. Sandbox de testes

Crie uma chave com prefixo mef_test_xxx para apontar contra um conjunto de dados de teste isolado. Webhooks de sandbox usam endpoint dedicado e não disparam eventos reais (folha, eSocial, e-mails).