Laravel MCP - Knowledge of Laravel

What is MCP?

The Model Context Protocol (MCP) is a specification for AI clients (such as Claude, Cursor, and GitHub Copilot) to communicate with applications through a standardized protocol. By implementing an MCP server, you can allow AI agents to access data in your Laravel application or perform actions on your behalf.

Laravel MCP is an official package added in Laravel 13. Distributed as laravel/mcp, it provides the features you need to build an MCP server.

An MCP server can provide three main capabilities.

Capability	Description
Tools	Functions AI clients can invoke — for search, updates, external API integration, and so on.
Resources	Data or contextual information AI clients can load.
Prompts	Reusable prompt templates.

Installation

Install the package via Composer.

composer require laravel/mcp

After installation, run the vendor:publish Artisan command to generate the routes/ai.php file.

php artisan vendor:publish --tag=ai-routes

This command creates the routes/ai.php file. This is where you register your MCP servers.

Creating a server

Generate a server class with the make:mcp-server Artisan command.

php artisan make:mcp-server WeatherServer

The server class is created in the app/Mcp/Servers directory.

<?php

namespace App\Mcp\Servers;

use Laravel\Mcp\Server\Attributes\Instructions;
use Laravel\Mcp\Server\Attributes\Name;
use Laravel\Mcp\Server\Attributes\Version;
use Laravel\Mcp\Server;

#[Name('Weather Server')]
#[Version('1.0.0')]
#[Instructions('This server provides weather information and forecasts.')]
class WeatherServer extends Server
{
    protected array $tools = [
        // GetCurrentWeatherTool::class,
    ];

    protected array $resources = [
        // WeatherGuidelinesResource::class,
    ];

    protected array $prompts = [
        // DescribeWeatherPrompt::class,
    ];
}

Registering a server

Once you’ve created a server, register it in routes/ai.php. There are two registration types: web servers and local servers.

Web servers

A web server is accessed via HTTP POST requests. This is ideal for remote AI clients or web-based integrations.

use App\Mcp\Servers\WeatherServer;
use Laravel\Mcp\Facades\Mcp;

Mcp::web('/mcp/weather', WeatherServer::class);

You can apply middleware just like a regular route.

Mcp::web('/mcp/weather', WeatherServer::class)
    ->middleware(['throttle:mcp']);

Local servers

A local server runs as an Artisan command. Use it to integrate with local AI clients like Claude Desktop.

use App\Mcp\Servers\WeatherServer;
use Laravel\Mcp\Facades\Mcp;

Mcp::local('weather', WeatherServer::class);

Local servers are typically started automatically by the MCP client. You don’t need to run the mcp:start Artisan command manually.

Tools

A tool is a function the AI client can call. You can implement data retrieval, integrations with external APIs, database operations, and more.

Creating a tool

Generate a tool class with the make:mcp-tool Artisan command.

php artisan make:mcp-tool CurrentWeatherTool

use App\Mcp\Tools\CurrentWeatherTool;
use Laravel\Mcp\Server;

class WeatherServer extends Server
{
    protected array $tools = [
        CurrentWeatherTool::class,
    ];
}

Here’s a basic tool implementation.

<?php

namespace App\Mcp\Tools;

use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\Tool;

#[Description('Fetches the current weather forecast for a specified location.')]
class CurrentWeatherTool extends Tool
{
    public function handle(Request $request): Response
    {
        $location = $request->get('location');

        // Fetch weather data...

        return Response::text('The weather is sunny, 22°C.');
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'location' => $schema->string()
                ->description('The location to get the weather for.')
                ->required(),
        ];
    }
}

Tool name and description

Default names and titles are generated from the class name. CurrentWeatherTool becomes name current-weather and title Current Weather Tool. You can customize both with the Name and Title attributes.

use Laravel\Mcp\Server\Attributes\Name;
use Laravel\Mcp\Server\Attributes\Title;

#[Name('get-optimistic-weather')]
#[Title('Get Optimistic Weather Forecast')]
class CurrentWeatherTool extends Tool
{
    // ...
}

The tool’s description (Description) is not generated automatically. It’s essential for the AI model to understand how to use the tool, so always provide a meaningful description.

Input schema

