Update, October 2026: I first published this post in August 2025. It aged badly, and fast. About three weeks after it went up, the PHP Foundation, Symfony, and Anthropic’s MCP team announced an official PHP SDK, which made both packages I’d recommended the wrong place to start. Then in July 2026 the protocol itself changed shape. So I’ve thrown out the old version and written this one from scratch. (The URL is the same. Almost nothing else is.)

If you write PHP for a living and somebody has asked you to “make the app work with AI agents,” this is what I’d tell you over coffee.

What changed since the first version

Four things, and I’ll go through them in the order they hurt.

• There’s an official SDK now. It’s mcp/sdk, it grew out of Kyrian Obikwelu’s PHP-MCP project and the Symfony AI work, and the Symfony team leads maintenance. It covers servers and clients. It’s also still pre-1.0, and the README says “experimental” in plain words, so pin your version.
• Laravel ships its own package. laravel/mcp is first-party, documented alongside the framework, and comes with Artisan generators, a test API, and an MCP client.
• The protocol went stateless. The 2026-07-28 revision removed the opening handshake and the protocol-level session. More on this below, because for PHP it’s the big one.
• Authorization grew up. OAuth 2.1 is the mechanism the spec documents. A bearer token still works with plenty of clients, but “use an API token” (which is all I said last time) isn’t the whole answer anymore.

And one correction I owe you. The JSON example in the old post called a method named tool. There’s no such method. It’s tools/call, and it was tools/call back then too. Sorry about that.

What a PHP MCP server exposes

This part hasn’t changed, so I’ll keep it short. A server offers three kinds of things to an AI client.

Tools are functions the model can call: create a project, send an invoice, look up an order. Resources are read-only data the client can pull in as context, addressed by a URI. Prompts are reusable templates the server hands to the client.

Start with tools. In the servers we’ve built, tools did nearly all the useful work, and resources came a distant second. I’d leave prompts until a real user asks for one.

Why the stateless spec suits PHP

Until this summer, MCP over HTTP was a conversation. The client opened with an initialize handshake, the server handed back a session ID, and every later request had to carry that ID so the server could remember who it was talking to.

That’s fine in Node or Python, where one long-lived process sits in memory holding the session. It’s a nuisance in PHP, because PHP-FPM on an ordinary host gives you a fresh process for each request that remembers nothing, which meant you needed a session store (files on one server, Redis on several), and then you needed the load balancer to cooperate, and then somebody’s shared hosting plan killed the long-running stream the server wanted to keep open, and at that point a perfectly sane developer would ask why a remote procedure call needed all this furniture.

The 2026-07-28 revision removes the furniture. There’s no handshake and no protocol session. Each request carries its own protocol version and client details, any worker on any machine can answer it, and list results come with cache hints. Cloudflare, AWS, and the MCP maintainers all describe it the same way: MCP now scales like any other HTTP API.

What if your server really does need to remember something, like a cart or a half-finished import? The spec’s guidance is to return a handle from one tool and accept it as an argument on the next. In other words, a primary key. We’ve been doing that since PHP 3.

There’s a cost, and you should hear it from me before you hear it from a client. The new revision isn’t backward compatible. A server that only speaks 2026-07-28 may not work with an older client, and the reverse. So for a while you’ll be supporting both eras, and that’s a good reason to use an SDK instead of hand-rolling the JSON. (We hand-rolled once. I wrote up what happened in building a WordPress MCP server while the spec changed.)

What a tool call looks like on the wire

MCP messages are JSON-RPC 2.0, a small remote procedure call format where every message names a method and carries an ID. Here’s a client asking a server to run a tool.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "create_project",
    "arguments": {
      "project_name": "New Website Launch",
      "due_date": "2026-12-31"
    },
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28"
    }
  }
}

I’ve trimmed the _meta block. The spec requires client info and client capabilities in there too, and your SDK fills them in. On HTTP, the client also sends MCP-Protocol-Version, Mcp-Method, and Mcp-Name headers, so a load balancer or firewall can route the call without opening the body. If you’ve ever fought a web application firewall over a JSON payload (I have, on our own host), you’ll like that.

The server answers like this.

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "resultType": "complete",
    "content": [
      { "type": "text", "text": "Created project 42: New Website Launch" }
    ],
    "structuredContent": { "project_id": 42, "name": "New Website Launch" },
    "isError": false
  }
}

