mcp

O submódulo MCP implementa um servidor completo do Model Context Protocol dentro do HedHog, expondo toda a superfície da API como ferramentas estruturadas e chamáveis para qualquer assistente de IA compatível com MCP. O MCP é um padrão aberto desenvolvido pela Anthropic que define como os modelos de IA descobrem e invocam capacidades de aplicações externas. Um servidor MCP anuncia um catálogo de ferramentas tipadas — cada uma com um nome, uma descrição e um JSON Schema para seus parâmetros — que os clientes de IA podem chamar pelo nome para executar ações reais e recuperar dados reais.

A autenticação usa API keys criadas via POST /mcp/api-keys com o type "mcp". Cada API key é vinculada ao usuário que a criou e carrega o conjunto completo de roles e permissões desse usuário. Isso significa que toda chamada de ferramenta MCP é autorizada exatamente sob as mesmas regras da chamada HTTP equivalente — uma ferramenta que lista usuários exige a role admin-user, seja invocada via REST ou MCP. Não há um modelo de permissões separado a manter.

As ferramentas MCP do HedHog seguem uma convenção de nomenclatura hierárquica: core.<submodule>.<action> (por exemplo, core.users.list, core.ai.agents.chat, core.settings.set). Esse namespace evita colisões quando múltiplos servidores MCP estão conectados à mesma sessão de cliente de IA. As bibliotecas fora do Core estendem o namespace com seu próprio prefixo (lms.courses.list, crm.persons.get).

O submódulo MCP Chat é construído sobre o servidor MCP para oferecer sessões de IA conversacional capazes de invocar ferramentas MCP no meio da conversa, viabilizando fluxos orientados por IA em que o assistente tanto gera texto quanto executa ações reais — cria registros, envia e-mails, lê dashboards — dentro de uma única thread de conversa.

Para conectar o Claude Desktop ou qualquer cliente compatível com MCP: crie uma API key e, em seguida, configure o cliente para apontar para o endpoint /mcp da sua implantação com a chave no cabeçalho Authorization: Bearer. O servidor anuncia seu catálogo de ferramentas automaticamente por meio do handshake de inicialização do MCP — nenhuma registração manual de ferramentas é necessária no lado do cliente.