MCP — conectar um agente IA externo ao Omniscol

O que o agente pode fazer

O agente MCP funciona muito bem nas perguntas de consulta em que o dado está no Omniscol:

• « Dê-me a taxa de ocupação das salas em relação aos horários de funcionamento esta semana. »
• « Encontre-me uma sala disponível três segundas-feiras de outubro na mesma faixa horária de 2 horas. »
• « Quantas horas de aula Jean Dupont deu ao longo do ano letivo em curso? »
• « Quais são todas as aulas de matemática de hoje? »
• « Liste os professores que realizaram menos de 70% das suas horas de serviço neste trimestre. »

Essas consultas cruzam tipicamente várias ferramentas: horário, painéis de controle de estatísticas, disponibilidades calculadas, fichas de professores. O agente orquestra as chamadas e formula a resposta em linguagem natural.

As ferramentas expostas

O servidor MCP constrói as suas ferramentas a partir das rotas de API do Omniscol autorizadas para o MCP. As rotas explicitamente ignoradas, e certos módulos técnicos (por exemplo, relativos à autenticação dos usuários) não se tornam ferramentas. A lista reflete, portanto, a API exposta ao MCP, não a integralidade interna da aplicação. É, no entanto, uma grande parte. Além disso, existe um certo número de rotas dedicadas ao MCP e não utilizadas pelo próprio Omniscol. É o caso de ferramentas de busca avançada para que o texto livre que designa uma entidade ("professor Jean Dupont", "turma 6A") seja encontrado pelo Omniscol com o seu identificador técnico, que serve em seguida para consultar precisamente os dados. É também o caso de ferramentas complexas em que o Omniscol não possui interface gráfica, porque isso se presta melhor ao prompt: a busca de ocupação e de disponibilidade de entidade, por exemplo ("encontre-me uma sala disponível por 2 horas à tarde 3 segundas-feiras seguidas", "há algum professor de matemática disponível na semana de 14 de outubro por 3 horas?").

As ferramentas cobrem em particular:

• módulo Administração (usuários, disciplinas, anos letivos, parâmetros),
• módulo Gestão de horários letivos (configuração, campi, salas, turmas, aulas),
• módulo Horário (planejamento, painéis de controle, buscas),
• módulo Gestão de ausências (declaração, estatísticas),
• busca global.

As rotas de leitura são as mais adaptadas a um uso agêntico. Certas operações de escrita podem existir no catálogo, conforme os direitos do token e a API disponível, mas elas devem permanecer supervisionadas: uma consulta que modifica vários objetos de negócio deve ser verificada por um usuário antes de ser considerada confiável.

Ativar o servidor MCP

O servidor MCP está disponível nas contas Premium. Tudo parte da tela MCP, aberta a partir do módulo Administração com Configurar: ela exibe a URL do servidor conforme o perímetro escolhido (global ou restrito a um módulo) e fornece, prontos para copiar, os elementos de configuração do seu cliente.

A autenticação padrão do MCP é OAuth2. Um cliente compatível (como o Claude) conecta-se simplesmente à URL do servidor, descobre ali a configuração OAuth2 da conta, e o usuário aprova o acesso por meio de uma tela de consentimento: não há nada a fornecer além da URL. O perímetro concedido segue os direitos da conta e as suas restrições de visibilidade. O servidor OAuth2 do Omniscol, a sua tela de gestão dos clientes e o detalhe do consentimento estão descritos em OAuth2 / OIDC (provedor).

Para um cliente que não gerencia OAuth2, a mesma tela gera um token (chave de API, expiração, usuário associado opcional, direitos de escrita a marcar) depois propõe, prontos para colar, os formatos úteis conforme o caso: cabeçalho Authorization: Bearer, URL com token, bloco de configuração Claude Desktop (modo gratuito) e comando de proxy local. O token apoia-se no sistema de chaves descrito em API Omniscol.

Boas práticas de segurança

• Autenticação OAuth2 — mais prática e a preferir quando o seu agente a suporta (Claude versão paga).
• Token dedicado à IA — crie um token com um rótulo esclarecedor (Agente IA — Claude desktop) que você pode revogar se necessário.
• Perímetro mínimo — com um token de API, selecione apenas os pontos de acesso de API necessários. Com um token OAuth, limite os escopos ao necessário real.
• Registros de atividade (logs) — uma chamada aparece nos registros associados ao token quando a rota em questão é registrada. Esses registros rastreiam a chamada; eles não conservam nem o detalhe dos dados devolvidos nem o conteúdo reproduzível da requisição.
• Restrições de visibilidade — o agente vê aquilo que o Omniscol lhe devolve. Se você configurou restrições de visibilidade estritas para o papel do token, elas se aplicam.