In this article, we will create a tool in our Laravel MCP server to add to-do items. We will then consume the MCP server from an MCP client like VS Code.
Source Code: https://github.com/medhatelmasry/mcp-todo-laravel
Getting Started
Create a standard Laravel app with the following command:
composer create-project laravel/laravel mcp-todo-laravel
cd mcp-todo-laravel
Install the official Laravel MCP package via Composer:
composer require laravel/mcp
Publish the MCP configuration and routing files:
php artisan vendor:publish --tag=ai-routes
This creates routes/ai.php, where we will register your MCP servers.
Open your application in VS Code.
We need to register the ai.php in the application bootstrap file. Edit the bootstrap/app.php file. Make these changes:
1) Add this at the top:
use Illuminate\Support\Facades\Route;
2) Add this code just under “health: '/up',”:
then: function () {
Route::prefix('mcp')
->middleware('api') // api middleware disables CSRF checks
->group(base_path('routes/ai.php'));
},
Create and Register the Server
Create and Register the Server
Generate an MCP server class to group our tools:
php artisan make:mcp-server TodoServer
This creates the following file:
<?php
namespace App\Mcp\Servers;
use Laravel\Mcp\Server;
use Laravel\Mcp\Server\Attributes\Instructions;
use Laravel\Mcp\Server\Attributes\Name;
use Laravel\Mcp\Server\Attributes\Version;
#[Name(Todo Server')]
#[Version('0.0.1')]
#[Instructions('This server is used to manage the to-do list. Tools are used to add to-do items.')]
class TodoServer extends Server {
protected array $tools = [
//
];
protected array $resources = [
//
];
protected array $prompts = [
//
];
}
Update the file with the text highlighted in yellow above.
Then, register it in routes/ai.php as either a local or web server (or both) by replacing the content with the following:
<?php
use App\Mcp\Servers\TodoServer;
use Laravel\Mcp\Facades\Mcp;
// Web server: accessible via HTTP POST at /mcp/todo
Mcp::web('/mcp/todo', TodoServer::class);
// Local server: runs as an Artisan command
Mcp::local('todo', TodoServer::class);
Create an MCP Tool
Tools define the actions an AI can perform. Generate a new tool class with:
php artisan make:mcp-tool AddTodoTool
This adds the following tool:
<?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('A description of what this tool does.')]
class AddTodoTool extends Tool {
public function handle(Request $request): Response {
//
return Response::text('The content generated by the tool.');
}
public function schema(JsonSchema $schema): array {
return [
//
];
}
}
Replace the above file with the following code:
<?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('Add a to-do item to the database. It takes description, isDone (Boolean) and date as parameters.')]
class AddTodoTool extends Tool {
public function handle(Request $request): Response {
$validated = $request->validate(
[
'description' => 'required|string',
'isDone' => 'required|boolean',
'created_at' => 'required|string',
]);
logger($validated);
return Response::text('The content generated by the tool.');
}
public function schema(JsonSchema $schema): array {
return [
'description' => $schema->string()
->description("The description of the to-do item")
->required(),
'isDone' => $schema->boolean()
->description("True if done and False if not done")
->required(),
'created_at' => $schema->string()
->description("The date when the to-do item was created")
->required(),
];
}
}
Register the above tool in the $tools array in app/Mcp/Servers/TodoServer.php. Add the code highlighted in yellow below.
use App\Mcp\Tools\AddTodoTool;
. . . . . . . . . .
protected array $tools = [
AddTodoTool::class,
];
Let’s now run the server with:
php artisan serve
Connecting to a Client
To test our server, we can use the MCP Inspector or add the endpoint to an AI IDE like VS Code.
Let us first test with the MCP Inspector. In another terminal window from the same folder, start the MCP inspector with:
php artisan mcp:inspector mcp/todo
The inspector will open in your default browsesr. Add :8000 to the URL, then click on the black Connect button.
Click on Tools, followed by "List Tools".
Click on "Add Todo Tool", enter a description (like: Add to-do item: go to the gym), enter a date, then click on the "Run Tool" button - as shown below.
The following confirmation will be displayed:
We now know that the MCP server and to-do tool are working as expected. Let's consume the MCP service from VS Code. In Visual Studio Code, from the top menu, select View >> Pallette…
Choose "MCP: Add Server ...".
Choose "HTTP (HTTP or Server-Sent Events).
Enter http://localhost:8000/mcp/todo for the URL, then hit ENTER.
Give the server ID: todo-mcp-server.
Choose: Workspace Available in the workspace, runs locally.
A file gets created under .vscode named mcp.json that looks like this:
{
"servers": {
"todo-mcp-server": {
"url": "http://localhost:8000/mcp/todo",
"type": "http"
}
},
"inputs": []
}
Make sure the server is running.
In Visual Studio Code, open the chat panel by clicking on the below tool.
Choose Agent mode.
Next, click on the "Configure Tools ..." tool as shown below.
The "Configure Tools ..." panel will open at the top and you should see that our todo-mcp-server is running.
Close the "Configure Tools ..." panel by clicking on the blue OK button.
Enter the following prompt into the chat windows:
using the todo mcp server, add this todo item: fix the dish washer dated 2026-03-07
VS Code will seek your permission to proceed. Click on the "Allow in this Session" button.
Sample Output:
Extending the Laravel MCP Tool
Let us get our Todo tool to add items into a SQLite database. We can get AI to do some of the coding for us. Enter this prompt into the chat window:Create a model called Todo, Add a migration. The database table should have description (string) and isDone ( Boolean). In the model, add all columns as fillable.
This may request that you agree to the execution of this terminal window command:
It then asks you to run this command to apply the migration:
php artisan migrate
Go ahead and run the above command.
In app/Mcp/Tools/AddTodoTool.php:
1) Add this at the top:
use App\Models\Todo;
2) Add this code to the handle() method just before the final return statement:
Todo::create($validated);
Test it out by entering this prompt:
I need to put gas in the car and buy bread.
Sample Result:
The todos table in the database/database.sqlite database file will contain the data that was just inserted into the database.
Conclusion
We have successfully added a Todo MCP tool in a Laravel application. There are so many opportunities to get AI to participate in a new way of concievinng applications that users can interface with using a AI chat interaction.
