Symfony MCP Server

A powerful Symfony package to build a Model Context Protocol Server seamlessly

[//]: # () [//]: # ()

Overview

Symfony MCP Server is a powerful package designed to streamline the implementation of Model Context Protocol (MCP) servers in Symfony applications. This package utilizes Server-Sent Events (SSE) transport, providing a secure and controlled integration method.

Why SSE instead of STDIO?

While stdio is straightforward and widely used in MCP implementations, it has significant security implications for enterprise environments:

• Security Risk: STDIO transport potentially exposes internal system details and API specifications
• Data Protection: Organizations need to protect proprietary API endpoints and internal system architecture
• Control: SSE offers better control over the communication channel between LLM clients and your application

By implementing the MCP server with SSE transport, enterprises can:

• Expose only the necessary tools and resources while keeping proprietary API details private
• Maintain control over authentication and authorization processes

Key benefits:

• Seamless and rapid implementation of SSE in existing Symfony projects
• Support for the latest Symfony and PHP versions
• Efficient server communication and real-time data processing
• Enhanced security for enterprise environments

Key Features

• Real-time communication support through Server-Sent Events (SSE) integration specified in the MCP 2024-11-05 version (Streamable HTTP from 2025-03-26 version is planned)
• Implementation of tools and resources compliant with Model Context Protocol specifications
• Adapter-based design architecture with Pub/Sub messaging pattern

Requirements

• PHP >=8.2
• Symfony >=7

Installation

1. Create the configuration file config/packages/klp_mcp_server.yaml and paste into it:

   For more detailed explanations, you can open the default configuration file from that link.

2. Install the package via Composer:

3. Add routes in your config/routes.yaml

You're all done! Upon completing this setup, your project will include two new API endpoints:

• Streaming Endpoint for MCP Clients: GET /{default_path}/sse
• Request Submission Endpoint: POST /{default_path}/messages

Docker Setup (Optional)

The project includes a Docker setup that can be used for development. The Docker setup includes Nginx, PHP-FPM with Redis extension, and Redis server.

For detailed instructions on how to set up and use the Docker containers, please refer to the Development Guidelines.

Strongly Recommended

Enhance your application's security by implementing OAuth2 Authentication. You can use the klapaudius/oauth-server-bundle or any other compatible OAuth2 solution.

Basic Usage

Creating and Adding Custom Tools

The package provides convenient Artisan commands to generate new tools:

This command:

• Handles various input formats (spaces, hyphens, mixed case)
• Automatically converts the name to the proper case format
• Creates a properly structured tool class in src/MCP/Tools
• Offers to automatically register the tool in your configuration

You can also manually create and register tools in config/packages/klp_mcp_server.yaml:

Testing MCP Tools

The package includes a special command for testing your MCP tools without needing a real MCP client:

This helps you rapidly develop and debug tools by:

• Showing the tool's input schema and validating inputs
• Executing the tool with your provided input
• Displaying formatted results or detailed error information
• Supporting complex input types including objects and arrays

For deep diving into tools creation please take a look at dedicated documentation Here

Visualizing MCP Tools with Inspector

You can also use the Model Context Protocol Inspector to visualize and test your MCP tools:

This will typically open a web interface at localhost:6274. To test your MCP server:

1. Warning: symfony server:start CANNOT be used with this package because it cannot handle multiple PHP connections simultaneously. Since MCP SSE requires processing multiple connections concurrently, you must use one of these alternatives:

   • Nginx + PHP-FPM
   • Apache + PHP-FPM
   • Custom Docker setup
   • Any web server that properly supports SSE streaming
2. In the Inspector interface, enter your Symfony server's MCP SSE URL (e.g., http://localhost:8000/mcp/sse)
3. Connect and explore available tools visually

The SSE URL follows the pattern: http(s)://[your-web-server]/[default_path]/sse where default_path is defined in your config/packages/klp_mcp_server.yaml file.

Advanced Features

Pub/Sub Architecture with SSE Adapters

The package implements a publish/subscribe (pub/sub) messaging pattern through its adapter system:

1. Publisher (Server): When clients send requests to the /messages endpoint, the server processes these requests and publishes responses through the configured adapter.

2. Message Broker (Adapter): The adapter maintains message queues for each client, identified by unique client IDs. This provides a reliable asynchronous communication layer.

3. Subscriber (SSE Connection): Long-lived SSE connections subscribe to messages for their respective clients and deliver them in real-time.

This architecture enables:

• Scalable real-time communication
• Reliable message delivery even during temporary disconnections
• Efficient handling of multiple concurrent client connections
• Potential for distributed server deployments

Redis Adapter Configuration (Optional)

A Redis adapter can be configured as follows:

Roadmap

We are committed to actively pursuing the following key initiatives to enhance the package's functionality and ensure compliance with evolving standards.

• Core Features:
  • Resources implementation compliant with MCP specification.
  • Prompts implementation compliant with MCP specification.
  • Support for Streamable HTTP (as specified in MCP 2025-03-26 version).
• Additional Adaptaters:
  • Support for more Pub/Sub adapters (e.g., RabbitMQ).

Credits

• Boris AUBE and all contributors
• Inspired by OP.GG/laravel-mcp-server

License

This project is distributed under the MIT license.