Building a remote MCP server in plain Laravel (no SDK): notes from a tax-hours app

PropHours is a tool for property owners to log their time spent on rental properties, crucial for tax purposes under various rules like the STR loophole and real estate professional status. Some users wanted to interact with their logs directly, prompting the creation of a remote Model Context Protocol server that can be accessed by AI assistants like ChatGPT. The server consists of a single Laravel controller without the need for an MCP SDK.

The server operates on a streamable HTTP transport using JSON-RPC 2.0 over a single POST endpoint. It provides four basic RPC methods: initialize for negotiating a protocol version, ping for returning an empty result, tools/list to retrieve tool definitions, and tools/call to execute a tool. The server also handles notifications and error handling, returning specific error codes for invalid requests or unavailable methods.

Security is a priority, with checks on the Origin header, request size, JSON structure, and method validation. OAuth is implemented using a discovery endpoint, dynamic client registration, and PKCE S256. Users register their assistants through dynamic client registration, and authorization requests are limited to 10 minutes. Access tokens expire after an hour, and refresh tokens are valid for 30 days.

To maintain data integrity, the server requires idempotent writes, meaning repeated calls with the same parameters should not result in duplicate entries. The request_id is used to track and prevent duplicate entries. Additionally, the server enforces rules and guidelines for the assistant to follow, ensuring accurate and ethical logging of work hours.