feat: Add MCP client tool #49

mkmeral · 2025-05-26T14:21:50Z

Description

This PR introduces a new MCP (Model Context Protocol) client tool for Strands Agents that provides a high-level interface for connecting to any MCP server with simplified configuration and enhanced functionality.

Key Features:

Multiple Transport Support: Connect to MCP servers via stdio (for local processes) or SSE (Server-Sent Events) for web-based servers
Simplified Configuration: Direct parameter passing without complex nested configurations
Connection Management: Thread-safe connection storage with support for multiple simultaneous connections
Tool Discovery: List available tools from connected MCP servers
Direct Tool Invocation: Call MCP tools directly or load them into the agent's tool registry
Environment Variable Support: Pass environment variables to stdio-based MCP servers
Comprehensive Error Handling: Detailed error messages and connection status tracking

Usage Examples:

# Connect to a custom MCP server
agent.tool.mcp_client(
    action="connect",
    connection_id="my_server",
    transport="stdio",
    command="python",
    args=["server.py"]
)

# List available tools
agent.tool.mcp_client(
    action="list_tools",
    connection_id="my_server"
)

# Call a tool directly
agent.tool.mcp_client(
    action="call_tool",
    connection_id="my_server",
    tool_name="calculate",
    x=10,
    y=20
)

# Load tools into agent's registry for direct access
agent.tool.mcp_client(
    action="load_tools",
    connection_id="my_server"
)

Related Issues

N/A

Documentation PR

N/A - Documentation is included in the README.md update

Type of Change

Bug fix
New Tool
Breaking change
Other (please describe):

Testing

The implementation includes comprehensive unit tests covering:

Connection management (stdio and SSE transports)
Tool listing and discovery
Direct tool invocation
Tool loading into agent registry
Error handling scenarios
Thread safety
Full workflow integration tests

Testing commands run:

hatch fmt --linter ✓
hatch fmt --formatter ✓
hatch test --all ✓

Manual Testing

**user:** use perplexity mcp from ~/.aws/amazonq/mcp.json and tell me what techno events are in amsterdam this weekend

**strands:** connected to Perplexity MCP server using `mcp_client(action="connect")` with stdio transport, reading config from ~/.aws/amazonq/mcp.json

**strands:** called `mcp_client(action="call_tool", tool_name="perplexity_ask")` to search for Amsterdam techno events, found 4 events including Amsterdam Sessions at Machinegebouw

**user:** load mcp's tools

**strands:** executed `mcp_client(action="load_tools")` to register MCP tools directly into agent, successfully loaded mcp_perplexity_perplexity_ask tool

**user:** using this tool, tell me what events there are this weekend at radion, lofi and thuishaven

**strands:** directly called loaded `mcp_perplexity_perplexity_ask()` tool without going through mcp_client, found Vault Sessions x BASSIANI event at Radion with full lineup details

Key achievements:

Connected to MCP server from JSON config file
Called MCP tools through the client interface
Loaded MCP tools into agent's native tool registry
Used loaded MCP tools directly like built-in tools
Seamless integration of external MCP services into Strands workflow

Checklist

I have read the CONTRIBUTING document
I have added tests that prove my fix is effective or my feature works
I have updated the documentation accordingly
I have added an appropriate example to the documentation to outline the feature
My changes generate no new warnings
Any dependent changes have been merged and published
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

mkmeral · 2025-05-27T08:21:11Z

Related strands-agents/agent-builder#4

src/strands_tools/mcp_client.py

- Add streamable_http transport option alongside stdio and sse - Support headers, timeout, sse_read_timeout, terminate_on_close, and auth parameters - Add comprehensive tests for streamable HTTP functionality - Update README with streamable HTTP example

README.md

src/strands_tools/mcp_client.py

cagataycali · 2025-06-01T01:51:51Z

src/strands_tools/mcp_client.py

+            elif isinstance(result, list):
+                # If it's already a list of content items, use it directly
+                content = result
+            elif isinstance(result, dict):


Can we make sure we support other types here like images?

src/strands_tools/mcp_client.py

…meout

cagataycali

Looks great! Approving and leaving a room to team to take a look!

dbschmigelski · 2025-06-18T13:28:24Z

README.md

@@ -52,6 +52,7 @@ Strands Agents Tools provides a powerful set of tools for your agents to use. It
 - ⏱️ **Task Scheduling** - Schedule and manage cron jobs
 - 🧠 **Advanced Reasoning** - Tools for complex thinking and reasoning capabilities
 - 🐝 **Swarm Intelligence** - Coordinate multiple AI agents for parallel problem solving with shared memory
+- 🔌 **MCP Client** - Connect to any Model Context Protocol server and access remote tools


nit: Can we edit this to callout that we are allowing an agent to autonomously perform this connection and dynamic loading. This was brought up on a client call and, as expected, this was called out as being potentially dangerous.

This tool is useful, I want to prevent customers from accidentally doing something like the following instead of using the MCPClient approach in the SDK

agent = Agent(tools=[mcp_client, use_browser]) agent.tool.mcp_client("connect") # Agent uses the browser, then connects and downloads tools from an attackers mcp_server.

This be be documentation, but I also have concerns with this tool being called mcp_client. I would bet that we will get customers asking us "should I use mcp_client tool or MCPClient" because of this.

dbschmigelski · 2025-06-18T13:32:15Z

src/strands_tools/mcp_client.py

+# Suppress warnings from MCP SDK about unknown notification types
+# This is particularly useful for test servers that send non-standard notifications
+# Users can override this by setting their own logging configuration
+logging.getLogger("mcp.shared.session").setLevel(logging.ERROR)


If I am using strands with mcp pinned at a particular version, how would I get a deprecation warning with this set to Error? Are we doing this elsewhere?