Use the schema method to define the input parameter schema. You can specify types and constraints using Laravel’s JSON schema builder.

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'),
    ];
}

Output schema

The outputSchema method lets you define the structure of the response. This makes it easier for AI clients to parse the response.

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(),
    ];
}

Validation

You can use Laravel’s standard validation features inside the handle method.

public function handle(Request $request): Response
{
    $validated = $request->validate([
        'location' => 'required|string|max:100',
        'units' => 'in:celsius,fahrenheit',
    ], [
        'location.required' => 'You must specify a location. For example, "New York City" or "Tokyo".',
        'units.in' => 'You must specify either "celsius" or "fahrenheit" for the units.',
    ]);

    // Use the validated data...
}

When validation fails, the AI client uses the error message to retry. Provide specific, actionable error messages.

Dependency injection

Tools are resolved through Laravel’s service container, so you can type-hint dependencies in the constructor or handle method.

<?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
{
    public function __construct(
        protected WeatherRepository $weather,
    ) {}

    public function handle(Request $request, WeatherRepository $weather): Response
    {
        $location = $request->get('location');
        $forecast = $weather->getForecastFor($location);

        return Response::text("Forecast: {$forecast}");
    }
}

Annotations

You can add annotations to tools to provide additional information about the tool’s behavior to the AI client.

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
{
    // ...
}

The available annotations are:

Annotation	Description
`#[IsReadOnly]`	Indicates the tool does not modify its environment.
`#[IsDestructive]`	Indicates the tool may perform destructive updates.
`#[IsIdempotent]`	Indicates repeated calls with the same arguments have no side effects.
`#[IsOpenWorld]`	Indicates the tool may interact with external entities.

Conditional registration

Implement shouldRegister to conditionally register the tool at runtime.

public function shouldRegister(Request $request): bool
{
    return $request?->user()?->subscribed() ?? false;
}

Returning false hides the tool from the AI client.

Responses

A tool must return a Laravel\Mcp\Response instance.

Text response

return Response::text('Weather Summary: Sunny, 22°C');

Error response

return Response::error('Unable to fetch weather data. Please try again.');

Image and audio responses

return Response::image(file_get_contents(storage_path('weather/radar.png')), 'image/png');

return Response::audio(file_get_contents(storage_path('weather/alert.mp3')), 'audio/mp3');

// Load directly from storage (MIME type auto-detected)
return Response::fromStorage('weather/radar.png');

Multi-content response

public function handle(Request $request): array
{
    return [
        Response::text('Weather Summary: Sunny, 22°C'),
        Response::text("**Detailed Forecast**\n- Morning: 18°C\n- Afternoon: 25°C"),
    ];
}

Structured response

Returns structured data that’s easy for AI clients to parse.

return Response::structured([
    'temperature' => 22.5,
    'conditions' => 'Partly cloudy',
    'humidity' => 65,
]);

Streaming response

Sends progress updates in real time during long-running operations.

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));
    }
}

Prompts

A prompt is a reusable prompt template. You can use them to provide standardized boilerplate queries that AI clients use to interact with language models.

Creating a prompt

php artisan make:mcp-prompt DescribeWeatherPrompt

use App\Mcp\Prompts\DescribeWeatherPrompt;

class WeatherServer extends Server
{
    protected array $prompts = [
        DescribeWeatherPrompt::class,
    ];
}

Prompt arguments

Use the arguments method to define the prompt’s parameters.

<?php

namespace App\Mcp\Prompts;

use Laravel\Mcp\Server\Prompt;
use Laravel\Mcp\Server\Prompts\Argument;

class DescribeWeatherPrompt extends Prompt
{
    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,
            ),
        ];
    }
}

Validation

Prompt arguments are automatically validated based on their definitions, but you can also apply more complex validation rules. Laravel MCP integrates seamlessly with Laravel’s validation features. You can validate arguments inside a prompt’s handle method.

<?php

namespace App\Mcp\Prompts;

use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Prompt;

class DescribeWeatherPrompt extends Prompt
{
    public function handle(Request $request): Response
    {
        $validated = $request->validate([
            'tone' => 'required|string|max:50',
        ]);

        $tone = $validated['tone'];

        // Generate the prompt using the given tone...
    }
}

