Core PHP MCP Server for Model Context Protocol

Overview

The Core PHP MCP Server is a minimal, high-performance implementation of the Model Context Protocol (MCP) written in plain PHP. It provides a lightweight HTTP server and toolkit to expose and manage model context endpoints, enabling applications and model orchestration layers to share, enrich, and consume context in a standardized way. Its design favors simplicity and extensibility so you can run MCP-compatible services without a heavy runtime or complex framework dependency.

This server is useful when you need low-latency, production-ready MCP endpoints for tasks such as context retrieval, context enrichment, tool orchestration, or integrating local resources with large language models. Because it’s implemented in core PHP, it fits into existing PHP hosting stacks (PHP-FPM, containers) and is straightforward to extend with custom providers, middleware, and persistence backends.

Features

• Lightweight HTTP MCP server implemented in plain PHP
• Simple setup: clone, composer install, run with built-in server or deploy via PHP-FPM/Nginx
• Extensible plugin points for context providers, middleware, and tools
• Example stores for in-memory and file-backed context persistence
• Production deployment patterns (Docker, PHP-FPM, Nginx) included
• Minimal external dependencies for easy maintenance and security auditing
• Basic logging and configurable runtime via environment variables

Installation / Configuration

Quick start (clone + composer):

# clone repository
git clone https://github.com/php-mcp/server.git
cd server

# install dependencies
composer install

# copy environment example and edit as needed
cp .env.example .env
# edit .env to configure HOST, PORT, LOG_LEVEL, storage path...

Run with PHP built-in server for local development:

# runs public/index.php as entrypoint
php -S 0.0.0.0:8080 -t public

Example environment variables (in .env):

MCP_HOST=0.0.0.0
MCP_PORT=8080
LOG_LEVEL=info
STORAGE_DRIVER=file     # options: memory, file, custom
STORAGE_PATH=/var/mcp/storage

Docker Compose example (development):

version: "3.7"
services:
  mcp:
    build: .
    ports:
      - "8080:8080"
    volumes:
      - ./storage:/var/mcp/storage
    environment:
      - MCP_PORT=8080
      - STORAGE_DRIVER=file

Production pattern (Nginx + PHP-FPM): run PHP-FPM with the same application code and configure Nginx to forward requests to /mcp/* to the PHP entrypoint. Example Nginx location:

location /mcp/ {
    try_files $uri /index.php$is_args$args;
    fastcgi_pass unix:/run/php/php-fpm.sock;
    fastcgi_param SCRIPT_FILENAME $document_root/index.php;
    include fastcgi_params;
}

Available Tools / Resources

Included examples and utilities to get started quickly:

• HTTP MCP server entrypoint (public/index.php) — minimal routing and request handling
• In-memory context store — useful for tests and ephemeral workloads
• File-backed context store — simple persistence for local deployments
• Example middleware — logging, basic auth, and input validation
• Sample client curl snippets and PHP client examples to call MCP endpoints
• Dockerfile and docker-compose for container-based runs
• Basic README and sample configuration files for common deployment scenarios

Repository and source: https://github.com/php-mcp/server

API Endpoints (common)

The server exposes a small set of MCP-oriented endpoints. Concrete paths and payloads may vary — check your instance’s OpenAPI or /mcp/.well-known on startup.

Example curl to add context:

curl -X POST "http://localhost:8080/mcp/context" \
  -H "Content-Type: application/json" \
  -d '{"id":"user:123","type":"user_profile","data":{"name":"Alex","prefs":["email"]}}'

Example curl to query context:

curl -X POST "http://localhost:8080/mcp/query" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-x","context_ids":["user:123"],"query":"recent purchases"}'

Use Cases

• Context-aware LLM requests: store and retrieve user-specific context (profiles, preferences, chat history) and serve it to model orchestration layers so responses are personalized and consistent.
• Tool orchestration: register tools (search, calendars, databases) and expose them through MCP endpoints so model controllers can invoke tools with shared context.
• Content enrichment pipelines: submit raw context to the server for preprocessing (embedding, metadata extraction) and retrieve enriched context for downstream models.
• Local or edge deployment for low-latency needs: run the server close to your application or data store (on-prem, private cloud, edge) to minimize round-trip times to model services.
• Testing and development: use the in-memory store for unit tests or CI pipelines to simulate MCP behavior without external dependencies.

Extending the Server

The server is intentionally modular. Common extension points:

• Add a custom storage driver by implementing the store interface and registering it in configuration.
• Add middleware to perform authentication, rate limiting, or request transformation.
• Add a custom tool provider to expose external services (databases, vector stores, search) through MCP.
• Wire the server into an existing orchestration layer to act as a context provider for model pipelines.

If you’re new to the project, start by running the built-in server, exercise the example endpoints with curl, then implement a small storage provider or middleware to learn the extension points.

Troubleshooting & Tips

• For production, prefer PHP-FPM + Nginx or container orchestration over the PHP built-in server.
• Use the file-backed storage for simple persistence, and move to a dedicated datastore (Redis, Postgres) via a custom driver when scaling.
• Keep logging level configurable and rotate logs in production to avoid disk growth.
• Run automated tests against the in-memory store to ensure deterministic behavior during CI.

This Core PHP MCP Server offers a compact, extensible foundation to implement MCP-compliant context services that integrate with modern model orchestration workflows.