Skip to content

MCP Server in PHP: 12 Simple Tools, One JSON File

5 min read Notes

MCP Server in PHP: 12 Simple Tools, One JSON File

An MCP server in PHP looks like overkill until the first time someone asks to change a link at 11pm. With a model wired to the server, the edit happens from a chat window, and the same validation runs as if it came from a form.

Code: Link-in-Bio-with-MCP-Server, MIT licensed.

The implementation in this project is worth reading because it stays small. An MCP server in PHP fits in one JSON-RPC endpoint, twelve tools and one content file, and it has no second admin path that drifts away from the first.

What an MCP server in PHP has to get right

Transport first. The endpoint accepts POST only and speaks JSON-RPC 2.0. A GET returns 405 with an Allow: POST header, which tells a misconfigured client what happened instead of dumping an HTML error page into its parser.

Authentication second. A bearer token lives in a file outside the web root, created with mode 0600, and every request is checked before any tool is dispatched. There is no anonymous mode to forget to disable.

Errors third. A tool that rejects input returns a JSON-RPC error with a message written for a human, not a stack trace. An agent can read “url must be absolute” and correct itself on the next call; a PHP notice gives it nothing to act on.

The twelve tools

The set is deliberately small: list sections, list links, read the whole content tree, create a link, update a link, move a link, delete a link, set visibility, update settings, preview, publish, and read the schema.

Two of them carry most of the value. preview renders the page from the current content without touching the cache, so an agent can show what a change will look like before committing it. publish writes the change and invalidates the rendered HTML cache in one step.

Twelve tools is about the limit where a model still picks the right one on the first try. An MCP server in PHP with twenty tools and overlapping names produces wrong calls, and each wrong call is a round trip.

Concurrency without a database

There is no database on this page, so the lock is a file lock and the version is a revision number in the JSON tree.

Every mutation reads the current revision, validates the whole tree, copies a backup, writes atomically under flock, appends to an audit log, and increments the revision. A client that sends a stale revision gets a rejection rather than an overwrite.

Validation covers the whole tree rather than the edited field. A link with a valid URL and an unknown icon name would render an empty slot, and the field-level check would have let it through.

Cache invalidation that survives a deploy

The rendered HTML cache key includes the content revision, a seed, the template name, every PHP source file and the public CSS and JS. Editing content changes the revision; deploying code changes the file hashes. Both invalidate without a manual purge, and neither needs a cron job.

That is the part most cache implementations get wrong on small sites. A cache keyed only on the content revision serves the old template after a deploy, and the bug appears as “the design reverted” until someone clears it by hand.

Metadata from the same tree

The meta tags, the Open Graph block, the JSON-LD profile object and the sitemap all read from the same content file as the visible page. Change the job title once and the search result, the social card and the structured data follow.

Two links in this catalogue cover the checks worth running after that change: auditing the head of a page without a browser, and counting URLs in a sitemap to catch a map that no longer parses.

Testing a page with no framework

195 unit tests, 16 HTTP checks and 76 browser checks, with the unit suite gated on full line coverage. The browser checks cover keyboard focus, the theme toggle and copy-to-clipboard, which are the parts that break silently in a hand-written page.

The HTTP layer is tested through a router that mirrors production rewrite rules, including /mcp, pretty URLs and dotfile denial. Testing against a different router than production is how a 404 in production passes a green suite.

Where this design stops

A single JSON file works for a page with dozens of links. At thousands of records the whole-tree validation becomes the bottleneck, and the atomic rewrite copies the file on every save.

The tools are also shaped for one editor and one page. Multi-user access would need per-token permissions, and the audit log would become a queryable table instead of a text file.

Neither limit matters for the size of project this targets, and staying under them is what keeps the page deployable by copying two files.

Background: the MCP specification and JSON-RPC 2.0.

Custom work

Need an API that does not exist yet?

Describe the task and the response format. We will estimate the endpoint, the integration and the maintenance.

Start a conversation