When validation fails, the AI client uses the error message to retry. Provide specific, actionable messages.

$validated = $request->validate([
    'tone' => ['required', 'string', 'max:50'],
], [
    'tone.*' => 'Please specify a tone. For example, "formal", "casual", or "humorous".',
]);

Dependency injection

Prompts are resolved through Laravel’s service container, so you can type-hint dependencies in the constructor or handle method.

<?php

namespace App\Mcp\Prompts;

use App\Repositories\WeatherRepository;
use Laravel\Mcp\Server\Prompt;

class DescribeWeatherPrompt extends Prompt
{
    public function __construct(
        protected WeatherRepository $weather,
    ) {}
}

You can also type-hint on handle, and the service container will resolve and inject dependencies automatically.

public function handle(Request $request, WeatherRepository $weather): Response
{
    $isAvailable = $weather->isServiceAvailable();

    // ...
}

Conditional registration

Implement shouldRegister to conditionally register a prompt at runtime.

<?php

namespace App\Mcp\Prompts;

use Laravel\Mcp\Request;
use Laravel\Mcp\Server\Prompt;

class CurrentWeatherPrompt extends Prompt
{
    public function shouldRegister(Request $request): bool
    {
        return $request?->user()?->subscribed() ?? false;
    }
}

Returning false hides the prompt from the AI client and prevents it from being called.

Prompt responses

A prompt’s handle method can return user messages and assistant messages. Use asAssistant() to mark a message as coming from the assistant.

<?php

namespace App\Mcp\Prompts;

use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Prompt;

class DescribeWeatherPrompt extends Prompt
{
    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 Tokyo?';

        return [
            Response::text($systemMessage)->asAssistant(),
            Response::text($userMessage),
        ];
    }
}

Resources

Resources are data or information that AI clients can load as context. You can provide documents, configuration information, dynamic data, and any other information that improves the quality of the AI’s response.

Creating a resource

php artisan make:mcp-resource WeatherGuidelinesResource

use App\Mcp\Resources\WeatherGuidelinesResource;

class WeatherServer extends Server
{
    protected array $resources = [
        WeatherGuidelinesResource::class,
    ];
}

<?php

namespace App\Mcp\Resources;

use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\Resource;

#[Description('Comprehensive guidelines for using the Weather API.')]
class WeatherGuidelinesResource extends Resource
{
    public function handle(Request $request): Response
    {
        $guidelines = "# Weather API Guidelines\n\n- Always specify a location...";

        return Response::text($guidelines);
    }
}

URIs and MIME types

