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

# Laravel-KI-Agenten unterstützen MCP-Server

> Erläuterung der MCP-Client-Funktion, die zu Laravel AI SDK und Laravel MCP hinzugefügt wurde. Sie können nun Tools eines MCP-Servers direkt in die tools()-Methode Ihres Agents einbinden.

## Überblick

Im Juni 2026 wurde im [offiziellen Laravel-Blog](https://laravel.com/blog/laravel-ai-agents-now-support-mcp-servers) angekündigt, dass mit dem Laravel AI SDK erstellte KI-Agenten sich nun mit **MCP-Servern (Model Context Protocol)** verbinden können.

Bislang bot Laravel MCP die Möglichkeit, eine Laravel-Anwendung „als **MCP-Server** bereitzustellen". Neu hinzugekommen ist nun die entgegengesetzte Richtung: die Fähigkeit, dass eine Laravel-Anwendung „als **MCP-Client** eine Verbindung zu anderen MCP-Servern aufbaut".

<Info>
  Die genaue Funktionsweise von MCP selbst finden Sie in der [Laravel-MCP-Dokumentation](https://laravel.com/docs/mcp). Diese Seite konzentriert sich ausschließlich auf die Client-Funktionalität.
</Info>

## Warum die Implementierung in Laravel MCP statt im AI SDK erfolgte

MCP ist ein Protokoll mit breitem Anwendungsbereich, das Transport-Aushandlung, Handshake, Authentifizierungsflüsse und mehr umfasst. Wäre dies direkt im AI SDK implementiert worden, ließe es sich in Szenarien ohne Agent (etwa Queue-Jobs oder Konsolenbefehle) nicht wiederverwenden.

Deshalb hat das Laravel-Team die Funktionalität in zwei Teile aufgeteilt.

```mermaid theme={null}
graph LR
    A["laravel/mcp<br>MCP-Client"] --> B["Verbindung, Auth, Handshake"]
    C["laravel/ai<br>Dünne Integrationsschicht"] --> D["MCP-Tools direkt zur<br>tools()-Methode des Agents hinzufügen"]
    A --> C
```

* **`laravel/mcp`**: Der eigentliche MCP-Client, zuständig für Verbindung, Aushandlung, Authentifizierung und Tool-Aufrufe.
* **`laravel/ai`**: Eine dünne Integrationsschicht, die es Agents ermöglicht, diesen Client nahtlos über `tools()` zu nutzen.

Beide können eigenständig verwendet werden. In Kombination lassen sich Tools eines MCP-Servers vom Agent genauso behandeln wie handgeschriebene Tools.

## Verbindung zu einem MCP-Server

Es werden sowohl STDIO-Server, die als lokale Prozesse gestartet werden, als auch Remote-Server über HTTP unterstützt.

```php theme={null}
use Laravel\Mcp\Client;

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

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

Verbindung, Handshake und die Aushandlung der Protokollversion werden vollständig vom Client übernommen. Die Anwendung muss lediglich `tools()` aufrufen.

## Authentifizierung

### Bearer-Token

```php theme={null}
$tools = Client::web('https://mcp.example.com')
    ->withToken($token)
    ->tools();
```

### OAuth

Viele gehostete MCP-Server wie Nightwatch erfordern OAuth. Registrieren Sie einen benannten Client im 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()
);
```

Verdrahten Sie die OAuth-Routen und die Callback-Verarbeitung.

```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');
```

Damit werden `mcp.oauth.nightwatch.connect` und die zugehörige Callback-Route generiert. Auf der Blade-Seite genügt es, einen Verbindungs-Button zu platzieren.

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

Wenn sich der Benutzer einloggt und autorisiert, erhält die Callback-Closure das Token. Sie müssen sich weder um die Redirect-URL noch um die Details von PKCE selbst kümmern.

Für Hintergrundverarbeitung ohne Benutzerinteraktion steht auch der Client-Credentials-Grant zur Verfügung.

```php theme={null}
$token = Mcp::client('billing')->oAuthClient()->clientCredentials();
```

## Integration in einen Agent

Der wichtigste Punkt ist, dass MCP-Tools ohne Änderung der `tools()`-Methode des Agents beigemischt werden können.

```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 erkennt, dass es sich bei den Elementen des `tools()`-Arrays um MCP-Tools handelt, und verpackt sie so, dass sie zum Tool-Vertrag des Agents passen. Das Eingabeschema von MCP wird in ein Laravel-JSON-Schema konvertiert, bei einem Tool-Aufruf des Modells wird der Remote-Aufruf ausgeführt und das Ergebnis normalisiert zurückgegeben. Fehler, strukturierte Daten, reiner Text und Streaming-Updates werden alle automatisch behandelt, sodass keine MCP-Details in den Agent-Code durchsickern.

Mehrere Transporte können auch in einem einzigen Agent gemischt werden.

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

Darüber hinaus können Sie Tool-Klassen, die Sie für Ihren eigenen Laravel-MCP-Server geschrieben haben, ohne Client-Verbindung direkt an den Agent übergeben. Dasselbe Tool lässt sich also sowohl für die externe Veröffentlichung als auch für Ihre Agents wiederverwenden.

```php theme={null}
use App\Mcp\Tools\CurrentWeatherTool;

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

## Cachen der Tool-Liste

Das Abrufen der Tool-Liste erfordert einen Roundtrip zum Server. Insbesondere bei Remote-Servern über OAuth ist es verschwenderisch, dies bei jedem Prompt zu tun. Da sich Tool-Listen selten ändern, eignen sie sich gut fürs Caching.

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

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

Da MCP-Tools als reine Daten zurückgegeben werden, funktionieren sie auch nach dem Wiederherstellen aus dem Cache unverändert.

## Testen

Auch ohne einen tatsächlich laufenden MCP-Server können Sie Agents mit der Fake-Funktion von Laravel AI testen. MCP-Tool-Namen folgen der Konvention `mcp_tools_<name>`, daher erscheint ein Tool namens `search` als `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');
```

Die normale Schleife des Agents läuft weiter, nur die Aussagen des Modells werden vom Fake festgelegt. Die Tool-Aufrufe selbst durchlaufen tatsächlich die MCP-Schicht, sodass Sie ohne Netzwerkverbindung denselben Pfad wie in der Produktion testen können.

## Aktueller Funktionsumfang

In diesem ersten Release werden sowohl STDIO- als auch Streamable-HTTP-Transporte unterstützt, ebenso Tools und Prompts. Bei der Authentifizierung werden Bearer-Token und OAuth unterstützt. Der Funktionsumfang wird sich mit der Weiterentwicklung von MCP selbst weiter erweitern.

## Verwandte Seiten

<CardGroup cols={2}>
  <Card title="Einen benutzerdefinierten Provider für das AI SDK erstellen" href="/de/advanced/ai-sdk-custom-provider" icon="plug">
    Implementierung eines benutzerdefinierten Providers für nicht standardmäßig unterstützte KI-Dienste
  </Card>

  <Card title="Einführung in Laravel Nightwatch" href="/de/blog/nightwatch-introduction" icon="binoculars">
    Erläuterung des in diesem Artikel als Beispiel verwendeten gehosteten Monitoring-Dienstes Nightwatch
  </Card>
</CardGroup>


## Related topics

- [Laravel und KI-Entwicklung](/de/ai.md)
- [Laravel Boost](/de/boost.md)
- [Einen eigenen Agenten für Boost erstellen](/de/advanced/boost-custom-agent.md)
- [Laravel AI SDK](/de/ai-sdk.md)
- [Weiterführende Themen](/de/advanced/index.md)