MCP Bundle

Creating MCP Capabilities

MCP capabilities are registered using PHP attributes on services: every service carrying one of the MCP attributes is picked up automatically at container compile time. In a default Symfony application (with autoconfiguration enabled and the classes in src/ registered as services) it is enough to add the attribute to a class.

1
2
3
4
5
6
7
8
9
10

use Mcp\Capability\Attribute\McpTool;

class CurrentTimeTool
{
    #[McpTool(name: 'current-time')]
    public function getCurrentTime(string $format = 'Y-m-d H:i:s'): string
    {
        return (new \DateTime('now', new \DateTimeZone('UTC')))->format($format);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12

use Mcp\Capability\Attribute\McpPrompt;

class TimePrompts
{
    #[McpPrompt(name: 'time-analysis')]
    public function getTimeAnalysisPrompt(): array
    {
        return [
            ['role' => 'user', 'content' => 'You are a time management expert.']
        ];
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

use Mcp\Capability\Attribute\McpResource;

class TimeResource
{
    #[McpResource(uri: 'time://current', name: 'current-time')]
    public function getCurrentTimeResource(): array
    {
        return [
            'uri' => 'time://current',
            'mimeType' => 'text/plain',
            'text' => (new \DateTime('now'))->format('Y-m-d H:i:s')
        ];
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

use Mcp\Capability\Attribute\McpResourceTemplate;

class TimeResourceTemplate
{
    #[McpResourceTemplate(uriTemplate: 'time://{timezone}', name: 'time-by-timezone')]
    public function getTimeByTimezone(string $timezone): array
    {
        $time = (new \DateTime('now', new \DateTimeZone($timezone)))->format('Y-m-d H:i:s T');
        return [
            'uri' => "time://$timezone",
            'mimeType' => 'text/plain',
            'text' => $time
        ];
    }
}

1
2
3
4
5
6
7
8

#[McpTool(name: 'my-tool')]
class MyTool
{
    public function __invoke(string $param): string
    {
        // Implementation
    }
}

1
2
3
4
5
6
7
8

class MyTools
{
    #[McpTool(name: 'tool-one')]
    public function toolOne(): string { }

    #[McpTool(name: 'tool-two')]
    public function toolTwo(): string { }
}

MCP Apps

MCP Apps let a tool return an interactive HTML screen (an "app") that the host renders in a sandboxed iframe instead of plain text — for example a dashboard, a form, or a record viewer. The bundle registers the underlying UI resource for you and enables the MCP Apps server extension, so you only write the markup.

A single class is the whole app (similar to a Symfony UX LiveComponent): the #[AsMcpApp] attribute carries the linked tool's identity (name/description) and the HTML shell (template), the constructor carries service dependencies, and a handler method (render by default) produces the tool result:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// src/Mcp/WeatherApp.php
use Symfony\AI\McpBundle\Attribute\AsMcpApp;

#[AsMcpApp(
    uri: 'ui://weather',
    name: 'get_weather',                 // the linked tool's name (model-facing)
    title: 'Weather',
    description: 'Show the weather for a city as an interactive dashboard.',
    template: 'mcp/weather.html.twig',
)]
class WeatherApp
{
    public function __construct(private WeatherClient $weather)
    {
    }

    // The returned value is the tool result, delivered to the iframe's JS render(model).
    // The input schema is derived from the method signature.
    public function render(string $city): array
    {
        return ['summary' => $this->weather->summaryFor($city)];
    }
}

The template extends the bundle's base template, which implements the MCP Apps postMessage handshake, iframe size reporting and a render(model) hook:

1
2
3
4
5
6
7
8
9
10
11
12
13

{# templates/mcp/weather.html.twig #}
{% extends '@Mcp/app/base.html.twig' %}

{% block style %}.card { font: 1rem system-ui; }{% endblock %}
{% block body %}<div id="root" class="card"></div>{% endblock %}

{% block app_script %}
    // Called with the linked tool's result. The iframe shell is static HTML; the per-request
    // data arrives at runtime via the tool-result message, not through Twig.
    function render(model) {
        document.getElementById('root').textContent = model.summary;
    }
{% endblock %}

The bundle registers the UI resource (with the required _meta.ui descriptor marker), registers the tool with its ui link auto-set to this app (resourceUri plus visibility [model, app]), and enables the MCP Apps extension. uri defaults to ui://<kebab-class-name>; the tool name defaults to that URI slug with dashes replaced by underscores, and the handler method defaults to render (set the method argument to use another). The tool is registered only when the handler method exists — an app without it is a static, tool-less screen.

The base template exposes the blocks title, head, style, body and app_script (override render(model) / onToolInput(params) there), plus sendRpc, callTool and openLink JavaScript helpers. The default render(model) implements the HTML-over-the-wire path described below, and interactions are wired declaratively via data-call / data-open attributes (see Interactive apps below) — so most apps write no JavaScript at all; override app_script only for a fully JS-driven UI.

The template form requires symfony/twig-bundle. For a dynamic shell, omit template and give the class an __invoke(): TextResourceContents method instead (inject Symfony\AI\McpBundle\App\McpAppRenderer to render Twig with your own context); that method then owns the returned content and its _meta.ui.

You can declare CSP and permission requirements for the iframe directly on the attribute:

1
2
3
4
5
6
7
8

#[AsMcpApp(
    uri: 'ui://weather',
    name: 'get_weather',
    template: 'mcp/weather.html.twig',
    prefersBorder: true,
    cspConnect: ['https://api.weather.example.com'],
    geolocation: true,
)]

The MCP Apps extension is enabled automatically as soon as one #[AsMcpApp] class exists. Use the apps.enabled option to force it on or off:

1
2
3
4

# config/packages/mcp.yaml
mcp:
    apps:
        enabled: true # null (default) = auto-enable when an app is registered; true/false forces it

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

#[AsMcpApp(
    uri: 'ui://weather',
    name: 'get_weather',
    template: 'mcp/weather.html.twig',       // the static iframe shell
    toolTemplate: 'mcp/_weather.html.twig',   // rendered into the tool result's `html`
)]
class WeatherApp
{
    public function __construct(private WeatherService $weather)
    {
    }

