[Agent][MCP] Auto-expose tools from a connected MCP server to the Agent Toolbox

[tacman]

Context

Following a Slack discussion with @chr-hertel: with api-platform/mcp (4.3) and the MCP Client now in mcp/sdk (impl #192, docs #259), the publisher side is in good shape. The consumer side still requires hand-written #[AsTool] wrappers per remote tool, duplicating names, descriptions, and schemas that the MCP server already advertises.

@ineersa (Illia Vasylevskyi) shared a working implementation that illustrates the gap:

• thin client: https://github.com/ineersa/re-search/blob/main/src/Research/Mcp/McpWebSearchClient.php
• per-tool wrapper: https://github.com/ineersa/re-search/blob/main/src/Research/Tool/WebSearchTool.php

The wrapper has to redeclare each tool's description because the Toolbox doesn't pull them from the server. Add a remote tool, edit PHP. Rename a description on the server, drift.

Proposal

A bridge that registers MCP-server tools into the Agent Toolbox at runtime, sourcing metadata from the server's tools/list response.

Sketch:

ai:
    agent:
        my_agent:
            mcp_servers:
                api_platform:
                    transport: http
                    url: 'https://shop.example.com/mcp'
                research:
                    transport: stdio
                    command: ['php', 'bin/mcp-research']

At boot (or first call), the bridge calls tools/list on each server, builds Tool metadata from the response, and adds a generic RemoteMcpTool executor to the Toolbox. The Agent sees these alongside #[AsTool]-tagged services with no per-tool PHP.

Open questions worth deciding in the issue

1. Discovery timing — boot-time (cache friendly, stale on server changes) vs lazy on first call vs tools/listChanged notifications.
2. Naming collisions across servers — prefix by server alias (api_platform.search_products) seems safest.
3. Auth passthrough for HTTP transports — user token, service token, or per-server config.
4. Failure mode when a server is unreachable — skip silently, log, or fail the agent call.

Claude and I are happy to draft the bridge against the mcp/sdk client if the direction is welcome.

Related: #41, #1259.

[ineersa]

I like this idea.

So you would do something like this:

• cycle through registered MCP servers
• create connection for each
• grab tools (can be expanded later for prompts, resources and so on)

In theory this can be done in parallel, if it's a worker maintaining connection might be good idea too after connect, it will bring pretty substantial performance boost.

As for caching, I'm more familiar with coding agents, they don't have any issues as it's pretty much simple event loop, so they just store that in memory and reconnect every time new session starts. For web and PHP this might be trickier, as not everyone runs in worker mode, so I guess Symfony Cache should be used here.

As for the naming conventions, mcp__<server_name>__<tool_name> I've seen few times, and it's what Claude is using. MCP+server name + tool name in any format works.

Auth passthrough for HTTP transports — user token, service token, or per-server config.

That's something I have no idea, I still think it's shouldn't be MCP concern, and idk how people use it. Usually it's just an token in MCP JSON config which passed through to a server as a header?
OAuth is tricky with MCPs.

Failure mode when a server is unreachable — skip silently, log, or fail the agent call.
I would just skip it on startup (maybe add some log), if connection dropped mid session try to reconnect with some form of exponential backoff, if not working remove tools from a list for LLM till reconnected.
If tool call fails, retry once on session expiry, otherwise surface error to the LLM.

This would be first step to proper MCP tool calling for an agent.

P.S. Forgot to mention, as pretty much everyone nowadays went to deferred tools loading, this will be great background for this feature in a future!

[tacman]

This would be first step to proper MCP tool calling for an agent.

ApiPlatform exposes an MCP so I can say to Claude, "create a Container entity called Box 3 in the Tenant Smithsonian".

When "Smithsonian" is logged in, I want them to be able to say "Create a Container called Box 3".

Then with ApiPlatform or Meilisearch, both expose MCPs, "how many birth certificates between 1850 and 1900 do we have?"

Gut feeling is that the MCP can already do that. Sometimes I wonder if I'm mis-understanding MCPs, or trying to use them the wrong way. But those 2 use cases, basically a natural language wrapper around a search, feels like something valuable.

[ineersa]

MCP is a protocol, and tools is only a part of a protocol.

Tools come from server functions as background, and they can be used without MCPs or with them.

Pretty much tools is what you pass in tools: [] each turn to LLM, instruct models trained to produce tool calls in some format, depending on chat template.

So for example if you have a tool create_entity(name: string), you need to pass it to LLM when doing turn, for example:

{
  "model": "gpt-5.3",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant. Use tools when appropriate."
    },
    {
      "role": "user",
      "content": "Create new entity TestingBlock."
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "create_entity",
        "description": "Create a new entity by name.",
        "parameters": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "Name of the entity to create."
            }
          },
          "required": ["name"],
          "additionalProperties": false
        }
      }
    }
  ],
  "tool_choice": "auto"
}

