How to Build an MCP Server in PHP

An MCP server implements the Model Context Protocol, allowing AI agents to call tools via Streamable HTTP or SSE transports. Fastio's MCP server at mcp.fast.io exposes multiple tools for file management, AI chat, and collaboration.

PHP MCP servers extend this to legacy systems, like ERP or CRM databases. Agents POST JSON payloads to /mcp, the server routes to handlers, and returns results.

Key components:

• Session management: Durable state for auth tokens.
• Tool routing: Dispatch based on action.
• Async processing: Laravel queues for long tasks.

No Composer packages exist yet, so we build from scratch.

Helpful references: Fastio Workspaces, Fastio Collaboration, and Fastio AI.

PHP runs 72.0% of websites. Laravel adds queues, validation, and middleware for secure routing.

Benefits:

• Queues: Handle agent tasks asynchronously.
• Validation: Laravel rules for MCP payloads.
• Deployment: Easy on Apache/Nginx with Supervisor for queues.

Laravel queues process jobs reliably, perfect for agent workflows like file processing.

Install Laravel:

composer create-project laravel/laravel mcp-server-php
cd mcp-server-php

Add queue driver (Redis recommended):

composer require predis/predis

Configure .env:

QUEUE_CONNECTION=redis
MCP_SESSION_SECRET=your-secret-key

Create MCP controller:

php artisan make:controller McpController
php artisan make:job ProcessAgentTask

Define /mcp route in routes/api.php:

Route::post('/mcp', [McpController::class, 'handle']);

In McpController:

public function handle(Request $request)
{
  $payload = $request->validate([
    'jsonrpc' => 'required|string',
    'method' => 'required|string',
    'params' => 'array',
    'id' => 'string',
  ]);

$sessionId = $request->header('Mcp-Session-Id');

// Route to handler
  $response = $this->routeMethod($payload['method'], $payload['params'], $sessionId);

return response()->json($response);
}

Implement routeMethod to dispatch actions like 'auth/signin', 'storage/list'.

Use session storage for auth tokens.

Give Your AI Agents Persistent Storage

Fastio provides hosted MCP with 251 tools, 50GB free storage for agents, and built-in RAG. No credit card required. Built for mcp server php workflows.

Get Free Agent Tier

Offload heavy work to queues.

In controller:

ProcessAgentTask::dispatch($taskData)->onQueue('mcp');
return ['status' => 'queued', 'job_id' => $uuid];

ProcessAgentTask job:

public function handle()
{
  // Process task, e.g. query legacy DB
  $result = $this->legacySystem->process($this->data);
  // Store result in session or DB
}

Run queues:

php artisan queue:work --queue=mcp

Supervisor for production.

Laravel validators for MCP payloads.

Example for auth/signin:

'method' => 'required|in:auth/signin',
'params.email' => 'required|email',
'params.password' => 'required|min:8',

Middleware for rate limiting:

RateLimiter::for('mcp', function (Request $request) {
  return Limit::perMinute(60)->by($request->header('Mcp-Session-Id'));
});

Encrypt sessions, validate origins.

Document access rules, audit trails, and retention policies before rollout so staging results are repeatable in production. This avoids late surprises and helps teams debug issues with confidence.

Deploy to Forge/Vapor or VPS.

Nginx config for /mcp:

location /mcp {
  proxy_pass http://localhost:8000;
  proxy_set_header Mcp-Session-Id $http_mcp_session_id;
}

Test with curl:

curl -X POST http://your-server/mcp \\
  -H "Content-Type: application/json" \\
  -H "Mcp-Session-Id: test-session" \\
  -d '{"jsonrpc":"2.multiple","method":"auth/signin","params":{"email":"test@example.com","password":"pass"},"id":"1"}'