Laravel MCP Server by OP.GG

<h1 align="center">Laravel MCP Server by OP.GG</h1>

<p align="center">
Build a route-first MCP server in Laravel and Lumen
</p>

<p align="center">
<a href="https://github.com/opgginc/laravel-mcp-server/actions"></a>
<a href="https://packagist.org/packages/opgginc/laravel-mcp-server"></a>
<a href="https://packagist.org/packages/opgginc/laravel-mcp-server"></a>
<a href="https://packagist.org/packages/opgginc/laravel-mcp-server"></a>
</p>

<p align="center">
<a href="https://op.gg/open-source/laravel-mcp-server">Official Website</a>
</p>

<p align="center">
<a href="README.md">English</a> |
<a href="README.pt-BR.md">Português do Brasil</a> |
<a href="README.ko.md">한국어</a> |
<a href="README.ru.md">Русский</a> |
<a href="README.zh-CN.md">简体中文</a> |
<a href="README.zh-TW.md">繁體中文</a> |
<a href="README.pl.md">Polski</a> |
<a href="README.es.md">Español</a>
</p>

<p align="center">

</p>

Breaking Changes 2.0.0

- Endpoint setup moved from config-driven registration to route-driven registration.
- Streamable HTTP is the only supported transport.
- Server metadata mutators are consolidated into setServerInfo(...).
- Legacy tool transport methods were removed from runtime (messageType(), ProcessMessageType::SSE).

Full migration guide: docs/migrations/v2.0.0-migration.md

Overview

Laravel MCP Server provides route-based MCP endpoint registration for Laravel and Lumen.

Key points:
- Streamable HTTP transport
- Route-first configuration (Route::mcp(...) / McpRoute::register(...))
- Tool, resource, resource template, and prompt registration per endpoint
- Route cache compatible endpoint metadata

Requirements

- PHP >= 8.2
- Laravel (Illuminate) >= 9.x
- Lumen >= 9.x (optional)

Quick Start

1) Install

composer require opgginc/laravel-mcp-server

2) Register an endpoint (Laravel)

use Illuminate\Support\Facades\Route;
use OPGG\LaravelMcpServer\Enums\ProtocolVersion;
use OPGG\LaravelMcpServer\Services\ToolService\Examples\HelloWorldTool;
use OPGG\LaravelMcpServer\Services\ToolService\Examples\VersionCheckTool;
Route::mcp('/mcp')

    ->setServerInfo(

        name: 'OP.GG MCP Server',

        version: '2.0.0',

    )

    ->setConfig(

        compactEnumExampleCount: 3,

    )

    ->setProtocolVersion(ProtocolVersion::V2025_11_25)

    ->enabledApi()

    ->tools([

        HelloWorldTool::class,

        VersionCheckTool::class,

    ]);

If you need compatibility with clients that do not support 2025-11-25, set:

->setProtocolVersion(ProtocolVersion::V2025_06_18)

3) Verify

php artisan route:list | grep mcp
php artisan mcp:test-tool --list --endpoint=/mcp

Quick JSON-RPC check:

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Dynamic Tool Filtering by Query String

If one endpoint needs to expose different tool sets based on the incoming URL, attach a dynamic tools resolver to the route.
The resolver owns both the declared tool catalog for the endpoint and the per-request visible subset.

use OPGG\LaravelMcpServer\Data\ToolResolutionContext;
use OPGG\LaravelMcpServer\Routing\McpEndpointDefinition;
use OPGG\LaravelMcpServer\Services\ToolService\DynamicToolResolverInterface;
final class LolPhaseToolResolver implements DynamicToolResolverInterface

{

    public function declaredTools(McpEndpointDefinition $endpoint): array

