personaleasy-mcp-server

Servidor MCP para a API PersonalEasy | EasyDental Cloud | DentalKids.

Tools

Tool	Descrição	Parâmetros
`personaleasy_get_agendamentos`	Busca agendamentos no período	`dt_inicio`, `dt_termino` (YYYY-MM-DD), `nm_unidade` (opcional)
`personaleasy_get_kpi_producao`	KPIs de produção para dashboard	`dt_inicio`, `dt_termino`, `nm_unidade` (opc.), `nm_prestador` (opc.)
`personaleasy_get_prestador_por_cpf`	ID e nome do prestador pelo CPF	`cpf` (formato 999.999.999-99)
`personaleasy_get_unidades`	Lista unidades de atendimento ativas	—

Todas as tools são somente leitura (readOnlyHint: true).

Instalação

npm install
npm run build

Credenciais

As credenciais nunca ficam no código. Configure via variáveis de ambiente:

PERSONALEASY_API_KEY — a api-key (header x-api-key)
PERSONALEASY_CLIENT_ID — o ID do cliente
PERSONALEASY_BASE_URL — opcional, padrão https://prsrb.onrender.com/v1/rpc

Para testes locais, copie .env.example para .env e preencha. O .env está no .gitignore — não o versione nem o compartilhe.

Configuração no Claude Code

claude mcp add personaleasy --env PERSONALEASY_API_KEY=SUA_KEY --env PERSONALEASY_CLIENT_ID=SEU_CLIENT_ID -- node D:/MCPS/personaleasy-mcp-server/dist/index.js

Configuração no Claude Desktop

Em claude_desktop_config.json:

{
  "mcpServers": {
    "personaleasy": {
      "command": "node",
      "args": ["D:/MCPS/personaleasy-mcp-server/dist/index.js"],
      "env": {
        "PERSONALEASY_API_KEY": "SUA_KEY",
        "PERSONALEASY_CLIENT_ID": "SEU_CLIENT_ID"
      }
    }
  }
}

Deploy no Easypanel (Docker)

O projeto tem dois modos de execução:

stdio (dist/index.js) — uso local (Claude Code / Claude Desktop)
HTTP (dist/http.js) — uso remoto; é o modo usado pelo Dockerfile

No Easypanel, crie um serviço do tipo App apontando para este repositório (build via Dockerfile) e configure as variáveis de ambiente:

Variável	Obrigatória	Descrição
`PERSONALEASY_API_KEY`	sim	api-key da API
`PERSONALEASY_CLIENT_ID`	sim	ID do cliente
`MCP_AUTH_TOKEN`	recomendada	token Bearer exigido no endpoint `/mcp` (gere um valor aleatório longo)
`PORT`	não	padrão 3000

Exponha a porta 3000 no serviço. Endpoints:

POST /mcp — endpoint MCP (Streamable HTTP, stateless)
GET /health — healthcheck

Instância em produção

URL base: https://dk-projetos-mcps.nv8gf3.easypanel.host
Healthcheck: GET https://dk-projetos-mcps.nv8gf3.easypanel.host/health → {"status":"ok"}
Endpoint MCP: POST https://dk-projetos-mcps.nv8gf3.easypanel.host/mcp

Para conectar um cliente MCP a essa instância:

claude mcp add --transport http personaleasy https://dk-projetos-mcps.nv8gf3.easypanel.host/mcp --header "Authorization: Bearer SEU_MCP_AUTH_TOKEN"

Substitua SEU_MCP_AUTH_TOKEN pelo valor configurado na variável MCP_AUTH_TOKEN do serviço no Easypanel.

Uso no claude.ai (conector custom — para não-desenvolvedores)

O claude.ai não tem campo para header de autenticação em conectores custom, então o servidor também aceita o token embutido na URL:

https://dk-projetos-mcps.nv8gf3.easypanel.host/mcp/SEU_MCP_AUTH_TOKEN

Passo a passo para o usuário final:

Abrir claude.ai → Configurações → Conectores
Clicar em Adicionar conector custom
Colar a URL acima (já com o token) e salvar
Numa conversa nova, ativar o conector e pedir normalmente: "quais os agendamentos de amanhã na unidade Campinas?"

Trate essa URL como uma senha: quem tiver a URL completa acessa os dados. Envie por canal seguro e, se vazar, troque o MCP_AUTH_TOKEN no Easypanel (isso invalida a URL antiga).

Importante: sem MCP_AUTH_TOKEN configurado no serviço, qualquer pessoa com essa URL consegue consultar os dados da clínica. Confirme que a variável está definida em produção.

API subjacente

Todas as chamadas vão para um único endpoint RPC:

POST {BASE_URL}
Headers: x-api-key
Body: { "clientId": "...", "method": "RPCGet...", "params": { ... } }

Métodos usados: RPCGetAgendamentos, RPCGetKPIPrd, RPCGetPrestadorCPF, RPCGetUnidadeAtendimento.