> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Los agentes de IA de Laravel ahora soportan MCP

> Explica la funcionalidad de cliente MCP añadida a Laravel AI SDK y Laravel MCP. Ahora puedes incorporar tal cual las herramientas de un servidor MCP en el tools() de un agente.

## Descripción general

En junio de 2026, el [blog oficial de Laravel](https://laravel.com/blog/laravel-ai-agents-now-support-mcp-servers) 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».

<Info>
  Para los detalles sobre el propio funcionamiento de MCP consulta la [documentación de Laravel MCP](https://laravel.com/docs/mcp). En esta página nos centramos en la funcionalidad de cliente.
</Info>

## 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.

```mermaid theme={null}
graph LR
    A["laravel/mcp<br>Cliente MCP"] --> B["Conexión, autenticación, handshake"]
    C["laravel/ai<br>Capa fina de integración"] --> D["Añadir tal cual las herramientas MCP<br>al tools() del agente"]
    A --> C
```

* **`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.

```php theme={null}
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

```php theme={null}
$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.

```php theme={null}
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.

```php theme={null}
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.

```blade theme={null}
<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.

```php theme={null}
$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.

```php theme={null}
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.

```php theme={null}
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.

```php theme={null}
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.

```php theme={null}
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`.

```php theme={null}
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

<CardGroup cols={2}>
  <Card title="Crear un proveedor personalizado para AI SDK" href="/es/advanced/ai-sdk-custom-provider" icon="plug">
    Cómo implementar un proveedor personalizado para servicios de IA que no estén soportados por defecto.
  </Card>

  <Card title="Introducción a Laravel Nightwatch" href="/es/blog/nightwatch-introduction" icon="binoculars">
    Explicación del servicio alojado de monitorización Nightwatch, utilizado como ejemplo en este artículo.
  </Card>
</CardGroup>


## Related topics

- [Laravel Agent Detector — Paquete de detección de agentes de IA](/es/blog/agent-detector-introduction.md)
- [Los agentes de IA pasan de código «correcto» a código «idiomático de Laravel»: el siguiente paso de Boost Benchmarks](/es/blog/boost-benchmarks-idiomatic-laravel.md)
- [laravel/agent-skills — Colección oficial de skills para agentes de IA de Laravel](/es/blog/agent-skills-introduction.md)
- [Laravel PAO — Herramienta de optimización de salida para agentes de IA](/es/blog/pao-introduction.md)
- [Actualización de Laravel — Junio de 2026](/es/blog/changelog/202606.md)