CÓMO CREAR UN MCP SERVER CON LARAVEL

El MCP, o Model Context Protocol, es el estándar abierto impulsado por Anthropic que permite a los modelos de IA interactuar de forma estructurada y segura con las aplicaciones. Laravel lanzó su paquete oficial "laravel/mcp", haciendo que crear un servidor MCP sea tan sencillo como cualquier otra funcionalidad del framework.
Un MCP Server tiene:
  • Tools: Acciones que la IA puede ejecutar como crear registros, enviar emails, etc.
  • Resources: Datos que la IA puede leer
  • Prompts: Plantillas reutilizables de instrucciones
Esto permite que cualquier cliente MCP controle la aplicación de forma conversacional, sin APIs REST tradicionales.

Instalación

composer require laravel/mcp

# Publicar las rutas de AI
php artisan vendor:publish --tag=ai-routes
#Este comando crea el archivo routes/ai.php.

Crear el MCP Server

Ejecutar el comando:

php artisan make:mcp-server TaskServer
Generándose el archivo en "app/Mcp/Servers/TaskServer.php":

namespace App\Mcp\Servers;

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

#[Name('Task Manager')]
#[Version('1.0.0')]
#[Instructions('Este servidor permite gestionar tareas de forma inteligente.')]
class TaskServer extends Server
{
    protected array $tools = [
        // Registrar tools aquí
    ];

    protected array $resources = [
        // Registrar resources aquí
    ];

    protected array $prompts = [
        // Registrar prompts aquí
    ];
}

Registrar el Server

En "routes/ai.php":


use App\Mcp\Servers\TaskServer;
use Laravel\Mcp\Facades\Mcp;

// Servidor web (recomendado para producción)
Mcp::web('/mcp/tasks', TaskServer::class)
    ->middleware(['auth:sanctum']); // o 'auth:api' con Passport

// Servidor local (para desarrollo con Claude Desktop, Cursor, etc.)
// Mcp::local('tasks', TaskServer::class);

Crear Tools

Ejecutar el comando:

php artisan make:mcp-tool CreateTaskTool
Ejemplo completo de un Tool:

namespace App\Mcp\Tools;

use App\Models\Task;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\Tool;

#[Description('Crea una nueva tarea en el sistema.')]
class CreateTaskTool extends Tool
{
    public function handle(Request $request): Response
    {
        $validated = $request->validate([
            'title' => 'required|string|max:255',
            'description' => 'nullable|string',
            'priority' => 'in:low,medium,high',
        ], [
            'title.required' => 'Debes proporcionar un título para la tarea.',
        ]);

        $task = Task::create($validated);

        return Response::text("Tarea creada correctamente:\n\n**{$task->title}**");
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'title' => $schema->string()
                ->description('Título de la tarea')
                ->required(),
            'description' => $schema->string()->description('Descripción detallada'),
            'priority' => $schema->enum(['low', 'medium', 'high'])
                ->description('Prioridad')
                ->default('medium'),
        ];
    }
}
Regístrarlo en el fichero "TaskServer":

protected array $tools = [
    \App\Mcp\Tools\CreateTaskTool::class,
    // ...
];

Autenticación

Laravel MCP soporta la autenticación de forma nativa:

Probar el MCP Server

  1. Levantar el servidor localmente.
  2. Usar Claude Desktop, Cursor, o el MCP Inspector.
  3. Conectar el servidor y probar comandos como: "Crea una tarea para revisar el presupuesto del Q3" o "Muéstrame las tareas pendientes"

Consejos Avanzados

  • Usar Inyeccion de Dependencias en las Tools. Se pueden inyectar Repositories, Services, etc.).
  • Implementar Resources para exponer datos de lectura.
  • Añadir Prompts para comportamientos predefinidos.
  • Usar anotaciones como "#[IsReadOnly]", "#[IsIdempotent]", etc.
  • Implementar logs.