Autenticação MCP

O MCP Server usa OAuth 2.0 via Clerk para autenticação. Cada request é autenticado independentemente via JWT.

Fluxo de autenticação

1. Cliente MCP descobre OAuth metadata
   GET /.well-known/oauth-authorization-server

2. Redireciona usuário para autenticação Clerk

3. Recebe token OAuth (JWT)

4. POST / sem Mcp-Session-Id (cria sessão)
   → Servidor valida JWT
   → Cria sessão vinculada ao usuário
   → Retorna Mcp-Session-Id

5. Requests seguintes incluem Mcp-Session-Id
   → JWT validado em cada request
   → Sessão verificada contra userId

OAuth Discovery

O servidor expõe endpoints de discovery conforme os RFCs 9728 e 8414:

Endpoint	RFC	Descrição
`GET /.well-known/oauth-protected-resource`	RFC 9728	Metadata do recurso protegido
`GET /.well-known/oauth-authorization-server`	RFC 8414	Metadata do servidor de autorização

Clientes MCP compatíveis (Claude Desktop, Cursor, etc.) usam esses endpoints automaticamente para descobrir como autenticar.

Contexto do usuário

Após autenticação, o servidor resolve o contexto completo:

Campo	Descrição
`userId`	ID do usuário no bitERP
`email`	Email do usuário
`tenantId`	ID do tenant (resolvido via `list_tenants`)
`membershipId`	ID da associação usuário-tenant
`role`	Role do usuário no tenant (`admin` ou `member`)

O token OAuth contém apenas o userId. O contexto de tenant é resolvido quando o agente chama list_tenants e passa o tenant_id nas operações.

Permissões

O sistema de permissões é idêntico ao da API de Integrações:

Usuários admin têm acesso completo
Usuários member têm acesso controlado por permissões granulares por recurso/ação
Permissões são verificadas antes de cada operação

Quando o agente tenta uma operação sem permissão, recebe um erro que permite informar o usuário sobre a restrição.

Segurança

Cada request é autenticado via JWT (não depende apenas da sessão)
Sessões são vinculadas ao userId — tentativas de uso por outro usuário são bloqueadas
Dados são isolados por tenant via Row-Level Security (RLS)
HTTPS obrigatório em produção