Announcement

The MCP driver for Kipchak

Mamluk · · 5 min read
The MCP driver for Kipchak

AI assistants are increasingly asked to act on a company’s data: to look up an order, check a stock level or open a support case. To do that, the assistant needs a defined way to call the systems that hold the data. The Model Context Protocol (MCP) is an open protocol for this. An API that speaks MCP describes its operations as tools, its data as resources and its reusable instructions as prompts, and any assistant that supports the protocol can use them.

The MCP driver lets a Kipchak API serve MCP. It is built on mcp/sdk, the official PHP SDK for the protocol, and it is free, under the MIT licence.

Tools are ordinary classes

A tool is a public method with an attribute. Its input schema is generated from the parameter types, and its description from the doc block:

use Mcp\Schema\ToolAnnotations;
use Mcp\Server\Capability\Attribute\McpTool;

final class StatusTools
{
    /**
     * Reports whether the API is running.
     */
    #[McpTool(name: 'status', annotations: new ToolAnnotations(readOnlyHint: true))]
    public function status(): array
    {
        return ['status' => 'alive'];
    }
}

Resources, resource templates and prompts are declared the same way, with #[McpResource], #[McpResourceTemplate] and #[McpPrompt]. Tool classes are built by the Kipchak container, so a constructor can ask for an entity manager, a cache or any other service the API already uses. The endpoint is one route:

$app->any('/mcp', \Kipchak\Driver\Mcp\Mcp::endpoint('default'));

Authentication stays where it is

An assistant that can call an API’s operations must be held to the same rules as any other caller. The MCP endpoint is an ordinary Kipchak route, so it sits behind the authentication middleware the API already uses, such as the JWKS or JWT middleware, and needs no second sign-in mechanism.

The driver passes the caller’s identity to the SDK: the token’s issuer, client and subject, and nothing else from the token. Where sessions are enabled, each session belongs to the caller who opened it. A tool that asks the user for input in the middle of a call receives a signed state that is bound to the request, the tool, its arguments and the caller, so a state issued to one caller does not verify for another.

One endpoint for both protocol eras

The protocol changed in its 2026-07-28 revision, which no longer needs a session. The driver serves clients on the earlier handshake revisions, up to 2025-11-25, and clients on 2026-07-28 from the same route. The driver is tested with the SDK’s own client, which lists and calls tools over HTTP on both revisions against an API running in worker mode.

Sessions are off by default. Each request then stands alone, so an API with several replicas needs no shared store. Where a client on an earlier revision needs a session, the driver keeps it in a cache from another Kipchak driver, such as Valkey.

Safe in worker mode

Kipchak runs on FrankenPHP in worker mode, where one PHP process serves many requests. The driver builds the MCP server once per worker and gives each request a transport of its own, so nothing about one caller reaches the next request. A configuration error stops the API when it starts, with a message naming the server and the setting, rather than when an assistant calls it.

In the starter project

New Kipchak projects include an example. Version 4.10 of the starter project serves /mcp with one read-only tool, status, which reports that the API is running. Like /status, the route needs no sign-in, because the tool reads no data. Any tool that reads or changes data must sit behind authentication, and the starter says so beside the route.

composer create-project kipchak/starter my-api

The SDK version

The driver requires mcp/sdk at exactly version 0.10.0. The SDK has not reached version 1.0, and its minor releases have changed its interfaces, so each SDK release reaches Kipchak users in a driver release that has passed the driver’s tests. Our commitment is that when the SDK publishes a security release, a driver release taking it follows within five working days. The dependencies of every Kipchak package are audited each day, so a new advisory is reported to us without waiting for someone to notice it.

Installation

composer require kipchak/driver-mcp

The driver needs version 1.6 or later of the Kipchak CLI, whose OpenAPI validator recognises the MCP endpoint as a protocol endpoint rather than a REST operation. The MCP driver documentation describes the configuration, authentication, sessions, signed request state and key rotation. The source is on GitHub, and the package is kipchak/driver-mcp on Packagist.

Share
← Back to the Journal

More from the Journal