Construindo um Servidor MCP em Laravel que Responde Perguntas com Dados Reais

Construindo um Servidor MCP Laravel Que Responde Perguntas Sobre Dados Reais

Um guia prático para o Protocolo de Contexto de Modelo no Laravel — dos primeiros princípios a uma ferramenta ao vivo dentro do Claude Desktop

O Protocolo de Contexto de Modelo (MCP) permite que um assistente de IA como Claude chame seu aplicativo —
executando seu código, lendo seus dados e respondendo perguntas que de outra forma não poderia. Este tutorial
esteach MCP no Laravel construindo um exemplo funcional: um servidor somente leitura que responde
preguntas em linguagem natural sobre um banco de dados de vendas ("quem foram nossos cinco principais clientes no último trimestre?")
e conectando-o ao Claude Desktop.

Usaremos um conjunto de dados de vendas de exemplo — clientes, pedidos, produtos, pagamentos — baseado no bem conhecido
classicmodels banco de dados de exemplo
(um varejista de modelos de carros em escala), popularizado pelo MySQL Tutorial e disponível gratuitamente para aprendizado. Nada
aqui é específico para ele, no entanto; os mesmos padrões se aplicam a qualquer dado de aplicativo Laravel. Cada trecho de código
é um exemplo ilustrativo; o servidor completo e executável está no projeto acompanhante,
linkado no final.

O que você aprenderá

1. O que é MCP e como ele difere de uma API REST tradicional.
2. Como testar um servidor localmente com o MCP Inspector, antes que qualquer cliente de IA o toque.
3. Como tornar suas ferramentas "nativas de agente" — os pequenos toques que tornam um servidor agradável para um modelo usar.
4. Como conectar o servidor ao Claude Desktop, e como protegê-lo para uso real.

Parte 1 — O que é MCP e como ele é diferente de uma API?

Um servidor MCP é, em certo sentido, uma API — ele fala JSON-RPC sobre um transporte e retorna
dados estruturados. Mas é um tipo de interface fundamentalmente diferente da API REST que você
escreveria manualmente para um aplicativo de página única ou um cliente móvel.

A principal diferença: quem é o consumidor

• Uma API REST é projetada para desenvolvedores. Um humano lê a documentação, aprende os endpoints e escreve código para chamar GET /orders?status=Shipped. O contrato vive na documentação que fica fora da API.
• Um servidor MCP é projetado para um modelo de IA. O modelo descobre o que está disponível em tempo de execução perguntando ao servidor "o que você pode fazer?" O contrato é auto-descritivo e é enviado com o servidor.

Essa única mudança impulsiona todas as outras diferenças.

Lado a lado

As três primitivas

Um servidor MCP Laravel é uma classe que registra três tipos de capacidade. Aqui está o esqueleto do
servidor que construiremos, que expõe todos os três:

use Laravel\Mcp\Server;
use Laravel\Mcp\Server\Attributes\Instructions;

#[Instructions(<<<'TXT'
    Este servidor expõe um conjunto de dados de vendas somente leitura para consultas ad-hoc.
    Leia o recurso "database-schema" primeiro para aprender as tabelas, então
    responda com as ferramentas curadas, recorrendo a uma consulta SQL somente leitura
    apenas quando nenhuma ferramenta curada se encaixar.
    TXT)]
class AssistantServer extends Server
{
    protected array $tools = [
        ListOrdersTool::class,
        SearchCustomersTool::class,
        RevenueReportTool::class,
        RunAssistantQueryTool::class,
        // ...
    ];

    protected array $resources = [DatabaseSchemaResource::class];

    protected array $prompts = [RevenueInsightsPrompt::class];
}

• Ferramentas são as ações chamáveis — ListOrdersTool, SearchCustomersTool, e assim por diante. Cada uma é uma classe com um método handle(), muito parecido com uma ação de controlador.
• Recursos são contextos somente leitura que o modelo pode puxar. Nosso DatabaseSchemaResource descreve cada tabela e coluna consultável em linguagem simples, para que o modelo conheça a forma dos dados.
• Prompts são modelos reutilizáveis — RevenueInsightsPrompt inicia um fluxo de trabalho de análise pré-definido.

Note o bloco #[Instructions]. Ele diz ao modelo como trabalhar — leia o esquema primeiro, prefira
tools curados, trate SQL bruto como uma opção de fallback — e o modelo o recebe automaticamente ao se conectar. Um
API REST não tem equivalente; a coisa mais próxima é um README que o desenvolvedor pode nunca ler.

Por que isso importa

1. Auto-descritivo & descobrível em tempo de execução. A descrição de uma ferramenta ("Lista pedidos com seu status, datas, cliente e total calculado…") é parte do protocolo de comunicação. O modelo a lê e sabe quando recorrer à ferramenta — nenhum humano colando documentos ao código.
2. Um cliente, qualquer servidor. Porque MCP é um padrão, o Claude Desktop se conecta ao seu servidor Laravel com zero código de integração personalizado. Contrastando com uma API REST, onde cada consumidor escreve seu próprio cliente.
3. Construído para raciocínio, não apenas transporte. Descrições e esquemas JSON são escritos para ajudar um modelo a decidir. Esse é um objetivo de design diferente de um endpoint que apenas retorna linhas.
4. Você mantém toda a sua estrutura Laravel.