symfony-mcp-server

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 StreamableHTTP and/or Server-Sent Events (SSE) transport, providing a secure and controlled integration methods.

Why not 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: StreamableHTTP or SSE offers better control over the communication channel between LLM clients and your application

By implementing the MCP server with StreamableHTTP or 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 StreamableHTTP and/or 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 StreamableHTTP and/or Server-Sent Events (SSE) integration
• Implementation of tools, resources and prompts compliant with Model Context Protocol specifications
• Support of streaming tools with progress notifications
• Support different types of tool results such as Text, Image, Audio or Resource
• Adapter-based design architecture with Pub/Sub messaging pattern
• Sampling support: Tools can request LLM assistance during execution for complex reasoning tasks
  • Dynamic model selection with preferences (cost, speed, intelligence)
  • Multi-message conversations with context preservation
  • Automatic capability detection and graceful fallback
  • Integration with tools, prompts, and resources

Requirements

• PHP >=8.2
• Symfony >=6.4

Installation

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

   klp_mcp_server:
       enabled: true
       server:
           name: 'My MCP Server'
           version: '1.0.0'
       default_path: 'mcp'
       ping:
           enabled: true  # Read the warning section in the default configuration file before disable it
           interval: 30
       server_providers: ['streamable_http','sse']
       sse_adapter: 'cache'
       adapters:
           cache:
               prefix: 'mcp_sse_'
               ttl: 100
       tools:
           - KLP\KlpMcpServer\Services\ToolService\Examples\HelloWorldTool
           - KLP\KlpMcpServer\Services\ToolService\Examples\ProfileGeneratorTool
           - KLP\KlpMcpServer\Services\ToolService\Examples\StreamingDataTool
           - KLP\KlpMcpServer\Services\ToolService\Examples\VersionCheckTool
       prompts:
           - KLP\KlpMcpServer\Services\PromptService\Examples\HelloWorldPrompt
       resources:
           - KLP\KlpMcpServer\Services\ResourceService\Examples\HelloWorldResource
       resources_templates:
           - KLP\KlpMcpServer\Services\ResourceService\Examples\McpDocumentationResource
   

   For more detailed explanations, you can open the default configuration file

2. Install the package via Composer:

   composer require klapaudius/symfony-mcp-server
   

3. Add routes in your config/routes.yaml

klp_mcp_server:
    resource: '@KlpMcpServerBundle/Resources/config/routes.php'
    type: php

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

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

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 .

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 or Prompts

The package provides convenient commands

• to generate new tools:

php bin/console make:mcp-tool MyCustomTool

• to generate new prompts:

php bin/console make:mcp-prompt MyCustomPrompt

Those commands:

• Handles various input formats (spaces, hyphens, mixed case)
• Automatically converts the name to the proper case format
• Creates a properly structured class in src/MCP/Tools or src/MCP/Prompts
• Offers to automatically register items in your configuration (config/packages/klp_mcp_server.yaml)

Testing MCP Tools or Prompts

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

# Test a specific tool interactively
php bin/console mcp:test-tool MyCustomTool

# Test a specific prompt interactively
php bin/console mcp:test-prompt MyCustomPrompt

# List all available tools
php bin/console mcp:test-tool --list

# List all available prompts
php bin/console mcp:test-prompt --list

# Test with specific JSON input
php bin/console mcp:test-tool MyCustomTool --input='{"param1":"value"}'

# Test with specific arguments
php bin/console mcp:test-prompt MyCustomPrompt --input='{"topic":"AI","tone":"professional"}'

This helps you rapidly develop and debug tools by:

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

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

For prompts creation: Here

Resources

The package provides a flexible resource management system that allows you to store and retrieve resources from different providers (file system, database, etc.).

Configuration

Configure resources in your config/packages/klp_mcp_server.yaml file:

klp_mcp_server:
    # ...
    resources:
        - App\MCP\Resources\MyCustomResource
    resources_templates:
        - App\MCP\Resources\MyCustomResourceTemplate

Usage

Creating Custom Resource

use KLP\KlpMcpServer\Services\ResourceService\ResourceInterface;

class MyCustomResource implements ResourceInterface
{
    // Resource implementation
}

Then register your resource in the configuration:

klp_mcp_server:
    # ...
    resources:
      - App\MCP\Resources\MyCustomResource

Creating Custom Resource Template

You can create custom resource templates by implementing the ResourceTemplateInterface:

use KLP\KlpMcpServer\Services\ResourceService\ResourceTemplateInterface;

class MyCustomResourceTemplate implements ResourceTemplateInterface
{
    // Implement the required methods
}

Then register your resource template in the configuration:

klp_mcp_server:
    # ...
    resources_templates:
      - App\MCP\Resources\MyCustomResourceTemplate

For deep diving into resources' management, please take a look at dedicated documentation Here

Visualizing with Inspector

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

# Run the MCP Inspector without installation
npx @modelcontextprotocol/inspector node build/index.js

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, chose the protocol and enter the corresponding endpoint url

3. Connect and explore available items visually

Advanced Features

Pub/Sub Architecture with Adapters

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

1. Publisher (Server): When clients send requests (e.g. /messages endpoint for SSE connection), 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:

klp_mcp_server:
    # ...
    sse_adapter: 'redis'
    adapters:
        redis:
            prefix: 'mcp_sse_'  # Prefix for Redis keys
            host: 'localhost'   # Change it as needed
            ttl: 100            # Message TTL in seconds

Roadmap

Our development roadmap outlines the planned enhancements and features for upcoming releases:

• Enhanced Protocol Support: Continued improvements to StreamableHTTP implementation and stay up to date with newer specifications
• ✅ Sampling Feature Implementation: Complete implementation of MCP sampling allowing tools to request LLM assistance

For detailed discussions about upcoming features and to contribute your ideas, please visit the Discussion section. Community feedback plays a crucial role in shaping our development priorities.

MCP Registries referencing

https://mcpreview.com/mcp-servers/klapaudius/symfony-mcp-server

https://mcp.so/server/symfony-mcp-server/klapaudius

Credits

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

License

This project is distributed under the MIT license.