[FEATURE] Support for multiple MCP servers (and loading from config file)

[jer96]

Problem Statement

I would like strands to support multiple MCP servers. One of the mechanisms to provide this may be loading from a config file.

As outlined in the parent issue #198 the DX for adding MCP tools to an agent can be improved, alongside these improvements it would be great to configure multiple MCP servers and have the lifecycle of client connections be managed automatically.

Proposed Solution

No response

Use Case

• Agents seamlessly interacting with multiple MCP servers
• Defining MCP servers via a config file and configuring agents accordingly

Alternatives Solutions

No response

Additional Context

No response

[Unshure]

/strands

[github-actions]

Repository Analysis & Clarifying Questions

Repository Analysis

I've analyzed the current implementation and found that multiple MCP servers and lifecycle management are already supported! The gap is specifically around configuration file support.

Current Capabilities ✅

Multiple MCP Server Support:

# This already works!
client1 = MCPClient(
    lambda: stdio_client(StdioServerParameters(command="uvx", args=["server1"])),
    prefix="server1"
)
client2 = MCPClient(
    lambda: stdio_client(StdioServerParameters(command="uvx", args=["server2"])),
    prefix="server2"
)

agent = Agent(tools=[client1, client2])

Automatic Lifecycle Management:

• MCPClient implements the ToolProvider interface
• Lifecycle is automatically managed when clients are passed to Agent
• Cleanup happens via consumer tracking (add_consumer/remove_consumer)
• See test: tests_integ/mcp/test_mcp_tool_provider.py::test_mcp_client_multiple_servers

What's Missing ❌

Configuration file support for MCP servers - Users currently must define MCP clients programmatically.

There is an experimental agent_config.py that supports loading agents from JSON, but it does not support MCP configuration.

---

Clarifying Questions

1. Configuration File Format & Location

Q1.1: What configuration file format should be used?

• JSON (matching existing agent_config.py)?
• YAML?
• TOML?
• Other format?

Q1.2: Where should MCP configuration be located?

• Integrated into the existing agent config structure?
• Separate MCP-specific config file?
• Support both approaches?

2. Configuration Schema

Q2.1: Should MCP configuration be part of the agent config, or separate?

Option A - Integrated Agent Config:

{
  "name": "my_agent",
  "model": "claude-3-5-sonnet-20241022",
  "mcp_servers": [
    {
      "name": "aws_docs",
      "transport": {
        "type": "stdio",
        "command": "uvx",
        "args": ["awslabs.aws-documentation-mcp-server@latest"]
      },
      "prefix": "aws",
      "startup_timeout": 30
    }
  ]
}

Option B - Separate MCP Config:

{
  "mcp_servers": [
    {
      "name": "aws_docs",
      "transport": { "type": "stdio", "command": "uvx", "args": [...] },
      "prefix": "aws"
    }
  ]
}

Which approach is preferred?

3. Transport Types

Q3.1: Which MCP transport types should be supported in configuration?

• stdio (command-line based servers)
• SSE (Server-Sent Events / HTTP streaming)
• WebSocket
• All of the above?

Q3.2: For each transport type, what parameters need to be configurable?

Example for stdio:

{
  "transport": {
    "type": "stdio",
    "command": "python",
    "args": ["server.py"],
    "env": {...}  // Should environment variables be configurable?
  }
}

4. MCP Client Configuration Options

Q4.1: Which MCPClient options should be configurable?

• ✅ prefix (for tool name prefixing)?
• ✅ startup_timeout?
• ✅ tool_filters (allowed/rejected patterns)?
• elicitation_callback (probably not, requires code)?

Q4.2: How should tool filters be specified in config?

Example:

{
  "tool_filters": {
    "allowed": ["echo", "list_.*"],  // String literals or regex patterns
    "rejected": ["dangerous_tool"]
  }
}

5. Environment Variables & Dynamic Configuration

Q5.1: Should the configuration support environment variable interpolation?

Example:

{
  "transport": {
    "type": "stdio",
    "command": "${MCP_SERVER_COMMAND}",
    "args": ["${MCP_SERVER_ARGS}"]
  }
}

Q5.2: Should paths in configuration support relative paths, and if so, relative to what?

6. Scope & Testing

Q6.1: Should this implementation:

• Extend the existing experimental agent_config.py?
• Create a new module for MCP configuration?
• Both?

Q6.2: Are there specific MCP servers you'd like to test with?

Q6.3: Should example configurations be provided in documentation?

7. Error Handling

Q7.1: How should configuration validation errors be reported?

• Fail fast during config loading?
• Detailed validation messages?

Q7.2: How should MCP server startup failures be handled?

• Fail agent initialization?
• Skip the failing server and continue with others?
• Configurable behavior?

---

Recommendation

Based on the repository structure, I recommend:

1. Extend src/strands/experimental/agent_config.py to support MCP configuration
2. Start with stdio transport as it's most commonly used
3. Use JSON format to match existing config pattern
4. Integrate into agent config for unified configuration
5. Support basic configuration options: prefix, startup_timeout, tool_filters

This keeps the implementation focused and aligned with existing patterns.