By default, the URI is auto-generated from the class name (for example, weather://resources/weather-guidelines). You can customize this with the Uri and MimeType attributes.

use Laravel\Mcp\Server\Attributes\MimeType;
use Laravel\Mcp\Server\Attributes\Uri;
use Laravel\Mcp\Server\Resource;

#[Uri('weather://resources/guidelines')]
#[MimeType('application/pdf')]
class WeatherGuidelinesResource extends Resource
{
    // ...
}

Resource templates

To define a dynamic resource with URI variables, implement the HasUriTemplate interface.

<?php

namespace App\Mcp\Resources;

use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\Attributes\MimeType;
use Laravel\Mcp\Server\Contracts\HasUriTemplate;
use Laravel\Mcp\Server\Resource;
use Laravel\Mcp\Support\UriTemplate;

#[Description('Access user files by ID')]
#[MimeType('text/plain')]
class UserFileResource extends Resource implements HasUriTemplate
{
    public function uriTemplate(): UriTemplate
    {
        return new UriTemplate('file://users/{userId}/files/{fileId}');
    }

    public function handle(Request $request): Response
    {
        $userId = $request->get('userId');
        $fileId = $request->get('fileId');

        // Fetch the file content and return it...

        return Response::text("File {$fileId} for user {$userId}");
    }
}

Variables from the URI are automatically merged into the request and can be read with get.

Resource requests

Unlike tools and prompts, resources cannot define an input schema or arguments. However, you can still access request information via the request object inside handle.

<?php

namespace App\Mcp\Resources;

use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Resource;

class WeatherGuidelinesResource extends Resource
{
    public function handle(Request $request): Response
    {
        // Access request information...
    }
}

Resource dependency injection

Resources are resolved through Laravel’s service container, so you can type-hint dependencies in the constructor or handle method.

<?php

namespace App\Mcp\Resources;

use App\Repositories\WeatherRepository;
use Laravel\Mcp\Server\Resource;

class WeatherGuidelinesResource extends Resource
{
    public function __construct(
        protected WeatherRepository $weather,
    ) {}
}

You can also type-hint on handle, and the service container will resolve and inject dependencies automatically.

public function handle(WeatherRepository $weather): Response
{
    return Response::text($weather->guidelines());
}

Resource annotations

You can attach audience, priority, and last-modified annotations to a resource.

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
{
    // ...
}

Annotation	Type	Description
`#[Audience]`	Role or array	Target audience (`Role::User`, `Role::Assistant`, or both).
`#[Priority]`	float	Importance score (0.0 to 1.0).
`#[LastModified]`	string	ISO 8601 last-modified timestamp.

Conditional resource registration

Implement shouldRegister to conditionally register a resource at runtime.

<?php

namespace App\Mcp\Resources;

use Laravel\Mcp\Request;
use Laravel\Mcp\Server\Resource;

class WeatherGuidelinesResource extends Resource
{
    public function shouldRegister(Request $request): bool
    {
        return $request?->user()?->subscribed() ?? false;
    }
}

Returning false hides the resource from the AI client and prevents access.

Resource responses

A resource must return a Laravel\Mcp\Response instance. For text content, use the text method.

return Response::text($weatherData);

Resource link response

Use the resourceLink method to return a resource link. Unlike an embedded resource, it returns a URI pointer that the AI client will fetch independently.

return Response::resourceLink(
    uri: 'file:///data/report.json',
    name: 'monthly-report',
    mimeType: 'application/json',
);

You can also pass a registered resource class or instance. The URI, name, title, description, and MIME type are inherited automatically.

return Response::resourceLink(new WeatherForecastResource);

Blob response

To return binary content, use the blob method. Set the MIME type using the #[MimeType] attribute on the resource.

return Response::blob(file_get_contents(storage_path('weather/radar.png')));

#[MimeType('image/png')]
class WeatherGuidelinesResource extends Resource
{
    // ...
}

Error response

Use the error method to indicate an error.

return Response::error('Unable to fetch weather data for the specified location.');

Apps

Laravel MCP supports MCP Apps, an extension of the Model Context Protocol that lets tools render interactive HTML applications inside a sandboxed iframe in supported hosts. This enables dashboards, forms, visualizations, and other rich experiences that go beyond plain text responses. An MCP app is composed of two pieces working together.

App resource — returns the self-contained HTML for the application.
Tool — linked to the app resource with the #[RendersApp] attribute. When the tool is invoked, the host fetches and renders the linked resource.

Creating an app resource

You can create an app resource with the make:mcp-app-resource Artisan command.

php artisan make:mcp-app-resource WeatherDashboardApp

This command creates two files: a PHP class in app/Mcp/Resources and a Blade view in resources/views/mcp. The view name is inferred from the class name. For example, WeatherDashboardApp maps to mcp.weather-dashboard-app.

<?php

namespace App\Mcp\Resources;

use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Attributes\AppMeta;
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\AppResource;

#[Description('An interactive weather dashboard.')]
#[AppMeta]
class WeatherDashboardApp extends AppResource
{
    /**
     * Handle the app resource request.
     */
    public function handle(Request $request): Response
    {
        return Response::view('mcp.weather-dashboard-app', [
            'title' => $this->title(),
        ]);
    }
}

AppResource extends the base Resource class and automatically applies the ui:// URI scheme and text/html;profile=mcp-app MIME type required by the MCP Apps specification. Like other resources, you must register it in the server’s $resources array. The generated Blade view uses the <x-mcp::app> component. This component renders a complete HTML document that includes the bundled client-side MCP SDK.

<x-mcp::app :title="$title">
    <x-slot:head>
        <script type="module">
        createMcpApp(async (app) => {
            document.getElementById('run-btn').addEventListener('click', async () => {
                const result = await app.callServerTool('get-weather-data', {});
                document.getElementById('output').textContent = result.content[0]?.text ?? '';
            });
        });
        </script>
    </x-slot:head>

    <div id="app">
        <button id="run-btn">Refresh</button>
        <p id="output"></p>
    </div>
</x-mcp::app>

The global createMcpApp function is provided by the bundled SDK. It handles the iframe’s connection to the server, applies the host theme, and exposes helpers such as callServerTool, sendMessage, and openLink along with event callbacks. See the MCP Apps specification for the full client-side API.

Rendering an app from a tool

To display an app resource, link it from a tool with the #[RendersApp] attribute. When the tool is invoked, Laravel MCP includes the resource’s URI in the tool metadata so the host can render the app inside a sandboxed iframe.

<?php

namespace App\Mcp\Tools;

use App\Mcp\Resources\WeatherDashboardApp;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Attributes\RendersApp;
use Laravel\Mcp\Server\Tool;

#[RendersApp(resource: WeatherDashboardApp::class)]
class ShowWeatherDashboard extends Tool
{
    /**
     * Handle the tool request.
     */
    public function handle(Request $request): Response
    {
        return Response::text('Weather dashboard loaded.');
    }
}

When an AppResource is registered, Laravel MCP automatically advertises the io.modelcontextprotocol/ui capability. No additional server configuration is required.

App tool visibility

Each #[RendersApp] tool can restrict its callers via the visibility argument. This is useful for hiding private app-only tools the UI calls to load or update data from the model.

use Laravel\Mcp\Server\Attributes\RendersApp;
use Laravel\Mcp\Server\Ui\Enums\Visibility;

#[RendersApp(resource: WeatherDashboardApp::class, visibility: [Visibility::App])]
class GetWeatherData extends Tool
{
    // ...
}

The Visibility enum has two cases, Model and App, and defaults to both. Use [Visibility::App] for backend actions that only the UI calls directly, and [Visibility::Model] to make the tool unavailable to the UI.

App configuration

The #[AppMeta] attribute on an app resource configures the iframe’s Content Security Policy, browser permissions, and any library scripts to include in the view’s <head>.

use Laravel\Mcp\Server\Attributes\AppMeta;
use Laravel\Mcp\Server\Ui\Enums\Library;
use Laravel\Mcp\Server\Ui\Enums\Permission;

#[AppMeta(
    connectDomains: ['https://api.weather.com'],
    permissions: [Permission::Geolocation],
    libraries: [Library::Tailwind, Library::Alpine],
)]
class WeatherDashboardApp extends AppResource
{
    // ...
}