    {

        return [

            \App\MCP\Tools\LolSearchChampionMetaTool::class,

            \App\MCP\Tools\LolGetChampionAnalysisTool::class,

            \App\MCP\Tools\LolGetLiveItemRecommendationsTool::class,

        ];

    }
public function resolve(

        McpEndpointDefinition $endpoint,

        ToolResolutionContext $context,

    ): array {

        return match ($context->queryParameters['phase'] ?? null) {

            'lobby' => [

                \App\MCP\Tools\LolSearchChampionMetaTool::class,

                \App\MCP\Tools\LolGetChampionAnalysisTool::class,

            ],

            'inprogress' => [

                \App\MCP\Tools\LolGetLiveItemRecommendationsTool::class,

            ],

            default => $this->declaredTools($endpoint),

        };

    }
public function consumedQueryParameters(): array

    {

        return ['phase'];

    }

}

Route::mcp('/mcp/voice/lol/live')
    ->setServerInfo(
        name: 'OP.GG MCP Server - Voice lol Live',
        version: '1.0.0',
    )
    ->dynamicTools(LolPhaseToolResolver::class);

Example requests:

/mcp/voice/lol/live?phase=lobby
/mcp/voice/lol/live?phase=inprogress

The same filtered tool set is applied consistently to:
- tools/list
- tools/call
- tools/execute
- POST /tools/{tool_name} when ->enabledApi() is enabled

If the same endpoint also uses POST /tools/{tool_name}, you can optionally expose a public
consumedQueryParameters(): array hook on the resolver for query keys that should be used only
for filtering and not forwarded as tool arguments. This hook is a documented convention and is
not part of DynamicToolResolverInterface; resolvers that omit it will forward those query keys
as tool arguments.

Lumen Setup

// bootstrap/app.php
$app->withFacades();
$app->withEloquent();
$app->register(OPGG\LaravelMcpServer\LaravelMcpServerServiceProvider::class);

use OPGG\LaravelMcpServer\Routing\McpRoute;
use OPGG\LaravelMcpServer\Services\ToolService\Examples\HelloWorldTool;
McpRoute::register('/mcp')

    ->setServerInfo(

        name: 'OP.GG MCP Server',

        version: '2.0.0',

    )

    ->tools([

        HelloWorldTool::class,

    ]);

Minimal Security (Production)

Use Laravel middleware on your MCP route group.

use Illuminate\Support\Facades\Route;
Route::middleware([

    'auth:sanctum',

    'throttle:100,1',

])->group(function (): void {

    Route::mcp('/mcp')

        ->setServerInfo(

            name: 'Secure MCP',

            version: '2.0.0',

        )

        ->tools([

            \App\MCP\Tools\MyCustomTool::class,

        ]);

});

v2.0.0 Migration Notes (from v1.0.0)

- MCP endpoint setup moved from config to route registration.
- Streamable HTTP is the only transport.
- Server metadata mutators are consolidated into setServerInfo(...).
- Tool migration command is available for legacy signatures:

php artisan mcp:migrate-tools

Full guide: docs/migrations/v2.0.0-migration.md

Advanced Features (Quick Links)

- Create tools: php artisan make:mcp-tool ToolName
- Create resources: php artisan make:mcp-resource ResourceName
- Create resource templates: php artisan make:mcp-resource-template TemplateName
- Create prompts: php artisan make:mcp-prompt PromptName
- Create notifications: php artisan make:mcp-notification HandlerName --method=notifications/method
- Generate from OpenAPI: php artisan make:swagger-mcp-tool <spec-url-or-file>
- Export tools to OpenAPI: php artisan mcp:export-openapi --output=storage/api-docs-mcp/api-docs.json

Code references:
- Tool examples: src/Services/ToolService/Examples/
- Resource examples: src/Services/ResourceService/Examples/
- Prompt service: src/Services/PromptService/
- Notification handlers: src/Server/Notification/
- Route builder: src/Routing/McpRouteBuilder.php

Swagger/OpenAPI -> MCP Tool

Generate MCP tools from a Swagger/OpenAPI spec:

…