Prisma PHP MCP Server

Turn your PHP application into a toolbox for AI agents. Define tools with #[McpTool], and let LLMs call your code, database, and services safely.

Getting Started

Your Prisma PHP project comes pre-configured with the Model Context Protocol.

src/Lib/MCP/mcp-server.php

Entry point: HTTP transport & tool discovery

src/Lib/MCP/WeatherTools.php

Example implementation with attributes

terminal

$ php src/Lib/MCP/mcp-server.php
➜  Server running on http://127.0.0.1:4000/mcp
➜  Discovered 3 tools in 25ms

On boot, the server auto-discovers all classes annotated with #[McpTool] in your source directory.

Environment Variables

Variable	Default	Description
MCP_NAME	prisma-php-mcp	Server identifier for clients.
MCP_PORT	4000	Port to listen on.
MCP_PATH_PREFIX	mcp	URL prefix (e.g., /mcp).
MCP_JSON_RESPONSE	false	Enable plain JSON for browser debugging.
APP_TIMEZONE	UTC	Timezone for consistent timestamps.

.env

# .env configuration
MCP_NAME="prisma-php-mcp"
MCP_VERSION="0.1.0"
MCP_PORT=4000
MCP_JSON_RESPONSE=true

Authoring Tools

Decorate public methods with #[McpTool]. Use #[Schema] to type and validate parameters automatically.

src/Lib/MCP/WeatherTools.php

<?php

use PhpMcp\Server\Attributes\McpTool;
use PhpMcp\Server\Attributes\Schema;

final class WeatherTools
{
    #[McpTool(name: 'get-weather', description: 'Returns current temp for a city')]
    public function getWeather(
        #[Schema(type: 'string', minLength: 1, description: 'City name')]
        string $city
    ): string {
        // Your logic here...
        return "It is sunny in {$city}";
    }
}

Pro Tip

Split tools by domain (e.g., DbTools, UserTools). Keep methods single-purpose to improve Agent reliability.

Run & Integrate

Set your .env configuration.
Start the server. npm run dev runs it automatically.
Point your AI agent to http://localhost:4000/mcp.

Security Notice

Put your MCP behind auth (e.g., reverse proxy with JWT/API keys). Never expose dangerous tool methods without strict validation.

Benefits

Benefit	What it Means	Example
Typed, discoverable tools	Agents know exactly which functions exist.	#[McpTool(name: 'create-order')]
Fast integration	Expose existing PHP code in minutes.	Wrap service layer methods.
Safe execution	Input schemas + server-side validation.	Rejects malformed IDs.
AI-native workflows	Natural-language to action via business logic.	"Restock items" -> `InventoryTools`.

Common Usage Patterns

Domain	Typical Tools	What the Agent Can Do
POS	find-product, apply-discount	Build a sale from a description.
E-commerce	search-catalog, create-order	Conversational checkout & returns.
Ops / Admin	user-lookup, grant-role	Role changes & data pulls via prompts.

Database Integration

Here is a safe pattern for fetching data. We validate inputs using attributes and enforce authentication before querying Prisma.

src/Lib/MCP/OrdersTools.php

<?php

use PhpMcp\Server\Attributes\McpTool;
use PhpMcp\Server\Attributes\Schema;
use Lib\Prisma\Classes\Prisma;
use Lib\Auth\Auth;

final class OrdersTools
{
    #[McpTool(name: 'order-by-id', description: 'Fetch an order by public ID')]
    public function getOrder(
        #[Schema(type: 'string', minLength: 10)] 
        string $orderId
    ): array {
        
        $auth = Auth::getInstance();
        $user = $auth->getPayload(); // Enforce auth

        $order = Prisma::getInstance()->order->findFirst([
            'where'  => ['publicId' => $orderId],
            'select' => ['id' => true, 'total' => true]
        ]);

        if (!$order) throw new \RuntimeException('Not found');
        
        return $order;
    }
}

Testing & Debugging

Use the official Inspector to debug your server.

Start with MCP_JSON_RESPONSE=true.
Throw \RuntimeException for clean errors.