Two details matter. structuredContent is the machine-readable result, and the text block is the fallback for clients that only read text. And when your business logic fails, say the due date is in the past, you return a normal result with isError set to true and a message the model can act on. Save real JSON-RPC errors for broken requests and unknown tools.

Build one in plain PHP with the official SDK

This works in any PHP project: plain PHP, CodeIgniter, Slim, a legacy app with no framework at all. The steps below build a local server that talks over STDIO (standard input and output, the way a desktop AI client starts a server as a child process).

Goal. A PHP file exposes one tool named create_project, and MCP Inspector can call it.

Before you start. You need Composer and Node.js installed. Check the PHP version the SDK requires on its Packagist page before you install.

Step 1: Install the SDK. Run this command in an empty project folder. Composer prints the installed version when it finishes.

composer require mcp/sdk

Step 2: Create the server file. Save this code as server.php in the same folder. The tool body is a stub, so replace it with a call to your own service class later.

<?php

require __DIR__ . '/vendor/autoload.php';

use Mcp\Server;
use Mcp\Server\Transport\StdioTransport;

class ProjectTools
{
    /**
     * Create a project and return its ID.
     */
    public function createProject(string $projectName, string $dueDate): array
    {
        // Call your existing service class here.
        return ['project_id' => 42, 'name' => $projectName, 'due_date' => $dueDate];
    }
}

$server = Server::builder()
    ->setServerInfo('Project Server', '1.0.0')
    ->addTool([ProjectTools::class, 'createProject'], 'create_project')
    ->build();

$server->run(new StdioTransport());

Step 3: Open the server in MCP Inspector. MCP Inspector is the official browser tool for testing a server by hand. Replace the path with the full path to your server.php.

npx @modelcontextprotocol/inspector php /Users/YOU/project-server/server.php

Check. The Inspector’s Tools tab lists create_project with two string inputs. You run it, and the result shows project_id 42.

If it fails. The usual cause is stray output. On STDIO, anything your script prints (a warning, a debug echo, a byte order mark) lands in the protocol stream and breaks it. Send logs to a file or to standard error.

Undo. Delete the project folder. Nothing else on your machine changed.

For a remote server you swap the transport for the SDK’s StreamableHttpTransport, which takes a PSR-7 request (the standard PHP interface for an HTTP message) and returns a response. The transports guide has the wiring. Read the protocol versions page while you’re there. As far as I can tell from the repository, support for the stateless revision has been landing release by release, so check what your installed version speaks before you promise a client anything.

Build one in Laravel with laravel/mcp

If the app is Laravel, don’t use the plain SDK. Use the first-party package. You get the container, validation, policies, and middleware you already know, and the tool class ends up looking like a small controller.

Goal. Your Laravel app serves an authenticated MCP endpoint at /mcp/projects with one tool that creates a project.

Before you start. The package needs PHP 8.2 or newer and Laravel 11, 12, or 13. The steps assume Sanctum (Laravel’s token authentication package) is already installed, and that you have a ProjectService class and a Project policy. Swap in your own names.

Step 1: Install the package.

composer require laravel/mcp

Step 2: Publish the routes file. This command creates routes/ai.php, where MCP servers are registered.

php artisan vendor:publish --tag=ai-routes

Step 3: Generate the server class. The file appears in app/Mcp/Servers.

php artisan make:mcp-server ProjectServer

Step 4: Generate the tool class. The file appears in app/Mcp/Tools.

php artisan make:mcp-tool CreateProjectTool

Step 5: Write the tool. Replace the generated tool with this code. Notice the order: authorize, validate, then call the service.

<?php

namespace App\Mcp\Tools;

use App\Models\Project;
use App\Services\ProjectService;
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('Creates a project for the signed-in user. Needs a name and a due date.')]
class CreateProjectTool extends Tool
{
    public function handle(Request $request, ProjectService $projects): Response
    {
        if (! $request->user()->can('create', Project::class)) {
            return Response::error('Permission denied.');
        }

        $validated = $request->validate([
            'project_name' => 'required|string|max:120',
            'due_date' => 'required|date|after:today',
        ]);

        $project = $projects->create($request->user(), $validated);

        return Response::structured([
            'project_id' => $project->id,
            'name' => $project->name,
        ]);
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'project_name' => $schema->string()
                ->description('The project name.')
                ->required(),
            'due_date' => $schema->string()
                ->description('The due date as YYYY-MM-DD.')
                ->required(),
        ];
    }
}

Step 6: Register the tool on the server. Open app/Mcp/Servers/ProjectServer.php and set the $tools property.

