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
11
12
13
14

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

class CurrentTimeTool
{
    #[McpTool(name: 'current-time')]
    public function getCurrentTime(
        #[Schema(description: 'PHP date format string. Default: Y-m-d H:i:s')]
        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
        ];
    }
}

Exposing capabilities

Carrying an attribute makes a class available; a server's capability lists decide which of them it exposes. Each list entry matches one of:

• '*' — every registered element of that kind;
• App\Mcp\SearchTool — that exact class name, or a service id for services registered under one;
• App\Mcp\Editor\ — every element whose class or service id starts with that namespace.

1
2
3
4
5
6
7
8
9
10

mcp:
    servers:
        default:
            registry:
                tools:
                    - 'App\Mcp\Tool\'          # a whole namespace
                    - 'App\Mcp\SearchTool'      # a single class
                    - 'app.mcp.legacy_lookup'    # a custom service id
                prompts: ['*']
                # resources, resource_templates and the app list default to [] — nothing exposed

When every kind comes from the same place, give registry the list directly instead of repeating it five times:

1
2
3
4
5
6
7

# config/packages/mcp.yaml
mcp:
    servers:
        default:
            registry: ['App\Mcp\']   # every kind, from this namespace
        everything:
            registry: '*'             # every kind, everywhere

registry: is required and must end up with at least one non-empty kind, and a pattern that matches no service fails at compile time — that is nearly always a typo. The reverse is allowed on purpose: a service carrying an MCP attribute that no server lists (a tool shipped by a third-party bundle, say) is simply not exposed. Run debug:mcp to see those listed under Not exposed by any server.

Multiple Servers

Because servers: is a map, one application can expose several MCP servers on different routes, each with its own identity and capability set. A common shape is a public server next to a privileged one:

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

# config/packages/mcp.yaml
mcp:
    servers:
        public:
            name: 'acme'
            transports: { http: true }
            http:
                path: /mcp
                allowed_hosts: ['acme.example']
            registry:
                tools: ['App\Mcp\Public\']
                resources: ['*']

        editors:
            name: 'acme-editors'
            instructions: 'Editorial tooling. Requires an authenticated editor.'
            transports: { http: true }
            http:
                path: /mcp/editors
            registry:
                tools: ['*']
                prompts: ['*']

Access control is plain Symfony security — the routes have distinct, stable paths, so a firewall or an access_control rule targets them directly:

1
2
3
4

# config/packages/security.yaml
security:
    access_control:
        - { path: ^/mcp/editors, roles: ROLE_EDITOR }

Each server gets its own registry, session store and HTTP route (named _mcp_endpoint_<name>), and its own services under mcp.server.<name>.*. Autowire a specific server with Mcp\Server $editorsServer.

If http.path is not set, it defaults to /mcp/<name>. That default is always derived from the server's name rather than from how many servers exist, so adding a second server can never silently move the first one's endpoint.

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 on a server as soon as it exposes at least one #[AsMcpApp] class, which its apps: list decides like any other capability:

1
2
3
4
5
6
7
8
9

# config/packages/mcp.yaml
mcp:
    servers:
        default:
            registry:
                apps: ['*']                  # every app; [] (the default) exposes none
        editors:
            registry:
                apps: ['App\Mcp\App\Editor\'] # only these

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

Each server declares its transports under transports::

• STDIO Transport (stdio, default false) - For command-line clients, served by symfony console mcp:server <name>. A process owns one STDIN/STDOUT pair, so one invocation serves exactly one server; the argument may be omitted when only one server enables STDIO.
• HTTP Transport (http, default true) - For web-based clients and MCP Inspector, using streamable HTTP connections on that server's route.

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
4
5

mcp:
    servers:
        default:
            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
4
5

mcp:
    servers:
        default:
            http:
                allowed_hosts: false

Session Storage

The MCP Bundle supports four types of session storage, configured per server. Every server needs its own storage — see the caution in Multiple Servers.

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

1
2
3
4
5
6
7

mcp:
    servers:
        default:
            session:
                store: file
                directory: '%kernel.cache_dir%/mcp-sessions/default' # defaults to this
                ttl: 3600

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

1
2
3
4
5
6

mcp:
    servers:
        default:
            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
8

mcp:
    servers:
        default:
            session:
                store: cache
                cache_pool: 'cache.mcp.sessions' # Reference to your cache pool service (PSR-16)
                prefix: 'mcp-default-' # Optional; defaults to "mcp-<name>-"
                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
7

mcp:
    servers:
        default:
            session:
                store: framework
                prefix: 'mcp-default-' # Optional; defaults to "mcp-<name>-"
                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.

The Modern Era

The 2026-07-28 revision drops the initialize handshake and the session that went with it: every request describes itself, so any worker can answer any request, and no long-running connection is needed.

Both eras are served on the same endpoint, with nothing to configure. The SDK builds a dispatcher per era, and the HTTP transport classifies every request before anything else looks at it: an envelope claiming a modern revision goes to the modern dispatcher, the initialize handshake and its session's later requests go to the other. A client picks nothing.

STDIO carries the handshake era alone — it has no per-request envelope to classify — so a server configured for both transports simply serves the modern era over HTTP only.

By default the HTTP endpoint supports every revision the SDK supports and negotiates with the client. Narrow the supported revisions through protocol_versions:

1
2
3
4
5
6
7
8

# config/packages/mcp.yaml
mcp:
    servers:
        api:
            protocol_versions: ['2025-11-25', '2026-07-28']
            http:
                path: /mcp
            registry: '*'

Each era takes what belongs to it. The modern revisions listed become the only ones that leg answers for; listing none of them refuses the modern era, leaving the handshake one alone. A handshake-era revision pins the handshake to exactly that one — the SDK either negotiates over everything it knows or is pinned to a single revision, so narrowing that era to a subset is rejected when the container is compiled.

The options below tune the modern-era leg. They are inert for handshake-era clients, which keep being served exactly as before. The converse does not hold: the modern leg is on for every server, including one written before the revision existed, and it drops things the handshake era offers.

1
2
3
4
5
6

# config/packages/mcp.yaml
mcp:
    servers:
        api:
            protocol_versions: ['2025-11-25'] # handshake era only, no modern leg
            registry: '*'

1
2
3
4
5
6

mcp:
    servers:
        api:
            request_state:
                key: '%env(MCP_REQUEST_STATE_KEY)%'
                ttl: 600 # seconds a minted state stays valid

1
2
3
4
5
6
7
8
9

mcp:
    servers:
        api:
            cache:
                ttl_ms: 5000
                scope: private # or "public"
                methods:
                    'tools/list': { ttl_ms: 60000, scope: public }
                    'resources/read': { ttl_ms: 1000 }

1
2
3
4
5
6
7

mcp:
    servers:
        api:
            subscriptions:
                bus: cache # none (default), memory, or cache
                cache_pool: 'cache.mcp.notifications'
                lifetime: 30.0 # seconds before the server closes a stream gracefully

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

use Mcp\Schema\Notification\ResourceUpdatedNotification;
use Mcp\Server\Subscription\NotificationBusInterface;

class DocumentSaver
{
    public function __construct(
        private NotificationBusInterface $apiNotificationBus,
    ) {
    }

    public function save(Document $document): void
    {
        // ...
        $this->apiNotificationBus->publish(new ResourceUpdatedNotification($document->uri()));
    }
}

Using a Client

Each client is available as Symfony\AI\McpBundle\Client\McpClientInterface, autowirable by the parameter name or with #[Target]. Its connections implement Symfony\AI\McpBundle\Client\ServerConnectionInterface:

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

use Symfony\AI\McpBundle\Client\McpClientInterface;
use Symfony\Component\DependencyInjection\Attribute\Target;

class ResearchService
{
    public function __construct(
        #[Target('research')] private McpClientInterface $client,
    ) {
    }

    public function run(string $path): string
    {
        $connection = $this->client->get('filesystem');

        foreach ($connection->getTools() as $tool) {
            // $tool is an Mcp\Schema\Tool
        }

        $result = $connection->callTool('read_file', ['path' => $path]);

        return $result->content[0]->text;
    }
}

A client is also iterable, which is handy for fanning a question out over every server it knows:

1
2
3

foreach ($this->client as $name => $connection) {
    $tools[$name] = $connection->getTools();
}

When exactly one client is configured, a plain McpClientInterface type hint resolves to it.

Connection Lifecycle

You never call connect(). A connection opens on its first request and closes on kernel reset, so resolving or iterating a client costs nothing until a request is actually made. That matters most for the STDIO transport, where connecting spawns a child process: a Messenger worker therefore starts a fresh process per message rather than carrying a stale one between them. Call disconnect() on a connection (or on the client, for all of them) to close early; it reconnects transparently afterwards.

Failures surface as bundle exceptions naming the client and server: Symfony\AI\McpBundle\Exception\ConnectionException when the handshake fails, and RemoteCallException when a request does, both implementing Symfony\AI\McpBundle\Exception\ExceptionInterface.

The HTTP transport uses the application's PSR-18 client (psr18.http_client, provided by symfony/http-client) unless the http_client option points at another service.

Server-initiated Requests

A remote server can ask the client to run a completion (sampling), to prompt the user (elicitation), or for the filesystem roots it may work in (roots). Point the matching option at a service implementing the SDK's callback interface; each capability is advertised only when a handler backs it, because advertising one without a handler earns a "method not found" from the client:

1
2
3
4
5
6
7
8
9
10

mcp:
    clients:
        research:
            roots: 'App\Mcp\RootsHandler'            # Mcp\Client\Handler\Request\RootsCallbackInterface
            sampling: 'App\Mcp\SamplingHandler'      # Mcp\Client\Handler\Request\SamplingCallbackInterface
            elicitation: 'App\Mcp\ElicitationHandler' # Mcp\Client\Handler\Request\ElicitationCallbackInterface
            capabilities:
                roots_list_changed: true
            servers:
                github: { transport: http, url: 'https://api.githubcopilot.com/mcp/' }

When the set of roots changes, tell the server with $connection->sendRootsListChanged().

Besides the tool, prompt and resource calls, a connection also exposes $connection->complete($ref, $argument) to complete one argument of a prompt or resource template, and $connection->getProtocolVersion() for the revision negotiated with that server (null until the first request opens the connection).

Logging notifications received from remote servers are written to the mcp logger channel; set forward_server_logs: false to drop them.