Instruct models trained to produce tool calls in such situations, and depending on how they do it and chat template they MIGHT produce something like this (Qwen example):

<function=create_entity>
    <parameter=name>TestingBlock</parameter>
</function>

Inference engine afterwards (OpenAI server or Antropic server or w.e.) parses it accordingly and produces tool call back:

{
  "id": "chatcmpl_abc123",
  "object": "chat.completion",
  "created": 1777286400,
  "model": "gpt-5.3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_001",
            "type": "function",
            "function": {
              "name": "create_entity",
              "arguments": "{\"name\":\"TestingBlock\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 18,
    "total_tokens": 60
  }
}

Current Toolbox/Platform implementation covers that, but it's missing connection between MCP servers tools and translation/execution of them into tools:[] array.

ApiPlatform exposes an MCP so I can say to Claude, "create a Container entity called Box 3 in the Tenant Smithsonian".

Claude has deferred MCP tools system, how it works on high level.

1. On session start they connect to all MCPs, collect information about tools, resources etc. Connections are stored for future use, there is a hook which keeps them alive and reconnects. Tools are cached. ToolsListChanged event from MCP server updates tool list.

2. All tools split into 2 categories: deferred and not. All built in tools are not deferred, all MCP tools by default deferred. How it looks for a model on 1st turn:

tools: [                                                                                                                                                                                                                     
     { name: "Read", description: "...", input_schema: {...} },           // ← full schema                                                                                                                                      
     { name: "Bash", description: "...", input_schema: {...} },           // ← full schema                      
     { name: "Edit", description: "...", input_schema: {...} },           // ← full schema                      
     { name: "ToolSearch", description: "...", input_schema: {...} },     // ← full schema                      
     // ... other built-in tools ...                    

     { name: "mcp__Slack__send_message", defer_loading: true },           // ← STUB - no schema!                
     { name: "mcp__Slack__list_channels", defer_loading: true },          // ← STUB                                               
     // ... 50 more MCP tools, all defer_loading: true ...                                                      
   ]

3. As you can see they never expose full tools for MCPs right away, this is done because people implement servers with crazy amounts of tools and something like Playwright MCP with 81 tools could easily eat 30k context each turn.
   But how model see tools? The API strips the defer_loading: true tools from the model's actual prompt. So the model only sees built-in tools + ToolSearch.

4. <system-reminder> message is added to conversation on session start with all available tools in format mcp__<server>__<tool>. This way model kinda can see what it can discover via ToolSearch.

5. When the model decides it needs to message Slack, it calls:

{                                                    
    "tool_use": {                                      
    "name": "ToolSearch",                            
    "input": { "query": "slack send message", "max_results": 5 }                                             
    }                                                  
}                                                    

ToolSearch then searches through all deferred tools and finds mcp__Slack__send_message and returns a result with a tool_reference block:

{                                                    
    "tool_result": {                                   
    "tool_use_id": "...",                            
    "content": [                                     
        { "type": "tool_reference", "tool_name": "mcp__Slack__send_message" }                                  
    ]                                                
    }                                                  
}                                                    

6. The Anthropic API server sees the tool_reference block, looks up mcp__Slack__send_message in the deferred tools, and injects the full schema into the model's context. The model now sees:

  [Previously deferred tool loaded]                    
  name: mcp__Slack__send_message                       
  description: Send a message to a Slack channel       
  parameters: { channel: string, text: string, ... }   