protected array $tools = [
    \App\Mcp\Tools\CreateProjectTool::class,
];

Step 7: Register the route. Put this code in routes/ai.php. The throttle:mcp middleware expects a rate limiter named mcp, so define one in your AppServiceProvider or remove that entry.

<?php

use App\Mcp\Servers\ProjectServer;
use Laravel\Mcp\Facades\Mcp;

Mcp::web('/mcp/projects', ProjectServer::class)
    ->middleware(['auth:sanctum', 'throttle:mcp']);

Step 8: Open the server in MCP Inspector. Add your Sanctum token as an Authorization: Bearer header when the Inspector asks for connection settings.

php artisan mcp:inspector mcp/projects

Check. The Inspector lists create-project (Laravel derives the name from the class). You call it with a past date, and the tool returns your validation message instead of creating anything.

If it fails. A 401 response means the token header is missing or the token is wrong. An empty tool list means Step 6 was skipped.

Undo. Remove the route from routes/ai.php. The endpoint stops existing on the next request.

One thing I’d do before any of this reaches production: write the validation messages for a machine reader. When validation fails, the model reads your error text and tries again, so “The due date must be a future date in YYYY-MM-DD format” gets you a correct retry and “Invalid input” gets you a loop. (Laravel’s type handling has its own traps here. We wrote about one in integers arriving as strings.)

MCP vs REST vs GraphQL

I get asked whether MCP replaces the REST API. No. They have different callers.

The row that matters is the second one. With REST, a programmer read your docs and decided which endpoint to hit. With MCP, a model reads your tool descriptions and decides on the spot. So the description is part of the interface, and a vague one is a bug.

Don’t write the logic twice, though. Your MCP tool and your REST controller should call the same service class. If your controllers are fat and the logic lives in them, fix that first. It’s the same advice I’d give for splitting a PHP app into services, and it pays off here for the same reason.

Security: what I’d lock down first

An MCP tool is a function on your production app that a language model can run. You are giving a caller that doesn’t understand consequences a button. You are trusting its client to ask a human first. You are assuming nobody slipped instructions into the text it just read. Treat every argument the way you’d treat a form field from a stranger.

The spec lists four things a server must do: validate inputs, enforce access control, rate limit, and sanitize outputs. Here’s how that turns into a pre-launch list.

• Every web MCP route sits behind authentication middleware. No public endpoints, not even for a demo.
• Each tool checks what this user may do, with a policy or gate, inside the tool. Being logged in isn’t permission.
• Each tool validates its arguments with real rules, not just the JSON schema.
• The route has a rate limiter. Models retry, and they retry quickly.
• Read-only tools are marked read-only, and destructive ones are marked destructive, so clients can ask for confirmation.
• Nothing destructive ships in version one. No delete tools, no bulk updates.
• Every tool call is logged with the user, the tool name, and the arguments.
• Tool output is trimmed to what the model needs. No password hashes, no internal IDs you wouldn’t put in an API response.

On authentication: Laravel’s own docs recommend OAuth through Passport, since that’s what the spec documents and what the widest range of clients support. They also say that if you’re already on Sanctum, stay there until a client forces the issue. I agree with that. Don’t bolt on an OAuth server for an internal tool three people use.

And keep a person in the loop for anything that writes. We run an MCP server on one of our own sites that lets an AI assistant edit pages. Every edit lands as a draft, and a human publishes it. That one rule has saved us more than once. It’s the same thinking behind controlled AI coding, and behind my standing worry that the code an AI wants to delete is load-bearing.

Where I’d wait

I’d build an internal MCP server today. I’d be slower about a public, customer-facing one, for two reasons.

Both PHP packages are pre-1.0. APIs will move. The examples in this post matched the documentation on the day I checked them (October 9, 2026), and I’d bet at least one is out of date within a year. Pin versions, and read the changelog before you run composer update.

The protocol also just had its biggest revision since launch. The maintainers added a formal deprecation policy alongside it, which is a good sign, but I’d let clients and SDKs settle for a few months before signing a contract that names a spec version.

If you’re not on Laravel: Symfony has symfony/mcp-bundle, Drupal has an mcp_server module, and API Platform and CakePHP have integrations built on the same official SDK. For WordPress, read the post I linked earlier. That’s about all I know that’s worth passing on. If you’ve shipped a PHP MCP server and something here is wrong, tell me in the comments and I’ll fix it with credit.

FAQ

The post PHP MCP Server: A PHP Developer’s Guide to the Model Context Protocol first appeared on Macronimous Blog.

