feat(agentenv-mcp): Environment with MCP-configurable action space

[supmo668]

Overview

An AgentGym environment where actions are determined by MCP servers you configure.

Instead of hardcoded tools, this environment's action space adapts based on which MCP servers you connect to. Configure servers via JSON, and the environment automatically uses their tools.

Concept

You configure → MCP Servers (via JSON) → Tools become actions → AgentGym Environment

Example: Configure a directional server → Environment gains up, down, left, right actions

What's Included

Environment

• Action space from configured MCP servers
• SSE-based server communication (fastmcp)
• Dual mode: internal tools OR external servers

Configuration

• mcp.example.json - Define which servers to use
• Automatic action space discovery
• Multi-server support

Example Server

• Directional navigation (up/down/left/right)
• FastMCP implementation
• Launcher for multiple servers

Utilities

• Trajectory collection
• Analysis tools
• Visualization

Usage

1. Configure Servers

{
  "mcpServers": {
    "directional": {
      "command": "uv",
      "args": ["run", "python", "-m", "examples.directional.server"],
      "url": "http://localhost:8001"
    }
  }
}

2. Run Environment

Internal Mode (built-in tools)

uv run python -m agentenv_mcp.launch --example directional

External Mode (configured servers)

# Start server
python examples/start_servers.py directional

# Use environment
mcp-client --config agentenv_mcp/mcp.json

3. Environment Adapts

The environment's action_space automatically reflects tools from your configured servers.

Extending

Add your own MCP server:

1. Create examples/myserver/server.py with FastMCP
2. Register in mcp.json
3. Environment automatically uses your tools

No environment code changes needed—just configuration.

Key Files

• mcp_environment.py - Environment that reads from MCP servers
• mcp_client.py - Connects to servers via SSE
• mcp.example.json - Server configuration template
• examples/directional/ - Example server implementation

Verified

• 28 files: core + examples + documentation
• 100% backward compatible (internal mode unchanged)
• Tested: 3 episodes, full trajectory collection
• Code: formatted with ruff, all checks pass

---

See README.md for architecture • MIGRATION.md for integration details

[SixPlusSeven67]

Thanks a lot for the contribution. This is a very interesting prototype and definitely a useful reference for how FastMCP-style servers can be plugged into an AgentGym-like environment.

From what I understand, this PR mainly provides a framework and an example (e.g., the directional server with up/down/left/right actions) demonstrating how to adapt an MCP server into an AgentEnvironment. This is great as a conceptual demo, but I’m not sure whether it makes sense to merge directly into the main codebase, since it doesn’t currently integrate with any of the existing AgentGym environments (WebShop, BabyAI, TextCraft, etc.).

I’d really love to discuss the broader direction with you: do you have any ideas or plans for adapting the existing AgentEnvironments to your MCP server design?

I think shaping a consistent mapping from real environments to MCP tools could be extremely valuable, and I’m happy to explore that direction.

[supmo668]

Thanks for the input @SixPlusSeven67

I agree with your assessment. The current PR is a foundational prototype, but its real value will only be realized when it connects to the actual benchmarks hosted in AgentGym.

I am very interested in contributing to the direction you mentioned: adapting existing AgentEnvironments to the MCP server design.

Before I start implementing, I would value your opinion on the best architectural approach:

1. Generic Adapter: Should I attempt to build a GymToMCP wrapper that takes a standard AgentEnv and automatically exposes its action space as MCP tools?
2. Specific Implementation: Or would you prefer I focus on crafting a high-quality MCP Server for one specific environment first to prove the pattern? more aligned with this direction for bridging the abstraction gap between an action and tool-use
   If you prefer the specific approach, which environment (WebShop, TextCraft, BabyAI, etc.) do you think would be the best "pilot" candidate?

My goal is to help standardize the mapping from environments to tools for better portability, happy to align with whichever path fits the AgentGym roadmap best.