How to Build an MCP Server in PHP

What is an MCP Server?

An MCP server implements the Model Context Protocol, allowing AI agents to call tools via Streamable HTTP or SSE transports. Fast.io'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: Fast.io Workspaces, Fast.io Collaboration, and Fast.io AI.

Practical execution note for mcp-server-php: define a baseline process, assign ownership, and document fallback behavior when dependencies fail. Run a pilot with a small team, collect concrete metrics, and compare throughput, error rate, and review time before broad rollout. After rollout, keep a living checklist so future contributors can repeat the workflow without re-learning critical constraints.

Why PHP and Laravel for MCP Servers?

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.

Practical execution note for mcp-server-php: define a baseline process, assign ownership, and document fallback behavior when dependencies fail. Run a pilot with a small team, collect concrete metrics, and compare throughput, error rate, and review time before broad rollout. After rollout, keep a living checklist so future contributors can repeat the workflow without re-learning critical constraints.

Project Setup

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

Practical execution note for mcp-server-php: define a baseline process, assign ownership, and document fallback behavior when dependencies fail. Run a pilot with a small team, collect concrete metrics, and compare throughput, error rate, and review time before broad rollout. After rollout, keep a living checklist so future contributors can repeat the workflow without re-learning critical constraints.

Add one practical example, one implementation constraint, and one measurable outcome so the section is concrete and useful for execution.

Implementing the MCP Router

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.

Practical execution note for mcp-server-php: define a baseline process, assign ownership, and document fallback behavior when dependencies fail. Run a pilot with a small team, collect concrete metrics, and compare throughput, error rate, and review time before broad rollout. After rollout, keep a living checklist so future contributors can repeat the workflow without re-learning critical constraints.

Laravel Queues for Agent Tasks

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.

Practical execution note for mcp-server-php: define a baseline process, assign ownership, and document fallback behavior when dependencies fail. Run a pilot with a small team, collect concrete metrics, and compare throughput, error rate, and review time before broad rollout. After rollout, keep a living checklist so future contributors can repeat the workflow without re-learning critical constraints.

Validation and Security

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.

Practical execution note for mcp-server-php: define a baseline process, assign ownership, and document fallback behavior when dependencies fail. Run a pilot with a small team, collect concrete metrics, and compare throughput, error rate, and review time before broad rollout. After rollout, keep a living checklist so future contributors can repeat the workflow without re-learning critical constraints.

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.

Deployment and Testing

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"}'

Practical execution note for mcp-server-php: define a baseline process, assign ownership, and document fallback behavior when dependencies fail. Run a pilot with a small team, collect concrete metrics, and compare throughput, error rate, and review time before broad rollout. After rollout, keep a living checklist so future contributors can repeat the workflow without re-learning critical constraints.

Add one practical example, one implementation constraint, and one measurable outcome so the section is concrete and useful for execution.