mcp-development

MCP Development

Documentation

Use search-docs for detailed Laravel MCP patterns and documentation.

For MCP UI apps (interactive HTML resources), read references/app.md — it covers the full architecture, host theming CSS variables, tool-to-UI linking patterns, library scripts (Tailwind, Alpine via Library), and real-world examples.

Basic Usage

Register MCP servers in routes/ai.php:

use Laravel\Mcp\Facades\Mcp;

Mcp::web('/mcp/demo', \App\Mcp\Servers\AppServer::class);

Creating MCP Primitives

php artisan make:mcp-tool ToolName            # Create a tool
php artisan make:mcp-resource ResourceName     # Create a resource
php artisan make:mcp-prompt PromptName        # Create a prompt
php artisan make:mcp-server ServerName        # Create a server
php artisan make:mcp-app-resource DashboardApp # Create a UI app (2 files)

After creating primitives, register them in your server's $tools, $resources, or $prompts properties.

Tools

use Illuminate\Json\Schema\JsonSchema;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Tool;

class MyTool extends Tool
{
    protected string $description = 'Describe what this tool does';

    public function schema(JsonSchema $schema): array
    {
        return [
            'name' => $schema->string()->description('The name parameter')->required(),
        ];
    }

    public function handle(Request $request): Response
    {
        $request->validate(['name' => 'required|string']);

        return Response::text('Hello, '.$request->get('name'));
    }
}

Registering Primitives in a Server

use Laravel\Mcp\Server;

class AppServer extends Server
{
    protected array $tools = [
        \App\Mcp\Tools\MyTool::class,
    ];

    protected array $resources = [
        \App\Mcp\Resources\MyResource::class,
    ];

    protected array $prompts = [
        \App\Mcp\Prompts\MyPrompt::class,
    ];
}

MCP UI Apps

For MCP UI apps, read references/app.md — it covers quick start examples, full architecture, AppMeta/Csp/Permissions, #[RendersApp] tool linking, library scripts (Tailwind/Alpine via Library), host theming CSS variables, and real-world patterns.

Verification

1. Check routes/ai.php for proper registration
2. Test tool via MCP client

Common Pitfalls

• Running mcp:start command (it hangs waiting for input)
• Using HTTPS locally with Node-based MCP clients
• Not using search-docs for the latest MCP documentation
• Not registering MCP server routes in routes/ai.php
• Do not register ai.php in bootstrap.php; it is registered automatically
• OAuth registration supports custom URI schemes (e.g., cursor://, vscode://) for native desktop clients via mcp.custom_schemes config