This is an exciting time for developers, and for a tech-focused people like us at Macronimous.com, diving into new tools like Gemini CLI for Laraval development is definitely a natural fit. Here’s a detailed blog post for Laravel developers on how Gemini CLI can revolutionize their workflow.

Let’s break down what Gemini CLI is, why it matters for Laravel developers, what you might miss if you don’t explore it, and how to get started.

What is Google Gemini CLI?

At its core, the Gemini CLI is an open-source AI agent that allows you to interact with Google’s Gemini models directly from your terminal. Think of your command line as an AI-powered workspace. It’s designed to understand natural language prompts and leverage the advanced capabilities of Gemini 2.5 Pro (which boasts an impressive 1 million token context window in the free tier) to perform a wide range of tasks.

Key capabilities include:

• Code Understanding and Generation: Explain complex code snippets, draft new code, generate unit tests, suggest refactorings, and even help with migrating code.
• Debugging and Troubleshooting: Analyze error messages, pinpoint root causes, and suggest effective solutions for bugs.
• File and Project Management: Use natural language to navigate, summarize, and even modify files within your project structure.
• Command Execution: Translate plain English instructions into executable shell commands.
• Content Generation: Beyond code, it can assist with general content creation, problem-solving, and research, grounding prompts with real-time Google Search results.
• Extensibility: Being open-source (Apache 2.0 license), it supports Model Context Protocol (MCP) servers, allowing for custom tool integrations and extending its functionality.

Essentially, Gemini CLI aims to be a versatile assistant that streamlines your development workflow, making you more productive without leaving the familiar environment of your terminal.

Is it Required for Laravel Developers to Learn and Use Gemini CLI?

“Required” is a strong word in software development, as many paths lead to a successful outcome. However, for Laravel developers aiming for peak efficiency and modern development practices, Gemini CLI is becoming increasingly valuable and highly recommended, though not strictly mandatory.

Here’s why:

1. Complexity of Modern Laravel: Laravel applications, especially larger ones, can involve intricate logic, multiple packages, API integrations, and complex database interactions. Navigating and understanding these can be time-consuming.
2. Increased Productivity: AI tools are no longer a luxury; they are becoming productivity multipliers. Gemini CLI can automate repetitive tasks, provide instant answers, and generate boilerplate code, freeing up developers to focus on more complex, creative problem-solving.
3. Staying Competitive: As AI integration becomes more common, developers who can effectively leverage these tools will have a significant edge in terms of speed, quality, and adaptability.

While you can develop Laravel applications perfectly well without it, embracing such tools pushes you towards a more efficient and less error-prone future.

What Would Laravel Developers Miss if They Don’t Use Gemini CLI?

Choosing to forgo Gemini CLI means missing out on several significant advantages:

• Rapid Prototyping and Boilerplate Generation: Imagine instantly generating a Laravel Livewire component with basic CRUD operations, or a database migration script for a new feature, just by describing it in natural language. Without Gemini CLI, these are manual tasks.
• Accelerated Debugging: Instead of meticulously tracing stack traces, you could paste an error and get intelligent suggestions, potential fixes, and even context-aware code modifications. This drastically cuts down debugging time.
• Deep Codebase Understanding: For large or legacy Laravel projects, understanding how different services, controllers, models, and views interact can be daunting. Gemini CLI, with its large context window, can analyze your entire codebase and provide summaries, architectural overviews, or explain specific Laravel patterns used.
• Optimized Code & Best Practices: You might miss opportunities for AI-driven code reviews that suggest performance improvements, adherence to Laravel conventions, or security enhancements.
• Reduced Context Switching: Staying in your terminal for AI assistance, rather than switching to a browser or other applications, maintains your flow state and improves focus.
• Enhanced Learning: For junior developers, or when learning new Laravel features or packages, Gemini CLI can act as an interactive tutor, explaining concepts, providing examples, and answering questions in real-time.
• Automated Documentation: Generating doc blocks for your Laravel classes, methods, or even entire modules can be automated, ensuring your codebase remains well-documented.

In essence, you’d be missing out on a powerful assistant that can significantly reduce cognitive load and development cycles.

Why Gemini CLI is Not Necessary for Some Developers

Despite its immense benefits, Gemini CLI might not be a game-changer for everyone, or at least not immediately:

• Smaller Projects or Solo Developers (Initial Stages): For very small, simple Laravel projects or developers who prefer a strictly manual approach, the initial setup and learning curve might seem like overkill.
• Highly Specialized Workflows: Developers with deeply ingrained, highly optimized, and unique manual workflows might find adopting a new AI tool disruptive, especially if their existing setup is already extremely efficient for their specific niche.
• Reliance on Specific IDE Features: Modern IDEs like PhpStorm already offer powerful code completion, refactoring, and debugging tools. Developers who heavily rely on these integrated features might not feel the immediate need for a CLI-based AI.
• Bandwidth/Internet Dependency: While the free tier is generous, heavy reliance on any cloud-based AI tool means you’re dependent on an internet connection and Google’s service availability.
• Privacy Concerns (for some): While Google has robust privacy policies, some developers or organizations might have strict internal policies against sending proprietary code to external AI services, even if the data handling is secure.
• “Human in the Loop” Preference: Some developers simply prefer to understand and write every line of code themselves, meticulously, and might view AI generation as a shortcut that reduces their hands-on understanding.

For these developers, the traditional Laravel development workflow remains perfectly viable. However, the capabilities offered by Gemini CLI are rapidly becoming a standard expectation for developer productivity.

How to Start Using Gemini CLI for Laravel Development

If you’re a Laravel developer ready to harness the power of Gemini CLI, getting started is straightforward.

1. Prerequisites:

• Node.js (Version 18 or higher): Gemini CLI runs on Node.js. Ensure you have a recent version installed. You can check with node -v.
• Google Account: You’ll need a personal Google account for authentication. This grants you free-tier access with generous quotas (60 requests/minute and 1,000 requests/day for Gemini 2.5 Pro). For higher limits or specific models, you can use a Google AI Studio API key.

2. Installation:

Open your terminal and choose one of the following installation methods:

• Run Directly (npx): This is great for quick tests or if you don’t want a global installation.

Bash

npx https://github.com/google-gemini/gemini-cli

• Global Installation (Recommended for regular use): This installs gemini as a command accessible anywhere.

npm install -g @google/gemini-cli

3. First Run and Authentication:

After installation, simply type gemini in your terminal:

gemini

On the first run, you’ll be prompted to:

• Choose a color theme: Select your preferred look.
• Authenticate: Select “Login with Google” and follow the browser prompts to sign in with your Google account. This securely links your terminal to Gemini’s AI capabilities.

4. Start Prompting!

Once authenticated, you’ll see the gemini > prompt. Now you can start interacting!

Examples for Laravel Developers:

• Explain Laravel Code:

gemini > Explain this Laravel controller method: @app/Http/Controllers/UserController.php:store

(Use @ to reference files/folders. Gemini CLI will often auto-complete paths).

• Generate a Model & Migration:

gemini > Write a Laravel migration for a `products` table with columns: name (string, unique), description (text, nullable), price (decimal), stock (integer, default 0). Also, create a Product model with fillable properties.

• Debug a PHP Error:

gemini > I'm getting a `Target class [App\Services\PaymentService] does not exist.` error in my Laravel application. Here's my controller: @app/Http/Controllers/OrderController.php. What's wrong?

• Generate a Blade Component:

gemini > Create a simple Blade component for displaying a success alert message. It should accept a `$message` prop.

• Refactor Code:

gemini > Refactor this PHP code to use a more modern Laravel approach: @app/Helpers/OldHelper.php

• Summarize a Project Folder:

gemini > Give me a summary of the `app/Models` directory and the relationships between the models.

Tips for Effective Usage:

• Be Specific: The more context and detail you provide in your prompt, the better the output.
• Use @ for Context: Leverage the @ symbol to include specific files, directories, or even parts of files in your prompt’s context.
• Review and Refine: AI-generated code is a starting point, not always a final solution. Always review, test, and refine the output to fit your exact needs and project standards.
• Explore Commands: Type /help within the Gemini CLI to see a list of available commands and shortcuts.

Conclusion

Google Gemini CLI is a powerful addition to the developer ecosystem, offering Laravel developers an intelligent co-pilot directly in their terminal. While not strictly “required,” embracing such AI-powered tools can significantly boost productivity, enhance code quality, and make the development process more enjoyable. For a web and mobile development business like Macronimous.com, integrating tools like Gemini CLI can translate directly into faster delivery, higher quality, and a more competitive edge in the market.

Start experimenting today, and unlock a new dimension of efficiency in your Laravel development journey!

The post Google Gemini CLI for Laraval development: Your New AI Co-Pilot in PHP programming first appeared on Macronimous Blog.