opgginc/laravel-mcp-server

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