> ## 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 客户端功能。现在可以直接将 MCP 服务器的工具整合进智能体的 tools()。

## 概要

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 团队将功能分成了两部分。

```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 的输入 schema 转换为 Laravel 的 JSON Schema，当模型调用工具时进行远程调用，并规范化结果后返回。错误、结构化数据、纯文本、流式更新都会被自动处理，因此 MCP 的细节不会渗透到智能体侧的代码中。

多种传输方式也可以混合在同一个智能体中。

```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 的 fake 功能来测试智能体。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');
```

智能体的常规循环会照常运行，只有模型的发言由 fake 决定。工具调用本身会真实通过 MCP 层，因此可以在不接入网络的情况下测试与生产相同的路径。

## 当前支持范围

在此次首次发布中，STDIO 和 Streamable HTTP 两种传输均支持工具与提示。认证支持 Bearer 令牌和 OAuth。随着 MCP 本身的演进，未来支持范围也会不断扩大。

## 相关页面

<CardGroup cols={2}>
  <Card title="创建 AI SDK 的自定义提供商" href="/zh-CN/advanced/ai-sdk-custom-provider" icon="plug">
    如何为标准未支持的 AI 服务实现自定义提供商
  </Card>

  <Card title="Laravel Nightwatch 入门" href="/zh-CN/blog/nightwatch-introduction" icon="binoculars">
    介绍本文示例中使用的托管型监控服务 Nightwatch
  </Card>
</CardGroup>


## Related topics

- [2026 年 5 月 Laravel 更新](/zh-CN/blog/changelog/202605.md)
- [Laravel Doctor — 应用程序诊断工具](/zh-CN/blog/laravel-doctor-introduction.md)
- [2026 年 6 月 Laravel 更新](/zh-CN/blog/changelog/202606.md)
- [Laravel AI SDK](/zh-CN/ai-sdk.md)
- [laravel/agent-skills — Laravel 官方 AI 智能体技能集](/zh-CN/blog/agent-skills-introduction.md)