[Agent] Add MCP client bridge

[chr-hertel]

Q	A
Bug fix?	no
New feature?	yes
Docs?	yes
Issues	-
License	MIT

Lets an agent use the tools a remote MCP server advertises, on top of the client side the MCP bundle already owns.

An agent is not an MCP client: it never asks a server for a prompt or reads one of its resources, it only draws tools from it. And a server that answers tools/list and tools/call already is a toolbox, so it becomes one rather than a tool inside another - its arguments follow a JSON schema the server publishes instead of a PHP method signature, and nothing reflects on its tool definitions.

• Agent\Toolbox\AbstractToolbox holds what executing a tool call shares across toolboxes - looking the tool up, the tool call events, the error handling - leaving subclasses to say only how a call turns into a value. Agent\Toolbox\ChainToolbox offers the tools of several toolboxes to one agent. Toolbox moves onto the base class without a behavior change.
• New symfony/ai-mcp-tool bridge (src/agent/src/Bridge/Mcp): McpToolbox turns a toolset's tools/list into Tool definitions and forwards each call as tools/call. ClientToolset reaches a server through the SDK's own client for standalone use; ToolsetInterface keeps the bridge open for a connection managed elsewhere. The tool-name prefix sits on the toolbox, since it exists to keep two servers advertising the same tool name apart within one agent.
• symfony/ai-bundle gains an mcp_server tool entry next to service and agent, naming a connection configured under mcp.clients, so both bundles share one connection instead of opening a second one to the same server (a stdio server would otherwise be spawned twice). Each server becomes a toolbox next to the agent's local one, so remote tools compose with tools: true and with an explicit tool list alike.

What a remote toolbox also has to get right:

• An argument-less tool (properties: {}) is described without parameters, which OpenAI would otherwise reject as [].
• Structured output drops only the text block mirroring its JSON; genuine text, images and resources are kept.
• A transport that dies mid-session is dropped, so the next call reconnects; a server-returned error keeps the connection.
• An unreachable server contributes no tools instead of failing the run, and is skipped for retryAfter seconds (60 by default) rather than costing its connect timeout on every listing.
• A tool name offered by two toolboxes in a chain throws a ToolConfigurationException instead of silently running the first.
• The profiler lists tools from ai.profiler_toolbox services, so rendering any page no longer opens every MCP connection.

Refreshing a cached tool list in long-running processes is tracked separately in #2530.

Standalone:

$toolset = new ClientToolset(
    'filesystem',
    Client::builder()->build(),
    new StdioTransport('npx', ['-y', '@modelcontextprotocol/server-filesystem', '/tmp']),
);

$agent = new Agent($platform, 'gpt-4o-mini', toolbox: new McpToolbox($toolset));

In a Symfony application:

mcp:
    clients:
        research:
            servers:
                filesystem:
                    transport: stdio
                    command: ['npx', '-y', '@modelcontextprotocol/server-filesystem', '%kernel.project_dir%/var']

ai:
    agent:
        my_agent:
            tools:
                - { mcp_server: 'research.filesystem' }

Runnable as examples/toolbox/mcp.php.

[ineersa]

https://modelcontextprotocol.io/specification/2025-06-18/server/tools#structured-content

Structured content is returned as a JSON object in the structuredContent field of a result. For backwards compatibility, a tool that returns structured content SHOULD also return the serialized JSON in a TextContent block.

In older MCP versions as far as I remember SHOULD was MUST, so we shoudln't just drop content if structuredContent is present to support older versions.

[wachterjohannes]

Agreed, and worth being stricter than "SHOULD": a server pairing structuredContent with a genuine human-readable message, not just its JSON mirror, would silently lose it here. Keep the TextContent blocks rather than dropping them when structuredContent is present.

[ineersa]

Exception is thrown, but connection never removed.
This should set $this->connected to false, so on next call it would try to reconnect properly.

/**
 * Closes the connection. Idempotent, and reconnects transparently on the next call.
 */
public function disconnect(): void

docblock already says about this behavior.

[wachterjohannes]

Fixed on the current head, $connected is cleared before the SDK call.

[ineersa]

ClientToolset::getTools() throws ConnectionException and here we are propagating it.

So any slow/broken MCP server in a chain will kill whole chain, or will make it wait until timeout.

What I do in agent is just skipping broken servers, or ones who couldn't get connection on time, and ship partial catalog instead of failing all servers/tools.

[wachterjohannes]

Doesn't reproduce on the current head: McpToolbox::getTools() already catches and logs, returns an empty list instead of throwing, so a broken server can't take the rest of the chain down.

[ineersa]

[LOW]
Caching tools is fine for HTTP, but for long living processes it could be a problem.
I don't really know how to solve it, I'm caching tools and have /mcp reconnect command.

But ideally should maybe check tools/listChanged or somehow refresh tools list later.

[chr-hertel]

Created #2530 as follow up - scope is huge already, but def valid topic! 👍

[ineersa]

[LOW]
What if multiple toolboxes would have same name?
IMHO it's better to throw error in that case to let developer know than get first from list.

[wachterjohannes]

Agreed, a silent first-match hides a real misconfiguration. Throwing on a duplicate tool name across toolboxes surfaces it at wiring time instead of at the wrong tool getting called.

[wachterjohannes]

