*/
public function icons(): array
{
return [
Icon::from('mcp/tool.png', mimeType: 'image/png'),
];
}
}
```
通过特性和 `icons` 方法定义的图标会自动合并。图标路径按以下规则解析：
- 带有 `https:` 或 `data:` 等 URI 方案的路径按原样使用。
- 相对路径使用 Laravel 的 `asset` 辅助函数解析为 URL。
## 身份认证
与路由一样，你可以使用中间件对 Web MCP 服务器进行身份认证。为 MCP 服务器添加身份认证后，用户必须先通过认证才能使用服务器的任何功能。
本节介绍外部 AI 客户端访问**你的应用的 MCP 服务器**时的认证。如果要使用用户凭据将你的应用连接到其他服务的 MCP 服务器，请参阅[客户端身份认证](#client-authentication)。
你可以通过两种方式对 MCP 服务器的访问进行身份认证：使用 [Laravel Sanctum](/docs/laravel/13.x/sanctum)，或通过 `Authorization` HTTP 请求头传入任意令牌，进行简单的令牌认证；也可以使用 [Laravel Passport](/docs/laravel/13.x/passport) 进行 OAuth 认证。
### OAuth 2.1
保护 Web MCP 服务器最完善的方式，是通过 [Laravel Passport](/docs/laravel/13.x/passport) 使用 OAuth 认证。
通过 OAuth 对 MCP 服务器进行身份认证时，请在 `routes/ai.php` 文件中调用 `Mcp::oauthRoutes` 方法，注册所需的 OAuth2 发现路由和客户端注册路由。然后，在同一文件中为 `Mcp::web` 路由应用 Passport 的 `auth:api` 中间件：
```php
use App\Mcp\Servers\WeatherExample;
use Laravel\Mcp\Facades\Mcp;
Mcp::oauthRoutes();
Mcp::web('/mcp/weather', WeatherExample::class)
->middleware('auth:api');
```
#### 全新安装 Passport
如果你的应用尚未使用 Laravel Passport，请按照 Passport 的[安装和部署指南](/docs/laravel/13.x/passport#installation)将其添加到应用中。继续之前，你应准备好一个 `OAuthenticatable` 模型、新的认证看守器以及 Passport 密钥。
接下来，发布 Laravel MCP 提供的 Passport 授权视图：
```shell
php artisan vendor:publish --tag=mcp-views
```
然后，使用 `Passport::authorizationView` 方法让 Passport 使用该视图。通常应在应用的 `AppServiceProvider` 的 `boot` 方法中调用此方法：
```php
use Laravel\Passport\Passport;
/**
* 引导应用服务。
*/
public function boot(): void
{
Passport::authorizationView(function ($parameters) {
return view('mcp.authorize', $parameters);
});
}
```
在身份认证期间，此视图会显示给最终用户，让他们拒绝或批准 AI 智能体的认证请求。
> [!NOTE]
> 在此场景中，我们只是将 OAuth 用作与底层可认证模型之间的转换层，并未处理 OAuth 的许多方面，例如作用域。
#### 使用现有的 Passport 安装
如果你的应用已使用 Laravel Passport，Laravel MCP 应能与现有的 Passport 安装无缝配合。不过，由于 OAuth 主要被用作与底层可认证模型之间的转换层，目前不支持自定义作用域。
Laravel MCP 通过上述 `Mcp::oauthRoutes` 方法，添加、公布并使用单一的 `mcp:use` 作用域。
#### Passport 与 Sanctum
OAuth2.1 是模型上下文协议规范中规定的身份认证机制，也是 MCP 客户端支持最广泛的机制。因此，我们建议尽可能使用 Passport。
如果你的应用已使用 [Sanctum](/docs/laravel/13.x/sanctum)，再添加 Passport 可能较为繁琐。在这种情况下，我们建议继续使用 Sanctum，直到明确需要使用仅支持 OAuth 的 MCP 客户端时，再添加 Passport。
#### 限制 OAuth 路由的请求频率
根据 MCP 规范和 RFC 7591 的要求，`Mcp::oauthRoutes` 注册的动态客户端注册路由可公开访问，允许任意 MCP 客户端无需身份认证即可注册。由于每次注册都会在数据库中创建新的 OAuth 客户端，你应根据应用的流量对这些路由进行频率限制。为此，可以在应用 Laravel `throttle` 中间件的路由组内注册这些路由：
```php
use Illuminate\Support\Facades\Route;
use Laravel\Mcp\Facades\Mcp;
Route::middleware('throttle:10,1')->group(function () {
Mcp::oauthRoutes();
});
```
如果 MCP 客户端无需动态注册自身，你可以将 `registration` 参数设为 `false`，完全禁用客户端注册路由：
```php
Mcp::oauthRoutes(registration: false);
```
### Sanctum
如果你想使用 [Sanctum](/docs/laravel/13.x/sanctum) 保护 MCP 服务器，只需在 `routes/ai.php` 文件中为服务器添加 Sanctum 的身份认证中间件。然后，确保 MCP 客户端提供 `Authorization: Bearer ` 请求头，以顺利通过身份认证：
```php
use App\Mcp\Servers\WeatherExample;
use Laravel\Mcp\Facades\Mcp;
Mcp::web('/mcp/demo', WeatherExample::class)
->middleware('auth:sanctum');
```
#### 自定义 MCP 身份认证
如果你的应用签发自定义 API 令牌，你可以为 `Mcp::web` 路由分配任意中间件，对 MCP 服务器进行身份认证。自定义中间件可以手动检查 `Authorization` 请求头，以认证传入的 MCP 请求。
## 授权
你可以通过 `$request->user()` 方法访问当前已认证用户，从而在 MCP 工具和资源中执行[授权检查](/docs/laravel/13.x/authorization)：
```php
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
/**
* 处理工具请求。
*/
public function handle(Request $request): Response
{
if (! $request->user()->can('read-weather')) {
return Response::error('Permission denied.');
}
// ...
}
```
## MCP 客户端
除了构建服务器，Laravel MCP 还包含一个客户端，可连接第一方或第三方的其他 MCP 服务器。客户端让应用能够发现并调用 MCP 服务器开放的工具，尤其适合让 [AI 智能体](/docs/laravel/13.x/ai-sdk#mcp-tools)使用外部 MCP 服务器提供的能力。
例如，聊天应用可以使用每个用户的 GitHub 令牌连接 GitHub 的 MCP 服务器，让智能体回答有关该用户仓库的问题。在此场景中，你的应用是 MCP 客户端，无需创建 MCP 服务器或注册 `Mcp::web` 路由。
### 连接服务器
你可以使用 `Client::web` 方法连接可通过 HTTP 访问的 MCP 服务器，并传入服务器的 URL：
```php
use Laravel\Mcp\Client;
$client = Client::web('https://api.githubcopilot.com/mcp/');
```
要连接以命令形式运行的本地 MCP 服务器，请使用 `Client::local` 方法，提供启动服务器所需的命令和参数：
```php
use Laravel\Mcp\Client;
$client = Client::local('php', ['artisan', 'mcp:start']);
```
客户端采用延迟连接，首次列出或调用工具时会自动建立连接。如果需要手动管理连接，可以使用 `connect`、`connected` 和 `disconnect` 方法：
```php
$client->connect();
if ($client->connected()) {
$capabilities = $client->capabilities();
$server = $client->serverInfo();
}
$client->disconnect();
```
你可以使用 `withTimeout` 方法自定义请求超时时间：
```php
$client = Client::web('https://api.githubcopilot.com/mcp/')->withTimeout(30);
```
### 命名客户端
你可以选择注册可复用的命名客户端，而无需在每次使用时构建客户端。`registerClient` 方法为出站连接命名；它不会开放 MCP 服务器，也不会为用户授予权限。通常使用 `Mcp` 门面，在服务提供者的 `boot` 方法中完成注册：
```php
use Laravel\Mcp\Client;
use Laravel\Mcp\Facades\Mcp;
Mcp::registerClient('github', fn () => Client::web('https://api.githubcopilot.com/mcp/'));
```
注册后，你可以在应用中的任意位置按名称解析客户端：
```php
use Laravel\Mcp\Facades\Mcp;
$client = Mcp::client('github');
```
命名客户端在每个请求中只解析一次，并在请求生命周期结束时自动断开连接。
### 客户端身份认证
#### Bearer 令牌
要连接受 Bearer 令牌保护的 Web MCP 服务器，请使用 `withToken` 方法。你可以传入令牌字符串，也可以传入延迟解析令牌的闭包：
```php
use Illuminate\Support\Facades\Auth;
use Laravel\Mcp\Client;
$client = Client::web('https://api.githubcopilot.com/mcp/')->withToken(
config('services.github_mcp.token'),
);
$client = Client::web('https://api.githubcopilot.com/mcp/')->withToken(
fn () => Auth::user()->github_mcp_token,
);
```
如果你已通过 [Socialite](/docs/laravel/13.x/socialite) 或其他账户关联流程获得合适的令牌，将它传入 `withToken` 即可，无需注册 MCP OAuth 路由。
#### 使用 OAuth 关联用户账户
设想一个聊天应用：用户关联项目管理服务后，向智能体提问「我有哪些任务已逾期？」外部项目管理服务开放了一个受 OAuth 保护的 MCP 服务器。你的应用必须将每个用户重定向到该服务的授权同意页面，用其批准结果换取令牌，并保存令牌以供未来调用工具时使用。
Laravel MCP 使用 `withOAuth` 和 `Mcp::oAuthRoutesFor` 处理此账户关联流程。首先，在服务提供者中注册命名客户端。OAuth 客户端凭据用于向服务标识你的应用，而 `withToken` 则在调用工具时提供已关联用户所保存的访问令牌：
```php
use Illuminate\Support\Facades\Auth;
use Laravel\Mcp\Client;
use Laravel\Mcp\Facades\Mcp;
Mcp::registerClient('projects', fn () => Client::web('https://projects.example.com/mcp')
->withOAuth(
clientId: config('services.projects.client_id'),
clientSecret: config('services.projects.client_secret'),
)
->withToken(fn () => Auth::user()->projects_token));
```
> [!NOTE]
> `clientId` 和 `clientSecret` 参数可以省略。如果授权服务器支持，Laravel 会使用[客户端 ID 元数据文档](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/client-registration#client-id-metadata-documents)；对于旧版服务器，则回退到[动态客户端注册](https://datatracker.ietf.org/doc/html/rfc7591)。
授权服务器必须在其授权服务器元数据中公布对 `S256` PKCE 代码质询方法的支持。如果未公布 PKCE 支持，Laravel 将拒绝授权尝试。
接下来，在 `routes/ai.php` 文件中注册账户关联路由。回调会接收客户端名称和生成的 `TokenSet`，以便为已登录用户保存令牌：
```php
use Illuminate\Support\Facades\Auth;
use Laravel\Mcp\Client\OAuth\TokenSet;
use Laravel\Mcp\Facades\Mcp;
Mcp::oAuthRoutesFor('projects', function (string $client, TokenSet $token) {
Auth::user()->update([
'projects_token' => $token->accessToken,
]);
return redirect('/chat');
}, middleware: ['web', 'auth']);
```
`oAuthRoutesFor` 方法会注册三个命名路由：连接路由（`mcp.oauth.{client}.connect`）将用户重定向到授权服务器；回调路由（`mcp.oauth.{client}.callback`）交换授权码并调用你的处理程序；公开的客户端 ID 元数据文档路由为 `mcp.oauth.{client}.client-metadata`。
连接路由和回调路由默认使用 `web` 中间件组；上面的账户关联示例还添加了 `auth`，要求用户先登录。元数据路由不使用此中间件，因为授权服务器必须能够获取该文档。
「连接项目服务」按钮应将用户导向连接路由：
```php
return redirect()->route('mcp.oauth.projects.connect');
```
Laravel 会将用户重定向到服务以批准访问，在用户返回后交换授权码，并调用你的回调。在后续聊天请求中，命名客户端会使用保存的令牌。例如，[AI SDK 智能体](/docs/laravel/13.x/ai-sdk#mcp-tools)可以开放此服务的工具：
```php
public function tools(): iterable
{
return [
...Mcp::client('projects')->tools(),
];
}
```
使用[加密类型转换](/docs/laravel/13.x/eloquent-mutators#encrypted-casting)保存令牌，并在模型序列化时隐藏它们。如果服务签发的令牌会过期，还应保存 `TokenSet` 中的刷新令牌和过期信息，并在调用工具之前处理续期。对于队列中的智能体，请从显式提供的用户解析凭据，而非使用 `Auth::user()`。
> [!NOTE]
> `Mcp::oAuthRoutesFor` 将你的用户关联到外部服务。相比之下，`Mcp::oauthRoutes` 允许外部 AI 客户端使用 Passport 认证并访问你自己的 MCP 服务器。上述账户关联流程无需使用 Passport 或 `Mcp::oauthRoutes`。
#### 客户端元数据
元数据文档将你的应用描述为公共 OAuth 客户端，并使用应用的 `APP_URL` 生成客户端 ID 和回调 URL。因此，你应确保生产环境中的 `APP_URL` 环境变量设置正确。你可以使用 `clientMetadataUri` 和 `clientMetadata` 参数自定义元数据路由，并提供额外的元数据：
```php
use Laravel\Mcp\Client\OAuth\TokenSet;
use Laravel\Mcp\Facades\Mcp;
Mcp::oAuthRoutesFor(
'projects',
function (string $client, TokenSet $token) {
// 保存令牌……
return redirect('/dashboard');
},
clientMetadataUri: 'oauth/projects/client.json',
clientMetadata: [
'client_name' => 'Acme Dashboard',
'logo_uri' => 'https://acme.com/logo.png',
],
);
```
### 工具
你可以使用 `tools` 方法获取 MCP 服务器开放的工具，该方法返回以名称为键的工具集合：
```php
use Laravel\Mcp\Facades\Mcp;
$tools = Mcp::client('github')->tools();
foreach ($tools as $tool) {
$tool->name;
$tool->title;
$tool->description;
$tool->inputSchema;
}
```
客户端会自动分页获取所有可用工具。你可以使用 `limit` 参数限制返回的工具数量：
```php
$tools = Mcp::client('github')->tools(limit: 10);
```
要调用工具，请使用 `callTool` 方法，传入工具名称和参数数组。返回的 `ToolResult` 实例提供对工具响应的访问：
```php
use Laravel\Mcp\Facades\Mcp;
$result = Mcp::client('github')->callTool('list_issues', [
'owner' => 'laravel',
'repo' => 'framework',
]);
$result->text(); // 响应的文本内容……
(string) $result; // 等同于调用 text()……
$result->isError; // 工具是否报告了错误……
$result->structuredContent; // 结构化内容（如果有）……
```
你也可以直接从已列出的工具实例调用工具：
```php
$tools = Mcp::client('github')->tools();
$result = $tools['list_issues']->call([
'owner' => 'laravel',
'repo' => 'framework',
]);
```
如果你使用 [Laravel AI SDK](/docs/laravel/13.x/ai-sdk) 构建智能体，也可以将 MCP 客户端中的工具直接提供给智能体，让模型在响应提示词时调用它们。更多信息请参阅 AI SDK 文档的 [MCP 工具](/docs/laravel/13.x/ai-sdk#mcp-tools)一节。
### 提示词
你可以使用 `prompts` 方法获取 MCP 服务器开放的提示词，该方法返回以名称为键的提示词集合：
```php
use Laravel\Mcp\Facades\Mcp;
$prompts = Mcp::client('github')->prompts();
foreach ($prompts as $prompt) {
$prompt->name;
$prompt->title;
$prompt->description;
$prompt->arguments;
}
```
客户端会自动分页获取所有可用提示词。你可以使用 `limit` 参数限制返回的提示词数量：
```php
$prompts = Mcp::client('github')->prompts(limit: 10);
```
要获取提示词，请使用 `getPrompt` 方法，传入提示词名称和参数数组。返回的 `PromptResult` 实例提供对生成消息的访问：
```php
use Laravel\Mcp\Facades\Mcp;
$result = Mcp::client('github')->getPrompt('issue_to_fix_workflow', [
'owner' => 'laravel',
'repo' => 'framework',
'title' => 'Fix typo in README',
'description' => 'The installation section has a typo.',
]);
$result->text(); // 消息的文本内容……
(string) $result; // 等同于调用 text()……
$result->messages; // 提示词返回的原始消息……
$result->description; // 提示词描述（如果有）……
```
### 资源
你可以使用 `resources` 方法获取 MCP 服务器开放的资源，该方法返回以 URI 为键的资源集合：
```php
use Laravel\Mcp\Facades\Mcp;
$resources = Mcp::client('github')->resources();
foreach ($resources as $resource) {
$resource->uri;
$resource->name;
$resource->title;
$resource->description;
$resource->mimeType;
$resource->size;
}
```
客户端会自动分页获取所有可用资源。你可以使用 `limit` 参数限制返回的资源数量：
```php
$resources = Mcp::client('github')->resources(limit: 10);
```
要读取资源，请使用 `readResource` 方法，并传入资源 URI。返回的 `ResourceReadResult` 实例提供对资源内容的访问：
```php
use Laravel\Mcp\Facades\Mcp;
$result = Mcp::client('github')->readResource('repo://laravel/framework/contents/README.md');
$result->content(); // 资源内容，按需解码 base64 Blob……
(string) $result; // 等同于调用 content()……
$result->mimeType(); // 资源的 MIME 类型（如果有）……
$result->contents; // 资源返回的原始内容……
```
## 测试服务器
你可以使用内置的 MCP Inspector 或编写单元测试来测试 MCP 服务器。
### MCP Inspector
交互式工具 [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) 用于测试和调试 MCP 服务器。你可以用它连接服务器、验证身份认证，并试用工具、资源和提示词。
你可以为任意已注册的服务器运行 Inspector：
```shell
# Web 服务器……
php artisan mcp:inspector mcp/weather
# 名为「weather」的本地服务器……
php artisan mcp:inspector weather
```
此命令会启动 MCP Inspector，并提供可复制到 MCP 客户端的客户端设置，以确保配置正确。如果 Web 服务器受身份认证中间件保护，请确保连接时包含所需的请求头，例如 `Authorization` Bearer 令牌。
### 单元测试
你可以为 MCP 服务器、工具、资源和提示词编写单元测试。
首先，创建一个新的测试用例，并在注册了目标基础组件的服务器上调用它。例如，要测试 `WeatherServer` 上的工具：
```php tab=Pest
test('tool', function () {
$response = WeatherServer::tool(CurrentWeatherTool::class, [
'location' => 'New York City',
'units' => 'fahrenheit',
]);
$response
->assertOk()
->assertSee('The current weather in New York City is 72°F and sunny.');
});
```
```php tab=PHPUnit
/**
* 测试工具。
*/
public function test_tool(): void
{
$response = WeatherServer::tool(CurrentWeatherTool::class, [
'location' => 'New York City',
'units' => 'fahrenheit',
]);
$response
->assertOk()
->assertSee('The current weather in New York City is 72°F and sunny.');
}
```
同样，你也可以测试提示词和资源：
```php
$response = WeatherServer::prompt(...);
$response = WeatherServer::resource(...);
```
你还可以在调用基础组件之前链式调用 `actingAs` 方法，以已认证用户的身份进行操作：
```php
$response = WeatherServer::actingAs($user)->tool(...);
```
收到响应后，你可以使用各种断言方法验证响应的内容和状态。
你可以使用 `assertOk` 方法断言响应成功。此方法会检查响应是否没有任何错误：
```php
$response->assertOk();
```
你可以使用 `assertSee` 方法断言响应包含指定文本：
```php
$response->assertSee('The current weather in New York City is 72°F and sunny.');
```
你可以使用 `assertHasErrors` 方法断言响应包含错误：
```php
$response->assertHasErrors();
$response->assertHasErrors([
'Something went wrong.',
]);
```
你可以使用 `assertHasNoErrors` 方法断言响应不包含错误：
```php
$response->assertHasNoErrors();
```
你可以使用 `assertName()`、`assertTitle()` 和 `assertDescription()` 方法断言响应包含指定的元数据：
```php
$response->assertName('current-weather');
$response->assertTitle('Current Weather Tool');
$response->assertDescription('Fetches the current weather forecast for a specified location.');
```
你可以使用 `assertSentNotification` 和 `assertNotificationCount` 方法断言通知已发送：
```php
$response->assertSentNotification('processing/progress', [
'step' => 1,
'total' => 5,
]);
$response->assertSentNotification('processing/progress', [
'step' => 2,
'total' => 5,
]);
$response->assertNotificationCount(5);
```
最后，如果你希望检查原始响应内容，可以使用 `dd` 或 `dump` 方法输出响应以进行调试：
```php
$response->dd();
$response->dump();
```