Now model see tool as it would see it normally and can use it just the same way as normal tool.

As for the issue itself, current Agent and Toolbox system is missing MCP client implementation and translation layer between MCP -> Toolbox.

Because of that this is first step into implementation of MCP tools/client in a future.

[tacman]

Thanks for the detailed explanation!

[aszenz]

@chr-hertel Is MCP tool support in Agent toolbox a blocker for v1.0 #1301

It's listed as:

COULD MCP support, agent acting as

[wachterjohannes]

@chr-hertel gentle ping, this question about v1.0 blocking is still open.

[ineersa]

I have that implemented in my coding agent, could try to port it maybe?
My version is quite complicated, would be interesting to try to simplify it.

P.S. code and overview AI generated

The pipeline

1. Raw discovery — src/CodingAgent/Mcp/Client/McpConnectionManager.php
discover() connects to each enabled server, calls listTools(), returns serverName → {status, transport, tools}.

2. Discovery → catalog — src/CodingAgent/Mcp/Catalog/McpToolCatalogBuilder.php
Converts raw results to McpToolCatalogDTO: MCP name → Hatfield name mapping, include/exclude filters, cross-server dedupe, config hash.

3. Persist — src/CodingAgent/Mcp/Handler/McpInitializeSessionHandler.php
Handles McpInitializeSessionCommand (on agent.command.bus), writes partial + final catalog via src/CodingAgent/Mcp/Catalog/SessionFileMcpToolCatalogStore.php → the session's mcp-tools.json.

4. Catalog → toolbox — src/CodingAgent/Mcp/Tool/:

• src/CodingAgent/Mcp/Tool/McpCatalogRegisteringToolSetResolver.php decorates CodingAgentToolSetResolver (wired in config/services.yaml). Every resolve() call first runs McpToolRegistrar::registerUsingCatalogFrom(), then builds the ActiveToolSet snapshot. It's idempotent — unchanged catalog fingerprints are a no-op.
• src/CodingAgent/Mcp/Tool/McpToolRegistrar.php registers each connected server's tool as a dynamic tool in ToolRegistryInterface, with an McpToolHandler from src/CodingAgent/Mcp/Tool/McpToolHandlerFactory.php. Stale MCP-owned tools are removed on catalog change; collisions with permanent/unrelated tools are skipped with a warning.

Execution side

src/CodingAgent/Tool/RegistryBackedToolbox.php enumerates registry->activeToolDefinitions() for LLM visibility (getTools() → Symfony AI Tool metadata) and executes calls through the native Symfony AI Toolbox. MCP-backed calls route via src/CodingAgent/Mcp/Messenger/McpExecuteToolCallRoutingMiddleware.php to the dedicated mcp transport, where src/CodingAgent/Mcp/Tool/McpToolInvoker.php runs them on the pooled connection.

User-visible contract: docs/mcp.md

[chr-hertel]

Hey there @ineersa, i opened #2497 few days ago - can you please cross check if the feature scope is basically the same or am i missing something? Cheers!

[ineersa]

Hey there @ineersa, i opened #2497 few days ago - can you please cross check if the feature scope is basically the same or am i missing something? Cheers!

@chr-hertel
Looks great!
Expecially AbstractToolbox and ToolsetInterface, that would help a lot with custom toolboxes.
McpToolbox is live proof of that architecture =)

Added few small comments on PR.

[chr-hertel]

Thanks @ineersa - that's really helpful!

[tacman]

#2497 (merged) covers the core of this issue: MCP server tools reach the agent toolbox from config, with no hand-written #[AsTool] wrappers. I tried it on main against the local-app case (the same #[McpTool] services for external agents and for the app's own chat) and left feedback there: #2497 (comment). That covers an in-process toolset prototype, and three rough edges: local tools leak into an mcp_server-only list, server error messages are masked from the model, and a server that fails to list is silent. I'd suggest keeping this issue open until the local/in-process question is settled.

[wachterjohannes]

Agreed, leaving it open until #2540 settles the in-process question.

[chr-hertel]

Settled :)