Laravel MCP Companion
by brianirish
mcp.md•84.6 kB
# Laravel MCP
- [Introduction](#introduction)
- [Installation](#installation)
- [Publishing Routes](#publishing-routes)
- [Creating Servers](#creating-servers)
- [Server Registration](#server-registration)
- [Web Servers](#web-servers)
- [Local Servers](#local-servers)
- [Tools](#tools)
- [Creating Tools](#creating-tools)
- [Tool Input Schemas](#tool-input-schemas)
- [Tool Output Schemas](#tool-output-schemas)
- [Validating Tool Arguments](#validating-tool-arguments)
- [Tool Dependency Injection](#tool-dependency-injection)
- [Tool Annotations](#tool-annotations)
- [Conditional Tool Registration](#conditional-tool-registration)
- [Tool Responses](#tool-responses)
- [Prompts](#prompts)
- [Creating Prompts](#creating-prompts)
- [Prompt Arguments](#prompt-arguments)
- [Validating Prompt Arguments](#validating-prompt-arguments)
- [Prompt Dependency Injection](#prompt-dependency-injection)
- [Conditional Prompt Registration](#conditional-prompt-registration)
- [Prompt Responses](#prompt-responses)
- [Resources](#resources)
- [Creating Resources](#creating-resources)
- [Resource Templates](#resource-templates)
- [Resource URI and MIME Type](#resource-uri-and-mime-type)
- [Resource Request](#resource-request)
- [Resource Dependency Injection](#resource-dependency-injection)
- [Resource Annotations](#resource-annotations)
- [Conditional Resource Registration](#conditional-resource-registration)
- [Resource Responses](#resource-responses)
- [Metadata](#metadata)
- [Authentication](#authentication)
- [OAuth 2.1](#oauth)
- [Sanctum](#sanctum)
- [Authorization](#authorization)
- [Testing Servers](#testing-servers)
- [MCP Inspector](#mcp-inspector)
- [Unit Tests](#unit-tests)
<a name="introduction"></a>
## Introduction
[Laravel MCP](https://github.com/laravel/mcp) provides a simple and elegant way for AI clients to interact with your Laravel application through the [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro). It offers an expressive, fluent interface for defining servers, tools, resources, and prompts that enable AI-powered interactions with your application.
<a name="installation"></a>
## Installation
To get started, install Laravel MCP into your project using the Composer package manager:
```shell
composer require laravel/mcp
```
<a name="publishing-routes"></a>
### Publishing Routes
After installing Laravel MCP, execute the `vendor:publish` Artisan command to publish the `routes/ai.php` file where you will define your MCP servers:
```shell
php artisan vendor:publish --tag=ai-routes
```
This command creates the `routes/ai.php` file in your application's `routes` directory, which you will use to register your MCP servers.
<a name="creating-servers"></a>
## Creating Servers
You can create an MCP server using the `make:mcp-server` Artisan command. Servers act as the central communication point that exposes MCP capabilities like tools, resources, and prompts to AI clients:
```shell
php artisan make:mcp-server WeatherServer
```
This command will create a new server class in the `app/Mcp/Servers` directory. The generated server class extends Laravel MCP's base `Laravel\Mcp\Server` class and provides properties for registering tools, resources, and prompts:
```php
<?php
namespace App\Mcp\Servers;
use Laravel\Mcp\Server;
class WeatherServer extends Server
{
/**
* The MCP server's name.
*/
protected string $name = 'Weather Server';
/**
* The MCP server's version.
*/
protected string $version = '1.0.0';
/**
* The MCP server's instructions for the LLM.
*/
protected string $instructions = 'This server provides weather information and forecasts.';
/**
* The tools registered with this MCP server.
*
* @var array<int, class-string<\Laravel\Mcp\Server\Tool>>
*/
protected array $tools = [
// GetCurrentWeatherTool::class,
];
/**
* The resources registered with this MCP server.
*
* @var array<int, class-string<\Laravel\Mcp\Server\Resource>>
*/
protected array $resources = [
// WeatherGuidelinesResource::class,
];
/**
* The prompts registered with this MCP server.
*
* @var array<int, class-string<\Laravel\Mcp\Server\Prompt>>
*/
protected array $prompts = [
// DescribeWeatherPrompt::class,
];
}
```
<a name="server-registration"></a>
### Server Registration
Once you've created a server, you must register it in your `routes/ai.php` file to make it accessible. Laravel MCP provides two methods for registering servers: `web` for HTTP-accessible servers and `local` for command-line servers.
<a name="web-servers"></a>
### Web Servers
Web servers are the most common types of servers and are accessible via HTTP POST requests, making them ideal for remote AI clients or web-based integrations. Register a web server using the `web` method:
```php
use App\Mcp\Servers\WeatherServer;
use Laravel\Mcp\Facades\Mcp;
Mcp::web('/mcp/weather', WeatherServer::class);
```
Just like normal routes, you may apply middleware to protect your web servers:
```php
Mcp::web('/mcp/weather', WeatherServer::class)
->middleware(['throttle:mcp']);
```
<a name="local-servers"></a>
### Local Servers
Local servers run as Artisan commands, perfect for building local AI assistant integrations like [Laravel Boost](/docs/{{version}}/installation#installing-laravel-boost). Register a local server using the `local` method:
```php
use App\Mcp\Servers\WeatherServer;
use Laravel\Mcp\Facades\Mcp;
Mcp::local('weather', WeatherServer::class);
```
Once registered, you should not typically need to manually run the `mcp:start` Artisan command yourself. Instead, configure your MCP client (AI agent) to start the server or use the [MCP Inspector](#mcp-inspector).
<a name="tools"></a>
## Tools
Tools enable your server to expose functionality that AI clients can call. They allow language models to perform actions, run code, or interact with external systems:
```php
<?php
namespace App\Mcp\Tools;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Tool;
class CurrentWeatherTool extends Tool
{
/**
* The tool's description.
*/
protected string $description = 'Fetches the current weather forecast for a specified location.';
/**
* Handle the tool request.
*/
public function handle(Request $request): Response
{
$location = $request->get('location');
// Get weather...
return Response::text('The weather is...');
}
/**
* Get the tool's input schema.
*
* @return array<string, \Illuminate\JsonSchema\Type\Type>
*/
public function schema(JsonSchema $schema): array
{
return [
'location' => $schema->string()
->description('The location to get the weather for.')
->required(),
];
}
}
```
<a name="creating-tools"></a>
### Creating Tools
To create a tool, run the `make:mcp-tool` Artisan command:
```shell
php artisan make:mcp-tool CurrentWeatherTool
```
After creating a tool, register it in your server's `$tools` property:
```php
<?php
namespace App\Mcp\Servers;
use App\Mcp\Tools\CurrentWeatherTool;
use Laravel\Mcp\Server;
class WeatherServer extends Server
{
/**
* The tools registered with this MCP server.
*
* @var array<int, class-string<\Laravel\Mcp\Server\Tool>>
*/
protected array $tools = [
CurrentWeatherTool::class,
];
}
```
<a name="tool-name-title-description"></a>
#### Tool Name, Title, and Description
By default, the tool's name and title are derived from the class name. For example, `CurrentWeatherTool` will have a name of `current-weather` and a title of `Current Weather Tool`. You may customize these values by defining the tool's `$name` and `$title` properties:
```php
class CurrentWeatherTool extends Tool
{
/**
* The tool's name.
*/
protected string $name = 'get-optimistic-weather';
/**
* The tool's title.
*/
protected string $title = 'Get Optimistic Weather Forecast';
// ...
}
```
Tool descriptions are not automatically generated. You should always provide a meaningful description by defining a `$description` property on your tool:
```php
class CurrentWeatherTool extends Tool
{
/**
* The tool's description.
*/
protected string $description = 'Fetches the current weather forecast for a specified location.';
//
}
```
> [!NOTE]
> The description is a critical part of the tool's metadata, as it helps AI models understand when and how to use the tool effectively.
<a name="tool-input-schemas"></a>
### Tool Input Schemas
Tools can define input schemas to specify what arguments they accept from AI clients. Use Laravel's `Illuminate\Contracts\JsonSchema\JsonSchema` builder to define your tool's input requirements:
```php
<?php
namespace App\Mcp\Tools;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Mcp\Server\Tool;
class CurrentWeatherTool extends Tool
{
/**
* Get the tool's input schema.
*
* @return array<string, \Illuminate\JsonSchema\Types\Type>
*/
public function schema(JsonSchema $schema): array
{
return [
'location' => $schema->string()
->description('The location to get the weather for.')
->required(),
'units' => $schema->string()
->enum(['celsius', 'fahrenheit'])
->description('The temperature units to use.')
->default('celsius'),
];
}
}
```
<a name="tool-output-schemas"></a>
### Tool Output Schemas
Tools can define [output schemas](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#output-schema) to specify the structure of their responses. This enables better integration with AI clients that need parseable tool results. Use the `outputSchema` method to define your tool's output structure:
```php
<?php
namespace App\Mcp\Tools;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Mcp\Server\Tool;
class CurrentWeatherTool extends Tool
{
/**
* Get the tool's output schema.
*
* @return array<string, \Illuminate\JsonSchema\Types\Type>
*/
public function outputSchema(JsonSchema $schema): array
{
return [
'temperature' => $schema->number()
->description('Temperature in Celsius')
->required(),
'conditions' => $schema->string()
->description('Weather conditions')
->required(),
'humidity' => $schema->integer()
->description('Humidity percentage')
->required(),
];
}
}
```
<a name="validating-tool-arguments"></a>
### Validating Tool Arguments
JSON Schema definitions provide a basic structure for tool arguments, but you may also want to enforce more complex validation rules.
Laravel MCP integrates seamlessly with Laravel's [validation features](/docs/{{version}}/validation). You may validate incoming tool arguments within your tool's `handle` method:
```php
<?php
namespace App\Mcp\Tools;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Tool;
class CurrentWeatherTool extends Tool
{
/**
* Handle the tool request.
*/
public function handle(Request $request): Response
{
$validated = $request->validate([
'location' => 'required|string|max:100',
'units' => 'in:celsius,fahrenheit',
]);
// Fetch weather data using the validated arguments...
}
}
```
On validation failure, AI clients will act based on the error messages you provide. As such, it is critical to provide clear and actionable error messages:
```php
$validated = $request->validate([
'location' => ['required','string','max:100'],
'units' => 'in:celsius,fahrenheit',
],[
'location.required' => 'You must specify a location to get the weather for. For example, "New York City" or "Tokyo".',
'units.in' => 'You must specify either "celsius" or "fahrenheit" for the units.',
]);
```
<a name="tool-dependency-injection"></a>
#### Tool Dependency Injection
The Laravel [service container](/docs/{{version}}/container) is used to resolve all tools. As a result, you are able to type-hint any dependencies your tool may need in its constructor. The declared dependencies will automatically be resolved and injected into the tool instance:
```php
<?php
namespace App\Mcp\Tools;
use App\Repositories\WeatherRepository;
use Laravel\Mcp\Server\Tool;
class CurrentWeatherTool extends Tool
{
/**
* Create a new tool instance.
*/
public function __construct(
protected WeatherRepository $weather,
) {}
// ...
}
```
In addition to constructor injection, you may also type-hint dependencies in your tool's `handle()` method. The service container will automatically resolve and inject the dependencies when the method is called:
```php
<?php
namespace App\Mcp\Tools;
use App\Repositories\WeatherRepository;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Tool;
class CurrentWeatherTool extends Tool
{
/**
* Handle the tool request.
*/
public function handle(Request $request, WeatherRepository $weather): Response
{
$location = $request->get('location');
$forecast = $weather->getForecastFor($location);
// ...
}
}
```
<a name="tool-annotations"></a>
### Tool Annotations
You may enhance your tools with [annotations](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations) to provide additional metadata to AI clients. These annotations help AI models understand the tool's behavior and capabilities. Annotations are added to tools via attributes:
```php
<?php
namespace App\Mcp\Tools;
use Laravel\Mcp\Server\Tools\Annotations\IsIdempotent;
use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;
use Laravel\Mcp\Server\Tool;
#[IsIdempotent]
#[IsReadOnly]
class CurrentWeatherTool extends Tool
{
//
}
```
Available annotations include:
| Annotation | Type | Description |
| ------------------ | ------- | ----------------------------------------------------------------------------------------------- |
| `#[IsReadOnly]` | boolean | Indicates the tool does not modify its environment. |
| `#[IsDestructive]` | boolean | Indicates the tool may perform destructive updates (only meaningful when not read-only). |
| `#[IsIdempotent]` | boolean | Indicates repeated calls with same arguments have no additional effect (when not read-only). |
| `#[IsOpenWorld]` | boolean | Indicates the tool may interact with external entities. |
Annotation values can be explicitly set using boolean arguments:
```php
use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;
use Laravel\Mcp\Server\Tools\Annotations\IsDestructive;
use Laravel\Mcp\Server\Tools\Annotations\IsOpenWorld;
use Laravel\Mcp\Server\Tools\Annotations\IsIdempotent;
use Laravel\Mcp\Server\Tool;
#[IsReadOnly(true)]
#[IsDestructive(false)]
#[IsOpenWorld(false)]
#[IsIdempotent(true)]
class CurrentWeatherTool extends Tool
{
//
}
```
<a name="conditional-tool-registration"></a>
### Conditional Tool Registration
You may conditionally register tools at runtime by implementing the `shouldRegister` method in your tool class. This method allows you to determine whether a tool should be available based on application state, configuration, or request parameters:
```php
<?php
namespace App\Mcp\Tools;
use Laravel\Mcp\Request;
use Laravel\Mcp\Server\Tool;
class CurrentWeatherTool extends Tool
{
/**
* Determine if the tool should be registered.
*/
public function shouldRegister(Request $request): bool
{
return $request?->user()?->subscribed() ?? false;
}
}
```
When a tool's `shouldRegister` method returns `false`, it will not appear in the list of available tools and cannot be invoked by AI clients.
<a name="tool-responses"></a>
### Tool Responses
Tools must return an instance of `Laravel\Mcp\Response`. The Response class provides several convenient methods for creating different types of responses:
For simple text responses, use the `text` method:
```php
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
/**
* Handle the tool request.
*/
public function handle(Request $request): Response
{
// ...
return Response::text('Weather Summary: Sunny, 72°F');
}
```
To indicate an error occurred during tool execution, use the `error` method:
```php
return Response::error('Unable to fetch weather data. Please try again.');
```
<a name="multiple-content-responses"></a>
#### Multiple Content Responses
Tools can return multiple pieces of content by returning an array of `Response` instances:
```php
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
/**
* Handle the tool request.
*
* @return array<int, \Laravel\Mcp\Response>
*/
public function handle(Request $request): array
{
// ...
return [
Response::text('Weather Summary: Sunny, 72°F'),
Response::text('**Detailed Forecast**\n- Morning: 65°F\n- Afternoon: 78°F\n- Evening: 70°F')
];
}
```
<a name="structured-responses"></a>
#### Structured Responses
Tools can return [structured content](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#structured-content) using the `structured` method. This provides parseable data for AI clients while maintaining backward compatibility with a JSON-encoded text representation:
```php
return Response::structured([
'temperature' => 22.5,
'conditions' => 'Partly cloudy',
'humidity' => 65,
]);
```
If you need to provide custom text alongside structured content, use the `withStructuredContent` method on the response factory:
```php
return Response::make(
Response::text('Weather is 22.5°C and sunny')
)->withStructuredContent([
'temperature' => 22.5,
'conditions' => 'Sunny',
]);
```
<a name="streaming-responses"></a>
#### Streaming Responses
For long-running operations or real-time data streaming, tools can return a [generator](https://www.php.net/manual/en/language.generators.overview.php) from their `handle` method. This enables sending intermediate updates to the client before the final response:
```php
<?php
namespace App\Mcp\Tools;
use Generator;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Tool;
class CurrentWeatherTool extends Tool
{
/**
* Handle the tool request.
*
* @return \Generator<int, \Laravel\Mcp\Response>
*/
public function handle(Request $request): Generator
{
$locations = $request->array('locations');
foreach ($locations as $index => $location) {
yield Response::notification('processing/progress', [
'current' => $index + 1,
'total' => count($locations),
'location' => $location,
]);
yield Response::text($this->forecastFor($location));
}
}
}
```
When using web-based servers, streaming responses automatically open an SSE (Server-Sent Events) stream, sending each yielded message as an event to the client.
<a name="prompts"></a>
## Prompts
[Prompts](https://modelcontextprotocol.io/specification/2025-06-18/server/prompts) enable your server to share reusable prompt templates that AI clients can use to interact with language models. They provide a standardized way to structure common queries and interactions.
<a name="creating-prompts"></a>
### Creating Prompts
To create a prompt, run the `make:mcp-prompt` Artisan command:
```shell
php artisan make:mcp-prompt DescribeWeatherPrompt
```
After creating a prompt, register it in your server's `$prompts` property:
```php
<?php
namespace App\Mcp\Servers;
use App\Mcp\Prompts\DescribeWeatherPrompt;
use Laravel\Mcp\Server;
class WeatherServer extends Server
{
/**
* The prompts registered with this MCP server.
*
* @var array<int, class-string<\Laravel\Mcp\Server\Prompt>>
*/
protected array $prompts = [
DescribeWeatherPrompt::class,
];
}
```
<a name="prompt-name-title-and-description"></a>
#### Prompt Name, Title, and Description
By default, the prompt's name and title are derived from the class name. For example, `DescribeWeatherPrompt` will have a name of `describe-weather` and a title of `Describe Weather Prompt`. You may customize these values by defining `$name` and `$title` properties on your prompt:
```php
class DescribeWeatherPrompt extends Prompt
{
/**
* The prompt's name.
*/
protected string $name = 'weather-assistant';
/**
* The prompt's title.
*/
protected string $title = 'Weather Assistant Prompt';
// ...
}
```
Prompt descriptions are not automatically generated. You should always provide a meaningful description by defining a `$description` property on your prompts:
```php
class DescribeWeatherPrompt extends Prompt
{
/**
* The prompt's description.
*/
protected string $description = 'Generates a natural-language explanation of the weather for a given location.';
//
}
```
> [!NOTE]
> The description is a critical part of the prompt's metadata, as it helps AI models understand when and how to get the best use out of the prompt.
<a name="prompt-arguments"></a>
### Prompt Arguments
Prompts can define arguments that allow AI clients to customize the prompt template with specific values. Use the `arguments` method to define what arguments your prompt accepts:
```php
<?php
namespace App\Mcp\Prompts;
use Laravel\Mcp\Server\Prompt;
use Laravel\Mcp\Server\Prompts\Argument;
class DescribeWeatherPrompt extends Prompt
{
/**
* Get the prompt's arguments.
*
* @return array<int, \Laravel\Mcp\Server\Prompts\Argument>
*/
public function arguments(): array
{
return [
new Argument(
name: 'tone',
description: 'The tone to use in the weather description (e.g., formal, casual, humorous).',
required: true,
),
];
}
}
```
<a name="validating-prompt-arguments"></a>
### Validating Prompt Arguments
Prompt arguments are automatically validated based on their definition, but you may also want to enforce more complex validation rules.
Laravel MCP integrates seamlessly with Laravel's [validation features](/docs/{{version}}/validation). You may validate incoming prompt arguments within your prompt's `handle` method:
```php
<?php
namespace App\Mcp\Prompts;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Prompt;
class DescribeWeatherPrompt extends Prompt
{
/**
* Handle the prompt request.
*/
public function handle(Request $request): Response
{
$validated = $request->validate([
'tone' => 'required|string|max:50',
]);
$tone = $validated['tone'];
// Generate the prompt response using the given tone...
}
}
```
On validation failure, AI clients will act based on the error messages you provide. As such, it is critical to provide clear and actionable error messages:
```php
$validated = $request->validate([
'tone' => ['required','string','max:50'],
],[
'tone.*' => 'You must specify a tone for the weather description. Examples include "formal", "casual", or "humorous".',
]);
```
<a name="prompt-dependency-injection"></a>
### Prompt Dependency Injection
The Laravel [service container](/docs/{{version}}/container) is used to resolve all prompts. As a result, you are able to type-hint any dependencies your prompt may need in its constructor. The declared dependencies will automatically be resolved and injected into the prompt instance:
```php
<?php
namespace App\Mcp\Prompts;
use App\Repositories\WeatherRepository;
use Laravel\Mcp\Server\Prompt;
class DescribeWeatherPrompt extends Prompt
{
/**
* Create a new prompt instance.
*/
public function __construct(
protected WeatherRepository $weather,
) {}
//
}
```
In addition to constructor injection, you may also type-hint dependencies in your prompt's `handle` method. The service container will automatically resolve and inject the dependencies when the method is called:
```php
<?php
namespace App\Mcp\Prompts;
use App\Repositories\WeatherRepository;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Prompt;
class DescribeWeatherPrompt extends Prompt
{
/**
* Handle the prompt request.
*/
public function handle(Request $request, WeatherRepository $weather): Response
{
$isAvailable = $weather->isServiceAvailable();
// ...
}
}
```
<a name="conditional-prompt-registration"></a>
### Conditional Prompt Registration
You may conditionally register prompts at runtime by implementing the `shouldRegister` method in your prompt class. This method allows you to determine whether a prompt should be available based on application state, configuration, or request parameters:
```php
<?php
namespace App\Mcp\Prompts;
use Laravel\Mcp\Request;
use Laravel\Mcp\Server\Prompt;
class CurrentWeatherPrompt extends Prompt
{
/**
* Determine if the prompt should be registered.
*/
public function shouldRegister(Request $request): bool
{
return $request?->user()?->subscribed() ?? false;
}
}
```
When a prompt's `shouldRegister` method returns `false`, it will not appear in the list of available prompts and cannot be invoked by AI clients.
<a name="prompt-responses"></a>
### Prompt Responses
Prompts may return a single `Laravel\Mcp\Response` or an iterable of `Laravel\Mcp\Response` instances. These responses encapsulate the content that will be sent to the AI client:
```php
<?php
namespace App\Mcp\Prompts;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Prompt;
class DescribeWeatherPrompt extends Prompt
{
/**
* Handle the prompt request.
*
* @return array<int, \Laravel\Mcp\Response>
*/
public function handle(Request $request): array
{
$tone = $request->string('tone');
$systemMessage = "You are a helpful weather assistant. Please provide a weather description in a {$tone} tone.";
$userMessage = "What is the current weather like in New York City?";
return [
Response::text($systemMessage)->asAssistant(),
Response::text($userMessage),
];
}
}
```
You can use the `asAssistant()` method to indicate that a response message should be treated as coming from the AI assistant, while regular messages are treated as user input.
<a name="resources"></a>
## Resources
[Resources](https://modelcontextprotocol.io/specification/2025-06-18/server/resources) enable your server to expose data and content that AI clients can read and use as context when interacting with language models. They provide a way to share static or dynamic information like documentation, configuration, or any data that helps inform AI responses.
<a name="creating-resources"></a>
## Creating Resources
To create a resource, run the `make:mcp-resource` Artisan command:
```shell
php artisan make:mcp-resource WeatherGuidelinesResource
```
After creating a resource, register it in your server's `$resources` property:
```php
<?php
namespace App\Mcp\Servers;
use App\Mcp\Resources\WeatherGuidelinesResource;
use Laravel\Mcp\Server;
class WeatherServer extends Server
{
/**
* The resources registered with this MCP server.
*
* @var array<int, class-string<\Laravel\Mcp\Server\Resource>>
*/
protected array $resources = [
WeatherGuidelinesResource::class,
];
}
```
<a name="resource-name-title-and-description"></a>
#### Resource Name, Title, and Description
By default, the resource's name and title are derived from the class name. For example, `WeatherGuidelinesResource` will have a name of `weather-guidelines` and a title of `Weather Guidelines Resource`. You may customize these values by defining the `$name` and `$title` properties on your resource:
```php
class WeatherGuidelinesResource extends Resource
{
/**
* The resource's name.
*/
protected string $name = 'weather-api-docs';
/**
* The resource's title.
*/
protected string $title = 'Weather API Documentation';
// ...
}
```
Resource descriptions are not automatically generated. You should always provide a meaningful description by defining the `$description` property on your resource:
```php
class WeatherGuidelinesResource extends Resource
{
/**
* The resource's description.
*/
protected string $description = 'Comprehensive guidelines for using the Weather API.';
//
}
```
> [!NOTE]
> The description is a critical part of the resource's metadata, as it helps AI models understand when and how to use the resource effectively.
<a name="resource-templates"></a>
### Resource Templates
[Resource templates](https://modelcontextprotocol.io/specification/2025-06-18/server/resources#resource-templates) enable your server to expose dynamic resources that match URI patterns with variables. Instead of defining a static URI for each resource, you can create a single resource that handles multiple URIs based on a template pattern.
<a name="creating-resource-templates"></a>
#### Creating Resource Templates
To create a resource template, implement the `HasUriTemplate` interface on your resource class and define a `uriTemplate` method that returns a `UriTemplate` instance:
```php
<?php
namespace App\Mcp\Resources;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Contracts\HasUriTemplate;
use Laravel\Mcp\Server\Resource;
use Laravel\Mcp\Support\UriTemplate;
class UserFileResource extends Resource implements HasUriTemplate
{
/**
* The resource's description.
*/
protected string $description = 'Access user files by ID';
/**
* The resource's MIME type.
*/
protected string $mimeType = 'text/plain';
/**
* Get the URI template for this resource.
*/
public function uriTemplate(): UriTemplate
{
return new UriTemplate('file://users/{userId}/files/{fileId}');
}
/**
* Handle the resource request.
*/
public function handle(Request $request): Response
{
$userId = $request->get('userId');
$fileId = $request->get('fileId');
// Fetch and return the file content...
return Response::text($content);
}
}
```
When a resource implements the `HasUriTemplate` interface, it will be registered as a resource template rather than a static resource. AI clients can then request resources using URIs that match the template pattern, and the variables from the URI will be automatically extracted and made available in your resource's `handle` method.
<a name="uri-template-syntax"></a>
#### URI Template Syntax
URI templates use placeholders enclosed in curly braces to define variable segments in the URI:
```php
new UriTemplate('file://users/{userId}');
new UriTemplate('file://users/{userId}/files/{fileId}');
new UriTemplate('https://api.example.com/{version}/{resource}/{id}');
```
<a name="accessing-template-variables"></a>
#### Accessing Template Variables
When a URI matches your resource template, the extracted variables are automatically merged into the request and can be accessed using the `get` method:
```php
<?php
namespace App\Mcp\Resources;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Contracts\HasUriTemplate;
use Laravel\Mcp\Server\Resource;
use Laravel\Mcp\Support\UriTemplate;
class UserProfileResource extends Resource implements HasUriTemplate
{
public function uriTemplate(): UriTemplate
{
return new UriTemplate('file://users/{userId}/profile');
}
public function handle(Request $request): Response
{
// Access the extracted variable
$userId = $request->get('userId');
// Access the full URI if needed
$uri = $request->uri();
// Fetch user profile...
return Response::text("Profile for user {$userId}");
}
}
```
The `Request` object provides both the extracted variables and the original URI that was requested, giving you full context for processing the resource request.
<a name="resource-uri-and-mime-type"></a>
### Resource URI and MIME Type
Each resource is identified by a unique URI and has an associated MIME type that helps AI clients understand the resource's format.
By default, the resource's URI is generated based on the resource's name, so `WeatherGuidelinesResource` will have a URI of `weather://resources/weather-guidelines`. The default MIME type is `text/plain`.
You may customize these values by defining the `$uri` and `$mimeType` properties on your resource:
```php
<?php
namespace App\Mcp\Resources;
use Laravel\Mcp\Server\Resource;
class WeatherGuidelinesResource extends Resource
{
/**
* The resource's URI.
*/
protected string $uri = 'weather://resources/guidelines';
/**
* The resource's MIME type.
*/
protected string $mimeType = 'application/pdf';
}
```
The URI and MIME type help AI clients determine how to process and interpret the resource content appropriately.
<a name="resource-request"></a>
### Resource Request
Unlike tools and prompts, resources can not define input schemas or arguments. However, you can still interact with request object within your resource's `handle` method:
```php
<?php
namespace App\Mcp\Resources;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Resource;
class WeatherGuidelinesResource extends Resource
{
/**
* Handle the resource request.
*/
public function handle(Request $request): Response
{
// ...
}
}
```
<a name="resource-dependency-injection"></a>
### Resource Dependency Injection
The Laravel [service container](/docs/{{version}}/container) is used to resolve all resources. As a result, you are able to type-hint any dependencies your resource may need in its constructor. The declared dependencies will automatically be resolved and injected into the resource instance:
```php
<?php
namespace App\Mcp\Resources;
use App\Repositories\WeatherRepository;
use Laravel\Mcp\Server\Resource;
class WeatherGuidelinesResource extends Resource
{
/**
* Create a new resource instance.
*/
public function __construct(
protected WeatherRepository $weather,
) {}
// ...
}
```
In addition to constructor injection, you may also type-hint dependencies in your resource's `handle` method. The service container will automatically resolve and inject the dependencies when the method is called:
```php
<?php
namespace App\Mcp\Resources;
use App\Repositories\WeatherRepository;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Resource;
class WeatherGuidelinesResource extends Resource
{
/**
* Handle the resource request.
*/
public function handle(WeatherRepository $weather): Response
{
$guidelines = $weather->guidelines();
return Response::text($guidelines);
}
}
```
<a name="resource-annotations"></a>
### Resource Annotations
You may enhance your resources with [annotations](https://modelcontextprotocol.io/specification/2025-06-18/schema#resourceannotations) to provide additional metadata to AI clients. Annotations are added to resources via attributes:
```php
<?php
namespace App\Mcp\Resources;
use Laravel\Mcp\Enums\Role;
use Laravel\Mcp\Server\Annotations\Audience;
use Laravel\Mcp\Server\Annotations\LastModified;
use Laravel\Mcp\Server\Annotations\Priority;
use Laravel\Mcp\Server\Resource;
#[Audience(Role::User)]
#[LastModified('2025-01-12T15:00:58Z')]
#[Priority(0.9)]
class UserDashboardResource extends Resource
{
//
}
```
Available annotations include:
| Annotation | Type | Description |
| ---------------- | -------------- | ----------------------------------------------------------------------------------------------- |
| `#[Audience]` | Role or array | Specifies the intended audience (`Role::User`, `Role::Assistant`, or both). |
| `#[Priority]` | float | A numerical score between 0.0 and 1.0 indicating resource importance. |
| `#[LastModified]`| string | An ISO 8601 timestamp showing when the resource was last updated. |
<a name="conditional-resource-registration"></a>
### Conditional Resource Registration
You may conditionally register resources at runtime by implementing the `shouldRegister` method in your resource class. This method allows you to determine whether a resource should be available based on application state, configuration, or request parameters:
```php
<?php
namespace App\Mcp\Resources;
use Laravel\Mcp\Request;
use Laravel\Mcp\Server\Resource;
class WeatherGuidelinesResource extends Resource
{
/**
* Determine if the resource should be registered.
*/
public function shouldRegister(Request $request): bool
{
return $request?->user()?->subscribed() ?? false;
}
}
```
When a resource's `shouldRegister` method returns `false`, it will not appear in the list of available resources and cannot be accessed by AI clients.
<a name="resource-responses"></a>
### Resource Responses
Resources must return an instance of `Laravel\Mcp\Response`. The Response class provides several convenient methods for creating different types of responses:
For simple text content, use the `text` method:
```php
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
/**
* Handle the resource request.
*/
public function handle(Request $request): Response
{
// ...
return Response::text($weatherData);
}
```
<a name="resource-blob-responses"></a>
#### Blob Responses
To return blob content, use the `blob` method, providing the blob content:
```php
return Response::blob(file_get_contents(storage_path('weather/radar.png')));
```
When returning blob content, the MIME type will be determined by the value of the `$mimeType` property on the resource class:
```php
<?php
namespace App\Mcp\Resources;
use Laravel\Mcp\Server\Resource;
class WeatherGuidelinesResource extends Resource
{
/**
* The resource's MIME type.
*/
protected string $mimeType = 'image/png';
//
}
```
<a name="resource-error-responses"></a>
#### Error Responses
To indicate an error occurred during resource retrieval, use the `error()` method:
```php
return Response::error('Unable to fetch weather data for the specified location.');
```
<a name="metadata"></a>
## Metadata
Laravel MCP also supports the `_meta` field as defined in the [MCP specification](https://modelcontextprotocol.io/specification/2025-06-18/basic#meta), which is required by certain MCP clients or integrations. Metadata can be applied to all MCP primitives, including tools, resources, and prompts, as well as their responses.
You can attach metadata to individual response content using the `withMeta` method:
```php
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
/**
* Handle the tool request.
*/
public function handle(Request $request): Response
{
return Response::text('The weather is sunny.')
->withMeta(['source' => 'weather-api', 'cached' => true]);
}
```
For result-level metadata that applies to the entire response envelope, wrap your responses with `Response::make` and call `withMeta` on the returned response factory instance:
```php
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\ResponseFactory;
/**
* Handle the tool request.
*/
public function handle(Request $request): ResponseFactory
{
return Response::make(
Response::text('The weather is sunny.')
)->withMeta(['request_id' => '12345']);
}
```
To attach metadata to a tool, resource, or prompt itself, define a `$meta` property on the class:
```php
use Laravel\Mcp\Server\Tool;
class CurrentWeatherTool extends Tool
{
protected string $description = 'Fetches the current weather forecast.';
protected ?array $meta = [
'version' => '2.0',
'author' => 'Weather Team',
];
// ...
}
```
<a name="authentication"></a>
## Authentication
Just like routes, you can authenticate web MCP servers with middleware. Adding authentication to your MCP server will require a user to authenticate before using any capability of the server.
There are two ways to authenticate access to your MCP server: simple, token based authentication via [Laravel Sanctum](/docs/{{version}}/sanctum) or any token which is passed via the `Authorization` HTTP header. Or, you may authenticate via OAuth using [Laravel Passport](/docs/{{version}}/passport).
<a name="oauth"></a>
### OAuth 2.1
The most robust way to protect your web-based MCP servers is with OAuth using [Laravel Passport](/docs/{{version}}/passport).
When authenticating your MCP server via OAuth, invoke the `Mcp::oauthRoutes` method in your `routes/ai.php` file to register the required OAuth2 discovery and client registration routes. Then, apply Passport's `auth:api` middleware to your `Mcp::web` route in your `routes/ai.php` file:
```php
use App\Mcp\Servers\WeatherExample;
use Laravel\Mcp\Facades\Mcp;
Mcp::oauthRoutes();
Mcp::web('/mcp/weather', WeatherExample::class)
->middleware('auth:api');
```
#### New Passport Installation
If your application is not already using Laravel Passport, follow Passport's [installation and deployment guide](/docs/{{version}}/passport#installation) to add Passport to your application. You should have an `OAuthenticatable` model, new authentication guard, and passport keys before moving on.
Next, you should publish Laravel MCP's provided Passport authorization view:
```shell
php artisan vendor:publish --tag=mcp-views
```
Then, instruct Passport to use this view using the `Passport::authorizationView` method. Typically, this method should be invoked in the `boot` method of your application's `AppServiceProvider`:
```php
use Laravel\Passport\Passport;
/**
* Bootstrap any application services.
*/
public function boot(): void
{
Passport::authorizationView(function ($parameters) {
return view('mcp.authorize', $parameters);
});
}
```
This view will be displayed to the end-user during authentication to reject or approve the AI agent's authentication attempt.
> [!NOTE]
> In this scenario, we're simply using OAuth as a translation layer to the underlying authenticatable model. We are ignoring many aspects of OAuth, such as scopes.
#### Using an Existing Passport Installation
If your application is already using Laravel Passport, Laravel MCP should work seamlessly within your existing Passport installation, but custom scopes aren't currently supported as OAuth is primarily used as a translation layer to the underlying authenticatable model.
Laravel MCP, via the `Mcp::oauthRoutes` method discussed above, adds, advertises, and uses a single `mcp:use` scope.
#### Passport vs. Sanctum
OAuth2.1 is the documented authentication mechanism in the Model Context Protocol specification, and is the most widely supported among MCP clients. For that reason, we recommend using Passport when possible.
If your application is already using [Sanctum](/docs/{{version}}/sanctum) then adding Passport may be cumbersome. In this instance, we recommend using Sanctum without Passport until you have a clear, necessary requirement to use an MCP client that only supports OAuth.
<a name="sanctum"></a>
### Sanctum
If you would like to protect your MCP server using [Sanctum](/docs/{{version}}/sanctum), simply add Sanctum's authentication middleware to your server in your `routes/ai.php` file. Then, ensure your MCP clients provide a `Authorization: Bearer <token>` header to ensure successful authentication:
```php
use App\Mcp\Servers\WeatherExample;
use Laravel\Mcp\Facades\Mcp;
Mcp::web('/mcp/demo', WeatherExample::class)
->middleware('auth:sanctum');
```
<a name="custom-mcp-authentication"></a>
#### Custom MCP Authentication
If your application issues its own custom API tokens, you may authenticate your MCP server by assigning any middleware you wish to your `Mcp::web` routes. Your custom middleware can inspect the `Authorization` header manually to authenticate the incoming MCP request.
<a name="authorization"></a>
## Authorization
You may access the currently authenticated user via the `$request->user()` method, allowing you to perform [authorization checks](/docs/{{version}}/authorization) within your MCP tools and resources:
```php
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
/**
* Handle the tool request.
*/
public function handle(Request $request): Response
{
if (! $request->user()->can('read-weather')) {
return Response::error('Permission denied.');
}
// ...
}
```
<a name="testing-servers"></a>
## Testing Servers
You may test your MCP servers using the built-in MCP Inspector or by writing unit tests.
<a name="mcp-inspector"></a>
### MCP Inspector
The [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) is an interactive tool for testing and debugging your MCP servers. Use it to connect to your server, verify authentication, and try out tools, resources, and prompts.
You may run the inspector for any registered server:
```shell
# Web server...
php artisan mcp:inspector mcp/weather
# Local server named "weather"...
php artisan mcp:inspector weather
```
This command launches the MCP Inspector and provides the client settings that you may copy into your MCP client to ensure everything is configured correctly. If your web server is protected by an authentication middleware, make sure to include the required headers, such as an `Authorization` bearer token, when connecting.
<a name="unit-tests"></a>
### Unit Tests
You may write unit tests for your MCP servers, tools, resources, and prompts.
To get started, create a new test case and invoke the desired primitive on the server that registers it. For example, to test a tool on the `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
/**
* Test a tool.
*/
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.');
}
```
Similarly, you may test prompts and resources:
```php
$response = WeatherServer::prompt(...);
$response = WeatherServer::resource(...);
```
You may also act as an authenticated user by chaining the `actingAs` method before invoking the primitive:
```php
$response = WeatherServer::actingAs($user)->tool(...);
```
Once you receive the response, you may use various assertion methods to verify the content and status of the response.
You may assert that a response is successful using the `assertOk` method. This checks that the response does not have any errors:
```php
$response->assertOk();
```
You may assert that a response contains specific text using the `assertSee` method:
```php
$response->assertSee('The current weather in New York City is 72°F and sunny.');
```
You may assert that a response contains an error using the `assertHasErrors` method:
```php
$response->assertHasErrors();
$response->assertHasErrors([
'Something went wrong.',
]);
```
You may assert that a response does not contain an error using the `assertHasNoErrors` method:
```php
$response->assertHasNoErrors();
```
You may assert that a response contains specific metadata using the `assertName()`, `assertTitle()`, and `assertDescription()` methods:
```php
$response->assertName('current-weather');
$response->assertTitle('Current Weather Tool');
$response->assertDescription('Fetches the current weather forecast for a specified location.');
```
You may assert that notifications were sent using the `assertSentNotification` and `assertNotificationCount` methods:
```php
$response->assertSentNotification('processing/progress', [
'step' => 1,
'total' => 5,
]);
$response->assertSentNotification('processing/progress', [
'step' => 2,
'total' => 5,
]);
$response->assertNotificationCount(5);
```
Finally, if you wish to inspect the raw response content, you may use the `dd` or `dump` methods to output the response for debugging purposes:
```php
$response->dd();
$response->dump();
```
Latest Blog Posts
- Federated Learning with MCP: Building Privacy-Preserving Agents Across Distributed EdgesBy Om-Shree-0709 on .SecuremcpLearning
- MCP Moves to the Linux Foundation: Neutral Stewardship for Agentic InfrastructureBy Om-Shree-0709 on .mcpanthropicLinux Foundation
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/brianirish/laravel-mcp-companion'
If you have feedback or need assistance with the MCP directory API, please join our Discord server