Sessões

O MCP Server do bitERP usa sessões stateful — cada conexão de agente de IA recebe sua própria instância de servidor MCP com transport dedicado.

Ciclo de vida

1. Criação

Quando o cliente envia POST / sem o header Mcp-Session-Id, uma nova sessão é criada:

• O servidor valida o JWT
• Cria uma instância McpServer dedicada
• Registra todas as tools disponíveis
• Conecta o transport HTTP
• Retorna o Mcp-Session-Id no header da resposta

2. Uso

Requests subsequentes incluem o header Mcp-Session-Id:

POST / HTTP/1.1
Authorization: Bearer <jwt>
Mcp-Session-Id: <session-id>
Content-Type: application/json

A cada request, o servidor:

• Valida o JWT (autenticação independente por request)
• Verifica que a sessão pertence ao usuário (userId)
• Atualiza o timestamp de última atividade
• Delega a mensagem ao transport da sessão

3. Expiração

Sessões inativas são removidas automaticamente:

4. Encerramento

O cliente pode encerrar a sessão explicitamente:

DELETE / HTTP/1.1
Authorization: Bearer <jwt>
Mcp-Session-Id: <session-id>

Server-Sent Events (SSE)

O servidor suporta conexões SSE para streaming de mensagens server-to-client:

GET / HTTP/1.1
Authorization: Bearer <jwt>
Mcp-Session-Id: <session-id>
Accept: text/event-stream

Proteção anti-hijack

Cada sessão é vinculada ao userId que a criou. Se um request com Mcp-Session-Id vem de outro usuário:

• O servidor retorna 404 Not Found
• Não revela se a sessão existe (previne enumeração)
• Registra tentativa de hijack nos logs

Graceful shutdown

Quando o servidor é encerrado (deploy, restart), todas as sessões ativas são fechadas de forma controlada — os transports e servers são encerrados antes do processo finalizar.