> ## 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 AIエージェントがMCPサーバーに対応

> Laravel AI SDKとLaravel MCPに追加されたMCPクライアント機能を解説します。エージェントのtools()にMCPサーバーのツールをそのまま組み込めるようになりました。

## 概要

2026年6月、[Laravel公式ブログ](https://laravel.com/blog/laravel-ai-agents-now-support-mcp-servers)で、Laravel AI SDKで構築したAIエージェントから **MCP（Model Context Protocol）サーバー**に接続できるようになったことが発表されました。

これまでLaravel MCPは「Laravelアプリを **MCPサーバーとして** 公開する」機能を提供していましたが、今回追加されたのは逆方向、つまり「Laravelアプリが **MCPクライアントとして** 他のMCPサーバーに接続する」機能です。

<Info>
  MCP自体の詳しい仕組みは[Laravel MCPのドキュメント](https://laravel.com/docs/mcp)を参照してください。このページではクライアント機能に絞って解説します。
</Info>

## なぜAI SDK本体ではなくLaravel MCPに実装されたか

MCPはトランスポートのネゴシエーション、ハンドシェイク、認証フローなど扱う範囲が広いプロトコルです。これをAI SDK内に直接実装すると、エージェントなしでMCPサーバーと通信したい場面（キュージョブやコンソールコマンドなど）で再利用できません。

そこでLaravel チームは機能を2つに分けました。

```mermaid theme={null}
graph LR
    A["laravel/mcp<br>MCPクライアント"] --> B["接続・認証・ハンドシェイク"]
    C["laravel/ai<br>薄い統合層"] --> D["エージェントのtools()に<br>MCPツールをそのまま追加"]
    A --> C
```

* **`laravel/mcp`**：接続・ネゴシエーション・認証・ツール呼び出しを担当するMCPクライアント本体
* **`laravel/ai`**：エージェントがそのクライアントを`tools()`から違和感なく使えるようにする薄い統合層

それぞれが単独でも使え、組み合わせるとエージェントからMCPサーバーのツールを手書きのツールと同じように扱えます。

## MCPサーバーへの接続

ローカルプロセスとして起動するSTDIOサーバーと、HTTP経由のリモートサーバーの両方に対応しています。

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

// ローカルサーバー（STDIO）
$client = Client::local('npx', ['-y', '@modelcontextprotocol/puppeteer']);
$tools = $client->tools();

// リモートサーバー（Streamable HTTP）
$client = Client::web('https://nightwatch.laravel.com/mcp');
$tools = $client->tools();
```

接続、ハンドシェイク、プロトコルバージョンのネゴシエーションはすべてクライアントが処理するため、アプリ側は`tools()`を呼ぶだけで済みます。

## 認証

### Bearerトークン

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

### OAuth

Nightwatchなど多くのホスト型MCPサーバーはOAuthを要求します。サービスプロバイダーで名前付きクライアントを登録します。

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

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

OAuthのルートとコールバック処理を配線します。

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

これで`mcp.oauth.nightwatch.connect`と対応するコールバックルートが生成されます。Blade側では接続ボタンを置くだけです。

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

ユーザーがログインして承認すると、コールバックのクロージャがトークンを受け取ります。リダイレクトURLやPKCEの詳細を自分で扱う必要はありません。

ユーザーの介在がないバックグラウンド処理向けには、クライアントクレデンシャルグラントも用意されています。

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

## エージェントへの組み込み

一番のポイントは、エージェントの`tools()`メソッドを変更せずにMCPツールを混ぜられることです。

```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は`tools()`配列の中身がMCPツールであることを検知し、エージェントのツール契約に合うようラップします。MCPの入力スキーマをLaravelのJSONスキーマに変換し、モデルがツールを呼び出したときにリモート呼び出しを行い、結果を正規化して返します。エラー、構造化データ、プレーンテキスト、ストリーミング更新のいずれも自動的に処理されるため、エージェント側のコードにMCPの詳細が漏れ出すことはありません。

複数のトランスポートを1つのエージェントに混在させることもできます。

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

さらに、自分のLaravel MCPサーバー用に書いたツールクラスは、クライアント接続なしにそのままエージェントへ渡せます。同じツールを外部公開用とエージェント用の両方で使い回せるということです。

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

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

## ツール一覧のキャッシュ

ツール一覧の取得にはサーバーへの往復が発生します。特にOAuth経由のリモートサーバーでは、プロンプトのたびに呼び出すのは無駄です。ツール一覧は頻繁に変わらないため、キャッシュ対象として適しています。

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

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

MCPツールはプレーンなデータとして返るため、キャッシュから復元してもそのまま動作します。

## テスト

実際に稼働しているMCPサーバーがなくても、Laravel AIのフェイク機能でエージェントをテストできます。MCPツール名は`mcp_tools_<name>`という命名規則に従うため、`search`というツールは`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');
```

エージェントの通常のループはそのまま動き、モデルの発言だけをフェイクが決定します。ツール呼び出し自体はMCPレイヤーを実際に通過するため、ネットワークなしで本番と同じ経路をテストできます。

## 現時点でサポートされる範囲

この最初のリリースでは、STDIOとStreamable HTTPの両トランスポートで、ツールとプロンプトをサポートしています。認証はBearerトークンとOAuthに対応しています。MCP自体の進化に合わせて、今後も対応範囲が広がっていく見込みです。

## 関連ページ

<CardGroup cols={2}>
  <Card title="AI SDKのカスタムプロバイダーを作る" href="/jp/advanced/ai-sdk-custom-provider" icon="plug">
    標準対応していないAIサービスに対応するカスタムプロバイダーの実装方法
  </Card>

  <Card title="Laravel Nightwatch 入門" href="/jp/blog/nightwatch-introduction" icon="binoculars">
    この記事で例に使われているホスト型監視サービスNightwatchの解説
  </Card>
</CardGroup>


## Related topics

- [Laravel AI SDK](/jp/ai-sdk.md)
- [Laravel Boost](/jp/boost.md)
- [応用トピック](/jp/advanced/index.md)
- [laravel/agent-skills — Laravel公式AIエージェントスキル集](/jp/blog/agent-skills-introduction.md)
- [2026年6月 Laravel アップデート](/jp/blog/changelog/202606.md)