[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.

---

Refined Requirements

Based on repository analysis and community feedback, here's the refined scope:

Current State ✅

Multiple MCP servers and lifecycle management are already supported programmatically:

from strands import Agent
from strands.tools.mcp import MCPClient
from mcp.client.stdio import stdio_client, StdioServerParameters

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])

Gap ❌

Configuration file support for MCP servers - Users must currently define MCP clients programmatically. The experimental agent_config.py does not support MCP configuration.

---

Proposed Solution

Extend src/strands/experimental/agent_config.py to support MCP server configuration.

Configuration Format

Use JSON format (matching existing agent_config.py pattern):

{
  "name": "my_agent",
  "model": "us.anthropic.claude-3-5-sonnet-20241022-v2:0",
  "prompt": "You are a helpful assistant.",
  "tools": ["strands_tools.file_read"],
  "mcp_servers": [
    {
      "name": "aws_docs",
      "transport": "stdio",
      "command": "uvx",
      "args": ["awslabs.aws-documentation-mcp-server@latest"],
      "env": {},
      "prefix": "aws",
      "startup_timeout": 30,
      "tool_filter": {
        "allowed": ["search_.*", "get_docs"],
        "rejected": ["dangerous_tool"]
      }
    },
    {
      "name": "local_agent",
      "transport": "sse",
      "url": "http://localhost:8000/sse",
      "headers": {
        "Authorization": "Bearer ${MCP_AUTH_TOKEN}"
      },
      "timeout": 300,
      "prefix": "local"
    },
    {
      "name": "remote_service",
      "transport": "streamable-http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "X-API-Key": "${API_KEY}"
      }
    }
  ]
}

Transport Types

Transport	Required Fields	Optional Fields
stdio	command	args, env, cwd
sse	url	headers, timeout
streamable-http	url	headers, timeout

Strands-Specific Options (per server)

Option	Type	Description
name	string	Server identifier (required)
prefix	string	Prefix for tool names to avoid collisions
startup_timeout	int	Timeout for server initialization (default: 30)
tool_filter	object	Filter which tools to load (allowed/rejected patterns)

Features

1. Environment Variable Interpolation: Support ${VAR_NAME} syntax for secrets
2. Per-Server Headers: Allow different auth headers per MCP server
3. Tool Filtering: Per-server tool allow/reject lists (supports regex patterns)
4. Graceful Failures: Opt-in behavior to continue if some servers fail (see [FEATURE] Graceful MCP server startup failures - fail open #1481)

---

Dependencies

• Blocking: [FEATURE] Graceful MCP server startup failures - fail open #1481 - Graceful MCP server startup failures (fail open)
  • When loading multiple MCP servers from config, a single failure shouldn't break the entire agent

---

Use Cases

1. Config-driven agents: Load agent configuration including MCP servers from a single JSON file
2. Multi-server setups: Seamlessly interact with multiple MCP servers (AWS docs, local tools, remote services)
3. Environment-specific configs: Different MCP servers per environment using env var interpolation
4. Selective tool loading: Filter which tools to expose from each server

---

Implementation Approach

1. Extend AGENT_CONFIG_SCHEMA in agent_config.py to include mcp_servers property
2. Create helper to parse MCP config and instantiate MCPClient instances
3. Support stdio transport first, then add SSE and streamable-http
4. Add validation for transport-specific required fields
5. Implement environment variable interpolation for sensitive values

---

Acceptance Criteria

• JSON configuration file can define multiple MCP servers
• All three transport types supported (stdio, sse, streamable-http)
• Per-server options work: prefix, startup_timeout, tool_filter, headers
• Environment variable interpolation works for secrets
• Integration with [FEATURE] Graceful MCP server startup failures - fail open #1481 for graceful failure handling
• Documentation with examples
• Unit and integration tests

---

References

• PR feat(mcp): add a feature to start MCP server from config file #623 (closed, not merged) - Previous implementation attempt
• MCP Transport Types
• Anthropic MCP Server Config Examples

[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.

[mkmeral]

#623

[mkmeral]

Refinement notes:

• We need to agree on a format (or maybe support multiple? :) )
• We need to agree Strands specific options
• We should probably fix this beforehand [FEATURE] Graceful MCP server startup failures - fail open #1481