Solid feature, and the Toolbox/AbstractToolbox split holds up, verified behavior-preserving. ineersa's earlier review already has two real fixes in code with no reply, and two points still open, replied inline on both.

[wachterjohannes]

Both open points fixed and verified: ChainToolbox now throws on a tool-name collision, and McpToolbox only drops TextContent when mirrors() confirms it's a genuine JSON duplicate of structuredContent. Approving.

[tacman]

Thanks for this. It covers most of what I asked for in #2003, and ToolsetInterface turned out to be the right seam. I tried it on main right after the merge, using the case that started #2003: an app whose #[McpTool] services serve external agents and its own chat page. It's a newspaper archive, and I'd rather not maintain a duplicate #[AsTool] layer that drifts. The demo has the same duplication today: movie_search exists as both #[AsTool] and #[McpTool].

What worked

In the demo I pointed an mcp.clients entry at the app's own server and added an agent with tools: [{ mcp_server: 'self.demo' }]:

# mcp.yaml
clients:
    self:
        servers:
            demo:
                transport: stdio
                command: ['php', '%kernel.project_dir%/bin/console', 'mcp:server', 'demo']

With no other changes, the agent's toolbox lists demo_current-time, demo_movie_search and demo_movie_details, and executing them through it returns the server's results. Each call takes 0.05-0.10 s, plus about 0.3 s to spawn the child and list its tools. Under php-fpm that spawn is paid again on every request.

In-process instead of a transport

For an app talking to itself, the transport isn't needed. I implemented ToolsetInterface over the server's own Builder::buildStateless(), so tools/list and tools/call run through the same stateless protocol an HTTP client would hit: the same schema validation, result formatting and MCP App handler, with no child process. Results are identical to the stdio path at 0.00-0.03 s per call, and a real chat works through it. The core is:

$this->protocol ??= $this->builder->buildStateless();
$params['_meta'] = [
    RequestMeta::PROTOCOL_VERSION => ProtocolVersion::V2026_07_28->value,
    RequestMeta::CLIENT_CAPABILITIES => new \stdClass(),
];
$result = $this->protocol->handle(json_encode([...]), [
    McpHeader::PROTOCOL_VERSION => ProtocolVersion::V2026_07_28->value,
    McpHeader::METHOD => $method,
    McpHeader::NAME => $params['name'], // for tools/call
]);

The only way to wire it today is to decorate ai.toolbox.<agent>.mcp_toolset.<client>.<server>, so a stdio client has to be configured even though it never starts. Would a first-class form be welcome, say { mcp_server: 'demo' } with no client part, meaning "this app's own server mcp.servers.demo, in-process"? That would make "write the tool once as #[McpTool], use it from both the MCP server and the chat agent" a single line of config. I'm happy to open a PR.

Three things I ran into

1. An mcp_server-only list still injects every #[AsTool]. testMcpToolboxesSitNextToTheTaggedToolsOfTheLocalToolbox asserts this on purpose, but it contradicts the "tools are opt-in, a list is explicit" rule, and the demo's AGENTS.md says the mcp agent "has no local tools at all". It actually offers similarity_search, clock, wikipedia_search, wikipedia_article, movie_search alongside the remote tools. It changed real behavior in my test: asked about a movie "in this application's catalog", gpt-5-mini picked the local movie_search over demo_movie_search. There's currently no way to say "only these MCP servers".
2. The server's error message never reaches the model. When a server rejects a call (a missing required slug, a wrong argument type), the model only sees An error occurred while executing tool "demo_movie_details"., over stdio and in-process alike. ToolCallException::returnedError() doesn't implement ToolExecutionExceptionInterface, so FaultTolerantToolbox masks it. MCP tool errors are meant to go back to the model so it can correct the call, so passing through returnedError() at least (not connection failures) seems right.
3. A server that fails to list is silent. Returning no tools is the right call, but in practice my tools just disappeared and I found out from the log. That might be worth a profiler hint, or a line in the docs on where to look.

The prototype is one demo-only commit on top of main: tacman/ai@7de2c53 (the local_mcp agent plus App\Mcp\LocalServerToolset). I'm happy to turn any of the above into PRs, whichever is useful.

[OskarStark]

@tacman not sure about the issues itself, but I propose to create dedicates issues which can be tackled independently instead of a comment in a merged PR. Thanks

[tacman]

Thanks @OskarStark, done. Split into independent issues, three with PRs:

• [Agent][MCP] A tool error reported by an MCP server never reaches the model #2534: a tool error reported by an MCP server never reaches the model → [Agent][MCP] Show an MCP server's tool error to the model #2535
• [AI Bundle] An mcp_server-only tool list still injects every #[AsTool] service #2536: an mcp_server-only tool list still injects every #[AsTool] service → [AI Bundle] Keep an mcp_server-only tool list explicit #2537
• [AI Bundle] Let an agent use the tools of the application's own MCP server, in-process #2539: let an agent use the application's own MCP server in-process → [AI Bundle] Give an agent the tools of the application's own MCP server #2540
• [Agent][MCP] A server whose tool listing fails silently contributes no tools #2538: a server whose tool listing fails silently contributes no tools (discussion only, no PR)

#2534 also corrects one detail of my comment above: the invalid-argument cases I tested fail through callFailed(), not returnedError().