Laravel MCP Server by OP.GG

Build a route-first MCP server in Laravel and Lumen

Official Website

English | Português do Brasil | 한국어 | Русский | 简体中文 | 繁體中文 | Polski | Español

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

2) Register an endpoint (Laravel)

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

3) Verify

Quick JSON-RPC check:

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.

Example requests:

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

Minimal Security (Production)

Use Laravel middleware on your MCP route group.

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:

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:

Useful options:

• --group-by: tag, path, or none
• --prefix: class-name prefix for generated tools/resources
• --test-api: test endpoint connectivity before generation

Generation behavior:

• In interactive mode, you can choose Tool or Resource per endpoint.
• In non-interactive mode, GET endpoints are generated as Resources and other methods as Tools.

Enhanced Interactive Preview

If you run the command without --group-by, the generator shows an interactive preview of folder structure and file counts before creation.

Example preview output:

After generation, register generated tool classes on your MCP endpoint:

MCP Tools -> OpenAPI Export

Export all registered ToolInterface classes (via Route::mcp(...)->tools([...]) or ->dynamicTools(...)) to an OpenAPI JSON document using each tool's inputSchema(). Only endpoints configured with ->enabledApi() are included in this export and exposed through POST /tools/{tool_name}. Operations are grouped by endpoint name using OpenAPI tags. If multiple endpoints register the same tool name, the operation keeps first-registration behavior and merges all matching endpoint names into tags. If route registration is missing, the command auto-discovers tools under default paths: app/MCP/Tools and app/Tools.

Enable Tool API route generation:

Swagger UI testing tip:

• Exported operations use query parameters only (no requestBody) for simpler manual testing.
• Required fields from each tool inputSchema().required are reflected in Swagger parameter validation.
• Enum fields are exported with schema.enum so Swagger renders dropdown selections.
• Array fields are exported with style=form + explode=true (repeat key format, e.g. desired_output_fields=items&desired_output_fields=runes).
• /tools/{tool_name} argument parsing prefers query parameters over body/form payloads to avoid Swagger conflicts.
• Enum fields without explicit default/example are auto-filled from the first enum value (or first non-null enum value).
• String fields with descriptions like e.g., en_US, ko_KR, ja_JP auto-infer first sample value as default and example.

Example Tool Class

JsonSchema Builder (Laravel-Style)

This package provides its own JsonSchema builder under the OPGG\LaravelMcpServer namespace. You can define tool schemas in a Laravel 12-style fluent format while keeping inputSchema(): array.

Notes:

• Existing full JSON Schema arrays are still supported.
• enum() accepts either an array or a BackedEnum::class.
• compact() can be chained after enum() to remove enum from emitted schema and append a compact hint to description (compact(), compact(null), compact(3), or compact('custom hint')).
• Default compact example count is 3, and it can be overridden per endpoint via Route::mcp(...)->setConfig(compactEnumExampleCount: N).
• When exporting (tools/list, OpenAPI), property maps are automatically normalized to JSON Schema object format.

Example Prompt Class

Example Resource Class

Register Examples on a Route

Testing and Quality Commands

Translation

Translate selected languages:

License

This project is distributed under the MIT license.