Los agentes de IA de Laravel ahora soportan MCP

Descripción general

En junio de 2026, el blog oficial de Laravel anunció que los agentes de IA construidos con Laravel AI SDK pueden ya conectarse a servidores MCP (Model Context Protocol). Hasta ahora, Laravel MCP ofrecía la posibilidad de «publicar la app Laravel como servidor MCP», pero lo que se ha añadido es la dirección contraria: la funcionalidad para que «una app Laravel se conecte como cliente MCP a otros servidores MCP».

Para los detalles sobre el propio funcionamiento de MCP consulta la documentación de Laravel MCP. En esta página nos centramos en la funcionalidad de cliente.

Por qué se implementó en Laravel MCP y no en AI SDK

MCP es un protocolo con un alcance amplio: negociación de transporte, handshake, flujos de autenticación, etc. Si se hubiese implementado directamente dentro de AI SDK, no podría reutilizarse en escenarios donde quieras comunicarte con un servidor MCP sin un agente (jobs en cola, comandos de consola, etc.). Por eso el equipo de Laravel dividió la funcionalidad en dos.

laravel/mcp: el propio cliente MCP, que se encarga de la conexión, la negociación, la autenticación y las llamadas a herramientas.
laravel/ai: la fina capa de integración que permite a los agentes usar ese cliente sin fricciones desde tools().

Cada uno puede utilizarse por separado y, combinándolos, un agente puede manejar herramientas de un servidor MCP de la misma forma que herramientas escritas a mano.

Conexión a un servidor MCP

Se soportan tanto los servidores STDIO que se arrancan como proceso local como los servidores remotos vía HTTP.

use Laravel\Mcp\Client;

// Servidor local (STDIO)
$client = Client::local('npx', ['-y', '@modelcontextprotocol/puppeteer']);
$tools = $client->tools();

// Servidor remoto (Streamable HTTP)
$client = Client::web('https://nightwatch.laravel.com/mcp');
$tools = $client->tools();

La conexión, el handshake y la negociación de versión del protocolo los realiza el cliente, así que del lado de la aplicación basta con llamar a tools().

Autenticación

Token Bearer

$tools = Client::web('https://mcp.example.com')
    ->withToken($token)
    ->tools();

OAuth

Muchos servidores MCP alojados, como Nightwatch, requieren OAuth. Registra un cliente con nombre en un service provider.

use Laravel\Mcp\Client;
use Laravel\Mcp\Facades\Mcp;

Mcp::registerClient('nightwatch', fn () =>
    Client::web('https://nightwatch.laravel.com/mcp')->withOAuth()
);

Conecta las rutas de OAuth y el manejo del callback.

use Laravel\Mcp\Facades\Mcp;
use Laravel\Mcp\Client\OAuth\TokenSet;

Mcp::oAuthRoutesFor('nightwatch', function (string $provider, TokenSet $token) {
    auth()->user()->update([
        'mcp_nightwatch_token' => encrypt($token->accessToken),
        'mcp_nightwatch_refresh' => encrypt($token->refreshToken),
    ]);

    return redirect('/dashboard');
}, middleware: 'auth');

Esto genera mcp.oauth.nightwatch.connect y la ruta de callback correspondiente. En Blade basta con colocar un botón de conexión.

<a href="{{ route('mcp.oauth.nightwatch.connect') }}">
    Connect Nightwatch
</a>

Cuando el usuario inicia sesión y da su consentimiento, el closure del callback recibe el token. No necesitas encargarte tú mismo de la URL de redirección ni de los detalles de PKCE. Para procesos en segundo plano sin intervención del usuario, también se dispone del flujo Client Credentials.

$token = Mcp::client('billing')->oAuthClient()->clientCredentials();

Integración con el agente

El punto clave es que puedes mezclar herramientas MCP en el método tools() del agente sin cambiar su firma.

use Laravel\Mcp\Facades\Mcp;
use App\Tools\SendSlackMessage;

class SupportAgent extends Agent
{
    public function instructions(): string
    {
        return 'You help triage production issues.';
    }

    public function tools(): array
    {
        return [
            ...Mcp::client('nightwatch')
                ->withToken(auth()->user()->mcp_nightwatch_token)
                ->tools(),
            new SendSlackMessage,
        ];
    }
}