    // @return array{forecast: Forecast} — the Twig context, not HTML
    public function render(string $city): array
    {
        return ['forecast' => $this->weather->forecastFor($city)];
    }
}

1
2
3
4

{# templates/mcp/weather.html.twig #}
{% extends '@Mcp/app/base.html.twig' %}
{% block style %}.card { font: 1rem system-ui; }{% endblock %}
{# body defaults to <div id="root"></div>; the rendered `html` is injected there #}

1
2
3
4
5
6
7
8
9

use Symfony\AI\McpBundle\Attribute\AsMcpAppTool;

// ... on the same #[AsMcpApp] class, alongside render() ...

#[AsMcpAppTool(name: 'set_unit', template: 'mcp/_weather.html.twig', appOnly: true)]
public function setUnit(string $city, string $unit): array
{
    return ['forecast' => $this->weather->forecastFor($city, $unit)];
}

1
2
3
4

<button data-call="set_unit" data-arg-city="{{ city }}" data-arg-unit="celsius">°C</button>

{# the result HTML lands in #root; the search form below re-runs its tool on submit #}
<form data-call="get_weather"><input name="city"><button>Go</button></form>

Transport Types

The MCP Bundle supports two transport types for server communication:

• STDIO Transport - For command-line clients (e.g., symfony console mcp:server)
• HTTP Transport - For web-based clients and MCP Inspector using streamable HTTP connections

The HTTP transport uses the MCP SDK's StreamableHttpTransport which supports:

• JSON-RPC 2.0 over HTTP POST requests
• Session management with configurable storage (file/memory/cache/framework)
• CORS headers for cross-origin requests
• Proper MCP initialization handshake

DNS Rebinding Protection

By default, the MCP SDK protects the HTTP transport against DNS rebinding attacks by only accepting requests whose Origin/Host header points to localhost. To expose a public MCP server, configure the allowed hosts:

1
2
3

mcp:
    http:
        allowed_hosts: ['example.com', 'mcp.example.com'] # Replaces the default localhost allowlist

Alternatively, disable the protection entirely (for example when the server sits behind a reverse proxy that already validates the Host header) by setting it to false:

1
2
3

mcp:
    http:
        allowed_hosts: false

Session Storage

The MCP Bundle supports four types of session storage for the HTTP transport:

File Storage (default) - Stores sessions on the filesystem:

1
2
3
4
5
6

mcp:
    http:
        session:
            store: file
            directory: '%kernel.cache_dir%/mcp-sessions'
            ttl: 3600

Memory Storage - Stores sessions in memory (non-persistent):

1
2
3
4
5

mcp:
    http:
        session:
            store: memory
            ttl: 3600

PSR-16 Cache Storage - Stores sessions in any PSR-16 compliant cache (Redis, Doctrine, APCu, etc.):

1
2
3
4
5
6
7

mcp:
    http:
        session:
            store: cache
            cache_pool: 'cache.mcp.sessions' # Reference to your cache pool service (PSR-16)
            prefix: 'mcp-' # Optional prefix for cache keys
            ttl: 3600

By default, if you don't configure a custom cache pool, the bundle automatically creates cache.mcp.sessions as a PSR-16 wrapper around Symfony's default cache.app pool.

To use a custom cache backend, you need to configure a PSR-16 cache service in your config/services.yaml:

1
2
3
4
5
6
7

# config/services.yaml
services:
    # Define a custom PSR-16 cache service wrapping a PSR-6 pool
    cache.mcp.sessions:
        class: Symfony\Component\Cache\Psr16Cache
        arguments:
            - '@cache.app' # or '@my_redis_pool', '@my_doctrine_pool', etc.

This allows you to store sessions in Redis, a SQL database via Doctrine, or any other PSR-6 cache adapter. See the Symfony Cache documentation for more details on configuring cache pools.

Framework Storage - Uses Symfony's SessionHandlerInterface for session persistence:

1
2
3
4
5
6

mcp:
    http:
        session:
            store: framework
            prefix: 'mcp-' # Optional prefix for session keys
            ttl: 3600

This wraps the configured Symfony session handler (e.g. Redis, database, filesystem — whatever your application uses for HTTP sessions) with a JSON envelope for application-level TTL. Expired sessions are cleaned up lazily on read.