This forced suppression seems strange to me. Couldn't we just remove this and then if the user thinks it is noisy because they are using standard notifications override it themselves?

dbschmigelski · 2025-06-18T13:34:00Z

src/strands_tools/mcp_client.py

+        connection_id: str,
+        tool_name: str,
+        tool_spec: ToolSpec,
+        mcp_client: Any,  # Required: direct MCP client reference


dbschmigelski · 2025-06-18T13:34:59Z

src/strands_tools/mcp_client.py

+        tool_name: str,
+        tool_spec: ToolSpec,
+        mcp_client: Any,  # Required: direct MCP client reference
+        name_prefix: bool = True,


nit: name prefix as this param doesn't seem clear to me

dbschmigelski · 2025-06-18T13:35:16Z

src/strands_tools/mcp_client.py

+        super().__init__()
+        self.connection_id = connection_id
+        self.original_tool_name = tool_name
+        self.mcp_client = mcp_client  # Direct client reference


nit: "# Direct client reference" does this add anything?

dbschmigelski · 2025-06-18T13:37:12Z

src/strands_tools/mcp_client.py

+                return {"toolUseId": tool_use_id, "status": "error", "content": [{"text": result["error"]}]}
+
+            # Convert MCP result to Strands format
+            content = []


We have https://github.com/strands-agents/sdk-python/blob/main/src/strands/tools/mcp/mcp_client.py#L262, is it possible to expose that so we can reuse it here rather than reimplement?

dbschmigelski · 2025-06-18T13:42:11Z

src/strands_tools/mcp_client.py

+            _connections[connection_id].last_error = last_error
+
+
+class MCPToolWrapper(AgentTool):


I'm a bit confused by the pattern here, we have MCPToolWrapper but we also have mcp_client. And both can be loaded by an Agent class as MCPToolWrapper implements AgentTool and mcp_client is annotated with @tool

When should I use one and not the other? Should there just be one?

Edit: it looks like this may be a naming related confusion where this is an MCPTool that was generated by the MCPClient

Still, curious why we opted for the class based approach here but the annotation one below.

dbschmigelski · 2025-06-18T13:46:26Z

src/strands_tools/mcp_client.py

+    try:
+        # Use the stored client
+        result = config.mcp_client.call_tool_sync(
+            tool_use_id=f"mcp_{connection_id}_{tool_name}_{uuid.uuid4().hex[:8]}", name=tool_name, arguments=tool_args


is there a length limitation here, my fear is that our uniqueness strategy of using uuid is no impacted by using the [:8] this may impact customer traceability

dbschmigelski · 2025-06-18T13:48:50Z

src/strands_tools/mcp_client.py

+    agent: Optional[Any] = None,  # Agent instance passed by SDK
+) -> Dict[str, Any]:
+    """
+    MCP client tool for connecting to any MCP server with simplified configuration.


Similar to above I think we need some serious editing here and callouts of the risks involved with using this

dbschmigelski · 2025-06-18T13:49:25Z

tests/test_mcp_client.py

Can you add an integration test as well

feat: Add MCP client tool

f33c742

mkmeral requested a review from a team as a code owner May 26, 2025 14:21

mkmeral mentioned this pull request May 26, 2025

feat: Add MCP client strands-agents/agent-builder#18

Open

5 tasks

fix: mcp_client failing on empty tool args

be4e945

cagataycali reviewed May 28, 2025

View reviewed changes

src/strands_tools/mcp_client.py Outdated Show resolved Hide resolved

cagataycali reviewed May 28, 2025

View reviewed changes

src/strands_tools/mcp_client.py Show resolved Hide resolved

cagataycali reviewed May 28, 2025

View reviewed changes

src/strands_tools/mcp_client.py Show resolved Hide resolved

Unshure assigned cagataycali and awsarron May 29, 2025

Murat Kaan Meral added 2 commits May 31, 2025 00:23

Merge branch 'main' into mcp-client

04d9fe0

cagataycali reviewed May 31, 2025

View reviewed changes

README.md Outdated Show resolved Hide resolved

fix: readme MCP client signature update

3e1abdd

cagataycali reviewed Jun 1, 2025

View reviewed changes

src/strands_tools/mcp_client.py Outdated Show resolved Hide resolved

cagataycali reviewed Jun 1, 2025

View reviewed changes

src/strands_tools/mcp_client.py Outdated Show resolved Hide resolved

cagataycali reviewed Jun 1, 2025

View reviewed changes

src/strands_tools/mcp_client.py Outdated Show resolved Hide resolved

cagataycali reviewed Jun 1, 2025

View reviewed changes

src/strands_tools/mcp_client.py Outdated Show resolved Hide resolved

cagataycali reviewed Jun 1, 2025

View reviewed changes

src/strands_tools/mcp_client.py Outdated Show resolved Hide resolved

Murat Kaan Meral added 3 commits June 5, 2025 20:32

Improve content type handling and add environment variable for mcp ti…

20e55d0

…meout

Merge branch 'main' into mcp-client

90ca572

fix: run formatter

dfa6854

cagataycali approved these changes Jun 6, 2025

View reviewed changes

dbschmigelski self-requested a review June 11, 2025 16:04

Unshure assigned dbschmigelski and unassigned awsarron Jun 17, 2025

dbschmigelski requested changes Jun 18, 2025

View reviewed changes

		_connections[connection_id].last_error = last_error


		class MCPToolWrapper(AgentTool):

feat: Add MCP client tool #49

Are you sure you want to change the base?

feat: Add MCP client tool #49

Uh oh!

Conversation

mkmeral commented May 26, 2025

Description

Key Features:

Usage Examples:

Related Issues

Documentation PR

Type of Change

Testing

Manual Testing

Checklist

Uh oh!

mkmeral commented May 27, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

cagataycali left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!