Laravel AI detecta que los elementos del array tools() son herramientas MCP y los envuelve para que cumplan el contrato de herramienta del agente. Convierte el esquema de entrada de MCP al esquema JSON de Laravel, realiza la llamada remota cuando el modelo invoca la herramienta y normaliza el resultado antes de devolverlo. Los errores, los datos estructurados, el texto plano y las actualizaciones en streaming se gestionan automáticamente, de modo que los detalles de MCP no se filtran al código del agente. También puedes mezclar varios transportes en un mismo agente.

public function tools(): array
{
    return [
        ...Mcp::client('nightwatch')->tools(),
        ...Client::local('npx', ['-y', '@modelcontextprotocol/server-puppeteer'])->tools(),
        new SendSlackMessage,
    ];
}

Además, las clases de herramienta que hayas escrito para tu propio servidor Laravel MCP puedes pasárselas al agente tal cual, sin conexión de cliente. Es decir, puedes reutilizar la misma herramienta tanto para exponerla al exterior como para el agente.

use App\Mcp\Tools\CurrentWeatherTool;

public function tools(): array
{
    return [
        new CurrentWeatherTool,
        new SendSlackMessage,
    ];
}

Caché de la lista de herramientas

Obtener la lista de herramientas implica una ida y vuelta al servidor. Especialmente en servidores remotos con OAuth, es un desperdicio llamarlos en cada prompt. Como la lista de herramientas no cambia con frecuencia, es un buen candidato para cachearse.

public function tools(): array
{
    $tools = Cache::remember('mcp.nightwatch.tools', now()->addHour(), fn () =>
        Mcp::client('nightwatch')->tools()
    );

    return [...$tools, new SendSlackMessage];
}

Las herramientas MCP se devuelven como datos planos, así que aunque las restaures desde la caché funcionarán tal cual.

Pruebas

Aunque no tengas un servidor MCP realmente en marcha, puedes probar el agente con las funcionalidades de fake de Laravel AI. Los nombres de las herramientas MCP siguen la convención mcp_tools_<nombre>, así que una herramienta llamada search aparecerá como mcp_tools_search.

use Laravel\Ai\Responses\Data\ToolCall;

SupportAgent::fake([
    new ToolCall('call_1', 'mcp_tools_search', ['query' => 'laravel']),
    'Found the issue.',
]);

$response = (new SupportAgent)->prompt('Find the latest error');

expect($response->toolCalls)->toHaveCount(1);
expect($response->toolResults->first()->result)->toContain('Found');

El bucle normal del agente sigue funcionando y solo se determinan por el fake las respuestas del modelo. La invocación de herramientas atraviesa la capa MCP real, así que puedes probar la misma ruta que en producción sin necesidad de red.

Alcance soportado actualmente

En esta primera versión se soportan herramientas y prompts tanto sobre transporte STDIO como Streamable HTTP. La autenticación admite tokens Bearer y OAuth. A medida que evolucione el propio MCP se prevé que el alcance del soporte también crezca.

Páginas relacionadas

Crear un proveedor personalizado para AI SDK

Cómo implementar un proveedor personalizado para servicios de IA que no estén soportados por defecto.

Introducción a Laravel Nightwatch

Explicación del servicio alojado de monitorización Nightwatch, utilizado como ejemplo en este artículo.

Changelog

Laravel 13

Productos

Presentación de paquetes

Análisis de nuevos repositorios

Guías de actualización

Autenticación

Frontend

Configuración del entorno

Los agentes de IA de Laravel ahora soportan MCP

Descripción general

Por qué se implementó en Laravel MCP y no en AI SDK

Conexión a un servidor MCP

Autenticación

Token Bearer

OAuth

Integración con el agente

Caché de la lista de herramientas

Pruebas

Alcance soportado actualmente

Páginas relacionadas

Crear un proveedor personalizado para AI SDK

Introducción a Laravel Nightwatch

​Descripción general

​Por qué se implementó en Laravel MCP y no en AI SDK

​Conexión a un servidor MCP

​Autenticación

​Token Bearer

​OAuth

​Integración con el agente

​Caché de la lista de herramientas

​Pruebas

​Alcance soportado actualmente

​Páginas relacionadas

Crear un proveedor personalizado para AI SDK

Introducción a Laravel Nightwatch

Descripción general

Por qué se implementó en Laravel MCP y no en AI SDK

Conexión a un servidor MCP

Autenticación

Token Bearer

OAuth

Integración con el agente

Caché de la lista de herramientas

Pruebas

Alcance soportado actualmente

Páginas relacionadas