The Library enum ships preconfigured CDN scripts for common frontend libraries such as Library::Tailwind and Library::Alpine, and the CDN origins are automatically merged into the CSP. The Permission enum covers browser permissions such as Camera, Microphone, Geolocation, and ClipboardWrite.

For dynamic configuration, override the resource’s appMeta method using the AppMeta, Csp, and Permissions fluent builders from the Laravel\Mcp\Server\Ui namespace.

Developing apps with Boost

Laravel MCP includes a dedicated Boost skill reference for building MCP Apps. When Laravel Boost is installed, AI coding agents can invoke the mcp-development skill and automatically generate an app resource, its Blade view, and the linked tool. For the complete protocol reference (including client-side API and schema details), see the official MCP Apps documentation.

Metadata

You can attach the MCP spec’s _meta field to tool, resource, and prompt responses.

// Attach metadata to response content
return Response::text('The weather is sunny.')
    ->withMeta(['source' => 'weather-api', 'cached' => true]);

To attach metadata to the entire response envelope, use Response::make.

return Response::make(
    Response::text('The weather is sunny.')
)->withMeta(['request_id' => '12345']);

To attach metadata to the tool, resource, or prompt class itself, define a $meta property.

class CurrentWeatherTool extends Tool
{
    protected ?array $meta = [
        'version' => '2.0',
        'author' => 'Weather Team',
    ];
}

Icons

MCP clients can display icons for the server and its primitives. Use the Icon attribute to declare icons on the server, tools, resources, and prompts.

use Laravel\Mcp\Enums\IconTheme;
use Laravel\Mcp\Server\Attributes\Icon;

