Construindo um Servidor MCP em Produção com Laravel

Aviso sobre a versão da especificação: Este artigo tem como alvo a versão da especificação MCP 2025-11-25. O protocolo teve mudanças significativas entre as versões, os nomes dos campos do esquema da ferramenta e os códigos de erro mudaram em lançamentos anteriores. Verifique a string protocolVersion contra o registro de alterações da especificação oficial do MCP antes da implantação e em cada atualização da especificação.

A maioria dos desenvolvedores Laravel encontra o Protocolo de Contexto de Modelo do lado do cliente. Você adicionou um servidor ao Claude Desktop, seu IDE se conectou a ele e ferramentas apareceram. Você era o consumidor. Este artigo constrói o outro lado dessa relação: um servidor mcp laravel que agentes de IA externos podem descobrir, autenticar e invocar.

Este é parte da série mais ampla Arquitetura de IA Laravel que cobre as decisões de infraestrutura que tornam as integrações de IA sustentáveis em escala. Os exemplos de código usam um domínio fictício consistente ao longo (uma aplicação de base de conhecimento baseada em Laravel) para que cada trecho se componha em um sistema coerente em vez de uma coleção de fragmentos isolados.

O que é realmente o MCP (e o que não é)

O MCP, o Protocolo de Contexto de Modelo, é um protocolo JSON-RPC 2.0. Não é um padrão de API. Não é REST. Não é um framework. Ele define uma conversa estruturada entre duas partes: um cliente e um servidor. O cliente solicita uma lista de ferramentas disponíveis. O servidor as descreve. O cliente pede ao servidor para executar uma. O servidor valida a entrada, executa a lógica e retorna um resultado dentro de um envelope JSON-RPC.

A distinção entre cliente e servidor é importante porque a maioria dos desenvolvedores Laravel esteve apenas de um lado. Ao integrar o Laravel Boost ao seu fluxo de trabalho, seu assistente de IA se conecta a um servidor MCP que expõe seus modelos Eloquent, rotas e configurações. Você é o cliente. O Laravel Boost faz a resposta. Este artigo é a outra extremidade desse fio, você constrói o servidor.

Há um pacote PHP, php-mcp/laravel, que estrutura um servidor para você. No momento da escrita, ele tem como alvo a versão da especificação 2025-03-26, que está duas revisões atrás do lançamento estável atual. Para sistemas de produção onde a negociação da versão do protocolo e a correção do esquema são importantes, construir a camada de transporte você mesmo lhe dá controle total sobre qual versão você anuncia e como você lida com falhas de negociação. Essa é a abordagem adotada aqui.

Os dois modos de transporte: stdio vs HTTP+SSE

O MCP suporta dois modos de transporte. Escolher o errado para o seu contexto de implantação é o erro mais comum no início.

stdio é executado como um processo filho. O cliente o inicia, se comunica via stdin/stdout e o processo sai quando a sessão termina. Rápido, sem configuração de rede, apropriado apenas para ferramentas locais.

HTTP+SSE é executado como um processo HTTP persistente. Os clientes se conectam pela rede. Chamadas JSON-RPC chegam como requisições POST. Respostas em streaming usam Eventos Enviados pelo Servidor em um canal separado. Tudo neste artigo é direcionado ao HTTP+SSE.

Definindo o manifesto do servidor e a negociação de capacidades

Toda sessão MCP começa com um initialize handshake. O cliente declara sua versão de protocolo e capacidades; o servidor responde com sua própria identidade e o que suporta.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {
      "roots": { "listChanged": true },
      "sampling": {}
    },
    "clientInfo": {
      "name": "claude-desktop",
      "version": "1.0.0"
    }
  }
}

O servidor responde:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-11-25",
    "capabilities": {
      "tools": { "listChanged": false }
    },
    "serverInfo": {
      "name": "knowledge-base-mcp",
      "version": "1.0.0"
    }
  }
}

Após initialize, o cliente envia uma notificação notifications/initialized (sem id, nenhuma resposta esperada), e a sessão está ativa. A string protocolVersion não é cosmética. Versões incompatíveis causam falhas silenciosas em alguns clientes; sempre ecoe exatamente o que você suporta.

Dirija ambos os valores a partir da configuração:

// config/mcp.php

return [
    'protocol_version' => env('MCP_PROTOCOL_VERSION', '2025-11-25'),
    'server_name'      => env('MCP_SERVER_NAME', 'knowledge-base-mcp'),
];

// app/MCP/Handlers/InitializeHandler.php

namespace App\MCP\Handlers;

class InitializeHandler
{
    public function handle(array $params): array
    {
        return [
            'protocolVersion' => config('mcp.protocol_version'),
            'capabilities'    => [
                'tools' => ['listChanged' => false],
            ],
            'serverInfo' => [
                'name'    => config('mcp.server_name'),
                'version' => config('app.version', '1.0.0'),
            ],
        ];
    }
}

listChanged: false informa ao cliente que sua lista de ferramentas é estática para a sessão. Defina como true apenas se você implementar o mecanismo de notificação push correspondente, caso contrário, você está anunciando uma capacidade que não pode cumprir.

Construindo a camada de rotas do Laravel

Todas as chamadas JSON-RPC chegam como um POST para um único endpoint. Este é o contrato de transporte do MCP: uma URL, todo o despacho de métodos tratado pelo servidor.

// routes/api.php

use App\Http\Controllers\McpController;

Route::middleware(['auth:sanctum', 'ability:mcp:connect', 'throttle:mcp'])
    ->group(function () {
        Route::post('/mcp', [McpController::class, 'handle']);
    });

Uma closure aqui é tentadora e errada. O controlador dedicado oferece injeção de construtor, testabilidade e um ponto de extensão limpo quando sua lista de métodos cresce.

// app/Http/Controllers/McpController.php

namespace App\Http\Controllers;

use App\MCP\Exceptions\McpException;
use App\MCP\Handlers\I