Download the PHP package nixphp/mcp without Composer

[!IMPORTANT] NixPHP is now NAF — "Not Another Framework".

This package continues as naf/mcp: github.com/nafphp/mcp · documentation · what changed and how to move

The old name collided with NixOS down to the shell, where the CLI binary was literally nix. This repository is archived and receives no further releases; nixphp/mcp stays on Packagist so existing installations keep working.

Note the plugin type. NAF discovers plugins by the Composer type naf-plugin. A package still declaring nixphp-plugin is not loaded — silently, with no error.

← Back to NixPHP

nixphp/mcp

Model Context Protocol (MCP) server implementation for NixPHP (Tools-first).

This plugin turns your NixPHP application into an MCP server that exposes Tools to AI clients such as ChatGPT.

🧩 Part of the official NixPHP plugin collection.

📦 Features

• JSON-RPC 2.0 compliant MCP endpoint
• Tool discovery via tools/list
• Tool execution via tools/call
• JSON Schema–driven tool descriptions
• Action-based tools (single tool, multiple behaviors)
• Long-running tools supported (blocking by design)
• No queues, no workers, no background state
• Simple, debuggable request flow

⚠️ This plugin currently operates in Tools-only mode. MCP Resources are currently not supported.

📥 Installation

The plugin auto-registers an MCP endpoint at:

The endpoint uses MCP Streamable HTTP in its minimal request/response form:

• JSON-RPC messages are sent via POST /mcp
• responses are returned as application/json
• server-initiated SSE streams are not opened yet
• GET /mcp returns 405 Method Not Allowed

Authentication

The endpoint is protected by Bearer token authentication by default. Tokens are stored file-based, so apps can use MCP without introducing database tables.

Default token file:

App configuration may override or disable this:

For internal or local-only projects authentication can be opened explicitly:

Create a token from application code:

If nixphp/cli is installed, the plugin registers token commands automatically:

Clients send the token as:

Tool Scopes

Tools may opt into scope checks by implementing ScopedToolInterface:

Supported scope patterns:

• *
• exact scopes such as articles:read
• prefix wildcards such as articles:*

Core Concept: Tools

Tools represent actions.

They:

• accept structured input (JSON Schema)
• execute application logic
• return structured results
• may read/write data internally

Examples:

• calculate a folder size
• analyze files
• summarize structured data

How the model interacts with your app (initialize)

On connection, the MCP server announces capabilities, not concrete tools.

Response (simplified):

capabilities.tools signals that this server supports MCP tools.

Tool Discovery (tools/list)

Clients explicitly request the available tools:

Response:

Example Tool: Folder Size

PHP Tool Implementation

How the model is calling the tool (tools/call)

JSON-RPC Request

Response

Action-Based Tools (Optional Pattern)

Tools may expose multiple behaviors via an action parameter:

This allows grouping related operations into a single tool while keeping schemas explicit.

This pattern is optional but recommended for more complex tools.

Storage & Filesystem Access

The plugin ships with a FilesystemStore utility.

Important notes:

• FilesystemStore is internal
• it is not exposed via MCP
• it is not a Resource API

Its purpose is to provide:

• safe, sandboxed filesystem access
• path traversal protection
• size limits
• predictable storage layout

Typical usage inside a tool:

Storage root (default):

About MCP Resources

This plugin currently does not expose MCP Resources (resources/read, resources/list, resources/write).

Reasoning:

• Tools already cover most required use cases
• Resources add conceptual overhead
• Most MCP clients primarily use tools

Resources may be added later as an extension.

Requirements

• PHP ≥ 8.3
• nixphp/framework ≥ 0.1.0

📄 License

MIT License.