#[Icon('mcp/server.png', mimeType: 'image/png', sizes: ['48x48'])]
#[Icon('mcp/server-dark.svg', theme: IconTheme::Dark)]
class WeatherServer extends Server
{
    // ...
}

The Icon attribute is repeatable, so you can declare multiple icons to provide different sizes or light/dark theme variants. Alternatively, you can override the icons method to define icons programmatically. This is useful when icons depend on runtime conditions.

use Laravel\Mcp\Schema\Icon;

class CurrentWeatherTool extends Tool
{
    /**
     * Get the tool's icons.
     *
     * @return array<int, Icon>
     */
    public function icons(): array
    {
        return [
            Icon::from('mcp/tool.png', mimeType: 'image/png'),
        ];
    }
}

Icons defined via attributes and the icons method are combined automatically. Icon paths are resolved as follows.

Paths with a URI scheme such as https: or data: are used as-is.
Relative paths are resolved to URLs using Laravel’s asset helper.

Authentication

Web servers can be authenticated with Laravel’s standard middleware.

Sanctum

Token authentication using Laravel Sanctum. The MCP client sends an Authorization: Bearer <token> header.

use App\Mcp\Servers\WeatherServer;
use Laravel\Mcp\Facades\Mcp;

Mcp::web('/mcp/weather', WeatherServer::class)
    ->middleware('auth:sanctum');

OAuth 2.1

OAuth authentication using Laravel Passport. This suits situations that call for stronger security.

use App\Mcp\Servers\WeatherServer;
use Laravel\Mcp\Facades\Mcp;

Mcp::oauthRoutes();

Mcp::web('/mcp/weather', WeatherServer::class)
    ->middleware('auth:api');

When using OAuth, publish the Passport authorization view and register it in a service provider.

php artisan vendor:publish --tag=mcp-views

// AppServiceProvider::boot()
use Laravel\Passport\Passport;

Passport::authorizationView(function ($parameters) {
    return view('mcp.authorize', $parameters);
});

Authorization

You can retrieve the authenticated user via $request->user() and perform authorization checks inside tools and resources.

public function handle(Request $request): Response
{
    if (! $request->user()->can('read-weather')) {
        return Response::error('Permission denied.');
    }

    // Continue processing...
}

MCP client

Laravel MCP doesn’t just help you build servers — it also provides a client for connecting to other MCP servers. With the client, you can discover and invoke tools exposed by external MCP servers. This is especially useful when providing external MCP server capabilities to your AI agents.

Connecting to a server

Use Client::web to connect to an HTTP-accessible MCP server, passing the server URL.

use Laravel\Mcp\Client;

$client = Client::web('https://mcp.example.com');

To connect to a local MCP server that starts as a command, use Client::local, passing the command and its arguments.

use Laravel\Mcp\Client;

$client = Client::local('php', ['artisan', 'mcp:start']);

The client connects lazily and establishes the connection the first time you list or invoke tools. To manage the connection manually, use the connect, connected, ping, and disconnect methods.

$client->connect();

$client->ping();

if ($client->connected()) {
    // ...
}

$client->disconnect();

Use withTimeout to customize the request timeout.

$client = Client::web('https://mcp.example.com')->withTimeout(30);

Named clients

Instead of constructing a client each time, you can register a reusable named client. This is typically done in a service provider’s boot method using the Mcp facade.

use Laravel\Mcp\Client;
use Laravel\Mcp\Facades\Mcp;

Mcp::registerClient('github', fn () => Client::web('https://mcp.example.com'));

Once registered, you can resolve the client by name.

use Laravel\Mcp\Facades\Mcp;

$client = Mcp::client('github');

A named client is resolved once per request and automatically disconnected at the end of the request lifecycle.

Client authentication

To connect to a web MCP server protected by a bearer token, use the withToken method. You can pass a token string or a closure that resolves lazily.

use Illuminate\Support\Facades\Auth;
use Laravel\Mcp\Client;

$client = Client::web('https://mcp.example.com')->withToken($token);

$client = Client::web('https://mcp.example.com')->withToken(
    fn () => Auth::user()->mcpToken(),
);

To connect to a server protected by OAuth 2.1, use the withOAuth method.

