Integrando um Servidor MCP em um App Laravel

Agentes de IA precisam de mais do que apenas uma interface (UI) extraída via scraping. Eles precisam de uma maneira de chamar ferramentas específicas com as permissões adequadas. É isso que o Model Context Protocol (MCP) faz.

Recentemente, integrei um servidor MCP diretamente em uma aplicação Laravel. Quero compartilhar as decisões arquiteturais para construir isso de forma segura.

The Receptionist Metaphor Pense no seu app como um edifício de escritórios.

  • A interface web é o saguão para humanos.
  • A API REST é a entrada de funcionários para sistemas.
  • O servidor MCP é um balcão de recepção para agentes de IA.

O agente apresenta um ID e solicita uma tarefa específica. A recepcionista não entrega as chaves do edifício para eles. Ela verifica as permissões, realiza uma tarefa e retorna uma resposta estruturada.

Key Design Decisions

  1. Use a single endpoint Não crie muitas rotas para diferentes ferramentas. Use um endpoint /mcp. O protocolo lida com a descoberta de ferramentas automaticamente. Uma superfície única é mais fácil de proteger e documentar.

  2. Support dual authentication Diferentes chamadores precisam de diferentes métodos de segurança:

  • Chamadores de primeira parte (como ferramentas CLI) usam tokens de acesso pessoal do Sanctum.
  • Agentes de terceiros (atuando em nome de usuários) usam OAuth 2.1.

Use um resolver no estilo driver para lidar com ambos. O código da ferramenta deve se preocupar apenas com o usuário autenticado, não com a forma como ele fez o login.

  1. Enforce existing RBAC A autenticação apenas prova quem é o chamador. Você ainda deve verificar o que ele pode fazer. Cada ferramenta deve mapear para uma ability existente. Se um usuário não pode visualizar participantes na interface web, ele não deve conseguir fazer isso via MCP.

  2. Limit data output Nunca retorne um modelo de banco de dados completo. Trate a saída do MCP como uma API pública. Retorne apenas os campos específicos que o agente precisa. Isso evita vazamentos de dados acidentais.

Testing for Security Seus testes devem provar que o sistema falha corretamente. Teste que:

  • Um usuário não autorizado recebe um erro 403 Forbidden.
  • Um usuário autorizado recebe apenas os campos permitidos.

Uma boa suíte de testes é sua melhor defesa contra vazamentos de dados ao usar agentes autônomos.

Summary Para construir um servidor MCP responsável, siga estas três regras:

  • Autentique cada chamador usando o esquema correto.
  • Autorize cada ferramenta usando seu modelo de permissão existente.
  • Trate cada saída de ferramenta como um recurso público limitado.

Source: https://dev.to/nasrulhazim/putting-an-mcp-server-inside-a-laravel-app-dual-auth-and-rbac-for-ai-tools-5376