Admin API — overview

O Simplafy Admin é o console interno da Simplafy. Concentra PM Board, BI Dashboards, Knowledge Base e Lab em um mesmo app Next.js, e expõe as mesmas operações via um MCP server irmão pensado para coding agents.

• Console web: admin.simplafy.com.br
• MCP server: https://mcp-admin.simplafy.com.br/mcp (Streamable HTTP)
• OpenAPI: https://admin.simplafy.com.br/api/v1/openapi.json
• Repositório: Simplafy-tec/simplafy-admin

O que é o Admin

Console interno + MCP server. Stack:

• Next.js 15 App Router (sem Pages Router)
• TypeScript strict
• Prisma 6 + PostgreSQL (namespace postgres em prd-2)
• NextAuth.js v5 para OAuth2 Google (RFC 7591) + Bearer credenciais customizadas
• @asteasolutions/zod-to-openapi para gerar spec OpenAPI 3.1
• pgvector para semantic search na Knowledge Base

O frontend admin (apps/web/src/app) é o consumidor primário da REST API. O MCP server (apps/mcp-server) implementa as mesmas operações via JSON-RPC, com audit log por chamada e autorização baseada em scopes.

Para quem é

Três perfis de consumidor:

• Frontend admin — telas internas do console, autenticadas via OAuth2 Google.
• Coding agents — automações, scripts e LLMs que precisam ler/escrever PM Board, KB, BI ou rodar cenários do Lab. Devem preferir o MCP server.
• Integrações server-to-server — workers e jobs internos usando AgentCredential (Bearer).

REST API vs MCP server

A REST API e o MCP server expõem o mesmo domínio de operações, com camadas de segurança diferentes.

curl -X POST https://mcp-admin.simplafy.com.br/mcp \
  -H "Authorization: Bearer $ADMIN_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

curl https://admin.simplafy.com.br/api/v1/openapi.json

Autenticação

Dois fluxos, ambos resolvendo para um Principal que carrega Scopes verificados via hasScope():

• OAuth2 Google (RFC 7591 clients) — devs e operadores.
• Bearer Credential (modelo AgentCredential no Prisma) — agentes server-to-server.

Detalhes em Auth.

Módulos principais

Cada módulo é um conjunto coeso de endpoints REST sob /api/v1/* com equivalentes no MCP server.

Mapeamento direto dos paths REST:

/api/v1/pm/*              PM Board (themes, modules, capabilities, epics, stories)
/api/v1/kb/*              Knowledge Base (references, semantic search)
/api/v1/bi/*              BI (KPIs, metrics)
/api/v1/lab/*             Lab (scenarios, runs)
/api/v1/hub-langfuse/*    Proxy para Hub Langfuse
/api/v1/openapi/specs/*   OpenAPI Registry (LEGACY, em deprecação)

Gotchas

• Edge Runtime — alguns paths rodam em Edge (auth-config, etc.). Não importar crypto do Node nesses arquivos.
• Prisma client hoist — @prisma/client faz hoist para a raiz do monorepo. Rodar prisma generate no workspace.
• route.ts — só aceita HTTP handlers. Named exports adicionais quebram next build silenciosamente.
• Scopes legacy admin:openapi:* — em remoção, não usar em integrações novas.

Onde o código real fica

apps/web/src/app/api/v1/{pm,kb,bi,lab,openapi,hub-langfuse}/*   Controllers REST
apps/web/src/lib/openapi/                                       Schemas + Registry OpenAPI
apps/web/src/lib/auth/                                          Auth (OAuth2 + Bearer)
apps/web/prisma/schema.prisma                                   Modelo de dados
apps/mcp-server/                                                MCP server irmão

Próximos passos