use Laravel\Mcp\Client;
use Laravel\Mcp\Facades\Mcp;

Mcp::registerClient('github', fn () => Client::web('https://mcp.example.com')->withOAuth(
    clientId: config('services.github_mcp.client_id'),
    clientSecret: config('services.github_mcp.client_secret'),
));

If the MCP server supports dynamic client registration, you can omit clientId and clientSecret. The client will register itself automatically.

Next, register the OAuth routes for the named client in routes/ai.php with oAuthRoutesFor. The closure receives the client name and a TokenSet after the authorization code has been exchanged for an access token.

use Illuminate\Support\Facades\Auth;
use Laravel\Mcp\Client\OAuth\TokenSet;
use Laravel\Mcp\Facades\Mcp;

Mcp::oAuthRoutesFor('github', function (string $client, TokenSet $token) {
    Auth::user()->update([
        'github_mcp_token' => $token->accessToken,
    ]);

    return redirect('/dashboard');
});

This registers two named routes: the connect route (mcp.oauth.{client}.connect) that redirects the user to the authorization server, and the callback route (mcp.oauth.{client}.callback) that exchanges the authorization code and calls your handler. Both use the web middleware group by default (which you can override via the middleware argument). To begin the authorization flow, redirect the user to the connect route.

return redirect()->route('mcp.oauth.github.connect');

Tools

The tools method fetches tools exposed by the MCP server. It returns a collection keyed by name.

use Laravel\Mcp\Facades\Mcp;

$tools = Mcp::client('github')->tools();

foreach ($tools as $tool) {
    $tool->name;
    $tool->title;
    $tool->description;
    $tool->inputSchema;
}

The client automatically handles pagination and fetches every tool. Use the limit argument to cap the number of results.

$tools = Mcp::client('github')->tools(limit: 10);

To invoke a tool, use callTool and pass the tool name and an argument array. The returned ToolResult instance carries the response.

use Laravel\Mcp\Facades\Mcp;

$result = Mcp::client('github')->callTool('current-weather', [
    'location' => 'New York',
]);

$result->text();             // The response text content
(string) $result;            // Equivalent to text()
$result->isError;            // Whether the tool reported an error
$result->structuredContent;  // Structured content (if present)

You can also invoke it directly from a listed tool instance.

$tools = Mcp::client('github')->tools();

$result = $tools['current-weather']->call([
    'location' => 'New York',
]);

If you’re building an agent with the Laravel AI SDK, you can hand the MCP client’s tools directly to the agent so the model can call them while responding to a prompt. See the MCP tools section of the AI SDK docs for details.

Prompts

The prompts method fetches prompts exposed by the MCP server. It returns a collection keyed by name.

use Laravel\Mcp\Facades\Mcp;

$prompts = Mcp::client('github')->prompts();

foreach ($prompts as $prompt) {
    $prompt->name;
    $prompt->title;
    $prompt->description;
    $prompt->arguments;
}

The client automatically handles pagination and fetches every prompt. Use limit to cap the number of results.

$prompts = Mcp::client('github')->prompts(limit: 10);

To retrieve a prompt, use getPrompt, passing the prompt name and an argument array. The returned PromptResult instance carries the generated messages.

use Laravel\Mcp\Facades\Mcp;

$result = Mcp::client('github')->getPrompt('describe-weather', [
    'location' => 'New York',
]);

$result->text();        // The message text content
(string) $result;       // Equivalent to text()
$result->messages;      // The raw messages returned by the prompt
$result->description;   // The prompt's description (if present)

Resources

The resources method fetches resources exposed by the MCP server. It returns a collection keyed by URI.

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;
}

The client automatically handles pagination and fetches every resource. Use limit to cap the number of results.

$resources = Mcp::client('github')->resources(limit: 10);

To read a resource, use readResource and pass the resource URI. The returned ResourceReadResult instance carries the resource content.

use Laravel\Mcp\Facades\Mcp;

$result = Mcp::client('github')->readResource('weather://guidelines');

$result->content();   // The resource content (base64 blobs are decoded automatically)
(string) $result;     // Equivalent to content()
$result->mimeType();  // The resource's MIME type (if present)
$result->contents;    // The raw contents returned by the resource

Testing

MCP Inspector

Use the interactive MCP Inspector debugging tool to verify your MCP server.

# Web server
php artisan mcp:inspector mcp/weather

# Local server (when the name is "weather")
php artisan mcp:inspector weather

When you run the command, MCP Inspector starts and you can copy the client configuration. If you’ve configured authentication middleware, include the Authorization header when connecting.

Unit tests

You can write unit tests against tools, resources, and prompts.

test('tool', function () {
    $response = WeatherServer::tool(CurrentWeatherTool::class, [
        'location' => 'Tokyo',
        'units' => 'celsius',
    ]);

    $response
        ->assertOk()
        ->assertSee('The current weather in Tokyo is 22°C and sunny.');
});

public function test_tool(): void
{
    $response = WeatherServer::tool(CurrentWeatherTool::class, [
        'location' => 'Tokyo',
        'units' => 'celsius',
    ]);

    $response
        ->assertOk()
        ->assertSee('The current weather in Tokyo is 22°C and sunny.');
}

You can test prompts and resources the same way.

$response = WeatherServer::prompt(DescribeWeatherPrompt::class, ['tone' => 'casual']);
$response = WeatherServer::resource(WeatherGuidelinesResource::class);

Use actingAs to run as an authenticated user.

$response = WeatherServer::actingAs($user)->tool(CurrentWeatherTool::class, [...]);

The main assertion methods are:

$response->assertOk();           // Verify there is no error
$response->assertSee('...');     // Verify the response contains the given text

Use assertHasErrors / assertHasNoErrors to check for errors.

$response->assertHasErrors();

$response->assertHasErrors([
    'Something went wrong.',
]);

$response->assertHasNoErrors();

You can verify the tool, resource, or prompt’s name, title, and description.

$response->assertName('current-weather');
$response->assertTitle('Current Weather Tool');
$response->assertDescription('Fetches the current weather forecast for a specified location.');

Use assertSentNotification and assertNotificationCount to verify streaming response notifications.

$response->assertSentNotification('processing/progress', [
    'step' => 1,
    'total' => 5,
]);

$response->assertSentNotification('processing/progress', [
    'step' => 2,
    'total' => 5,
]);

$response->assertNotificationCount(5);

Use dd or dump to debug the response contents.

$response->dd();
$response->dump();

​What is MCP?

​Installation

​Creating a server

​Registering a server

​Web servers

​Local servers

​Tools

​Creating a tool

​Tool name and description

​Input schema

​Output schema

​Validation

​Dependency injection

​Annotations

​Conditional registration

​Responses

​Prompts

​Creating a prompt

​Prompt arguments

​Validation

​Dependency injection

​Conditional registration

​Prompt responses

​Resources

​Creating a resource

​URIs and MIME types

​Resource templates

​Resource requests

​Resource dependency injection

​Resource annotations

​Conditional resource registration

​Resource responses

​Resource link response

​Blob response

​Error response

​Apps

​Creating an app resource

​Rendering an app from a tool

​App tool visibility

​App configuration

​Developing apps with Boost

​Metadata

​Icons

​Authentication

​Sanctum

​OAuth 2.1

​Authorization

​MCP client

​Connecting to a server

​Named clients

​Client authentication

​Tools

​Prompts

​Resources

​Testing

​MCP Inspector

​Unit tests

What is MCP?

Installation

Creating a server

Registering a server

Web servers

Local servers

Tools

Creating a tool

Tool name and description

Input schema

Output schema

Validation

Dependency injection

Annotations

Conditional registration

Responses

Prompts

Creating a prompt

Prompt arguments

Validation

Dependency injection

Conditional registration

Prompt responses

Resources

Creating a resource

URIs and MIME types

Resource templates

Resource requests

Resource dependency injection

Resource annotations

Conditional resource registration

Resource responses

Resource link response

Blob response

Error response

Apps

Creating an app resource

Rendering an app from a tool

App tool visibility

App configuration

Developing apps with Boost

Metadata

Icons

Authentication

Sanctum

OAuth 2.1

Authorization

MCP client

Connecting to a server

Named clients

Client authentication

Tools

Prompts

Resources

Testing

MCP Inspector

Unit tests