[earakely-scale]

What and why

vLLM 0.30 and later require mcp>=2. agent-env and its protocol package pinned mcp<2, so a trainer with agent-env installed was held to vLLM 0.29. TRL 1.16 allows vLLM 0.22–0.31, and its minimum keeps rising. On the current release, agentenv-framework with trl[vllm] and vllm>=0.30 has no solution; on this branch it resolves on Linux to TRL 1.16, vLLM 0.31 and mcp 2.3.0.

Pins

• agent-env and the protocol package take mcp>=1.25,<3, and the protocol's fastmcp extra <5.
• The gateway's image keeps its own mcp<2, since it serves on mcp 1's FastMCP. That code is container-only and unchanged.
• uv.lock stays on mcp 1: the openenv extra's fastmcp 3 needs it, until OpenEnv moves to FastMCP 4.
• agent-env no longer declares mcp itself. Nothing outside the gateway imports it directly any more, so test_runtime_dependencies_are_imported flagged it; it arrives with agentenv-framework-protocol[computer].

agentenv_protocol.mcp_compat holds what differs between the versions:

• server(name, **settings) builds mcp 1's FastMCP, or mcp 2's MCPServer holding the serving settings (path, host, port, transport security) that mcp 2 takes at streamable_http_app() and run() instead.
• client_session(url, headers=, timeout=) opens an initialized ClientSession. mcp 2's client takes an httpx2 client and yields two streams, where mcp 1's took httpx and yielded three.
• low_level_server(...) registers a low-level server's handlers: by decorator on mcp 1, by constructor on mcp 2.
• field(result, "isError") reads an mcp type's field. mcp 2 spells the attributes in snake case only.
• with_crash_text(error) restores a tool crash's text on mcp 2. mcp 2 reports "Error executing tool x" alone and keeps the exception's text on the server; mcp 1 sends "Error executing tool x: ". An env's errors now read the same on either version, and the crash is still logged on the server.

Where it's used

• Protocol:
  • create_fastmcp_app and serve();
  • the per-role tools/list filter, which on mcp 2 runs in MCPServer's middleware, since mcp 2 has no request context outside a handler;
  • the peer-agents server;
  • the computer conformance probe and its client.
• agent-env:
  • the env provider's tool listing;
  • the legacy reset;
  • the two MCP validators;
  • the two example verifiers. env_outcome_verifier runs a bundle's verify.py in agent-env's process, so verifiers see the trainer's mcp. The README tells verifier authors to use client_session and field.

Tests

• The protocol tests run on both versions. 243 of them were module-skipped on mcp 2 by importorskip("mcp.server.fastmcp").
• tests/mcp_versions.py (and tst/util/mcp_versions.py) give an in-memory or HTTP session whose results read by mcp 1's attribute names on either version.
• Two tests that read the session id from mcp 1's third stream now read it from the mcp-session-id response header, or speak JSON-RPC directly.

CI: unit-mcp2 runs the unit tier on mcp 2.3 and fastmcp 4. It installs every extra but openenv, plus the dev test tools read from pyproject.toml.

• Two passes. Importing fastmcp 4 adds mcp 1's camel-case attributes to mcp's types process-wide (fastmcp/_compat.py). In one process that hides exactly the reads this job exists to catch: run alone, 17 conformance tests failed that passed in the full suite. So the tests that import fastmcp run in a second pass.
• Left out of both passes:
  • the gateway's tests, and the ones that build a card with the real gateway server, which serves on mcp 1 inside its image;
  • the openenv tests;
  • the two packaging tests that read every extra's installed metadata, openenv's included. The unit job runs them.

Not in this PR: porting the gateway itself to MCPServer. Its container keeps mcp 1, and trainers don't need it.

How it was tested

• mcp 1: pytest tst/unit packages/agentenv-protocol/tests -n 10: 10,949 passed, 1 failed.
  • The failure is submit_runs_test::test_a_first_ctrl_c_lets_the_runner_finish_stopping, a Ctrl-C timing test that passes 3 of 3 alone and doesn't touch mcp. The run before passed all 10,950.
• mcp 2.3 + fastmcp 4.1.4, both unit-mcp2 passes exactly as the workflow runs them: 9,861 passed, then 56 passed.
• mcp 2.3 without fastmcp, where nothing can lend camel-case attributes: the protocol tests and the touched agent-env tests pass (871), with only the fastmcp-only modules skipped.
• Local Docker on mcp 2: tst/integration/env/envs/server_env_local_test.py, which drives the Episode API, passes 5 of 5.
• Resolution: uv pip compile of agent-env with trl[vllm] and vllm>=0.30 for x86_64 Linux and Python 3.12 resolves to TRL 1.16.0, vLLM 0.31.0 and mcp 2.3.0. On 0.9.1367 it has no solution.
• ruff check and uv lock --check pass.

🤖 Generated with Claude Code

Confidence Score: 4/5

Fix the duplicate settings arguments before merging so existing SDK callers can still build their environment apps.

Findings

1.  Server settings stop startup ▶

Fix with agent prompt

### Issue 1
packages/agentenv-protocol/src/agentenv_protocol/agent_env_environment.py:467-468
`create_fastmcp_app()` now raises `TypeError` when callers supply `host` or `port` through `fastmcp_kwargs`, because those keywords are also passed explicitly. Previously, it accepted those settings and then replaced them with `MCP_HOST` and `MCP_PORT`.

On mcp 2, supplying `transport_security` also fails because `deployed_server()` passes it twice. Merge the settings before calling these helpers so existing arguments do not stop the app from starting.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Adds shared helpers so the protocol SDK and framework clients can run on mcp 1 or mcp 2.

• Agent-env environments can serve tools on mcp 1 or mcp 2.
• Agent-env MCP clients and result readers work with either mcp version.
• The project tests mcp 2 separately while keeping its main lock on mcp 1.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  App[Environment app] --> Compat[mcp_compat]
  Clients[Framework clients] --> Compat
  Compat --> MCP1[mcp 1]
  Compat --> MCP2[mcp 2]
  Gateway[Gateway image] --> MCP1

Loading

_{Reviews (3) · Last reviewed commit: "ci(mcp): find the unit-mcp2 job's left-o..." · Reviewed by Greptile}

[greptile-apps]

Server settings stop startup

create_fastmcp_app() now raises TypeError when callers supply host or port through fastmcp_kwargs, because those keywords are also passed explicitly. Previously, it accepted those settings and then replaced them with MCP_HOST and MCP_PORT.

On mcp 2, supplying transport_security also fails because deployed_server() passes it twice. Merge the settings before calling these helpers so existing arguments do not stop the app from starting.

Prompt To Fix With AI

This is a comment left during a code review.
Path: packages/agentenv-protocol/src/agentenv_protocol/agent_env_environment.py
Line: 467-468

Comment:
**Server settings stop startup**

`create_fastmcp_app()` now raises `TypeError` when callers supply `host` or `port` through `fastmcp_kwargs`, because those keywords are also passed explicitly. Previously, it accepted those settings and then replaced them with `MCP_HOST` and `MCP_PORT`.

On mcp 2, supplying `transport_security` also fails because `deployed_server()` passes it twice. Merge the settings before calling these helpers so existing arguments do not stop the app from starting.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[earakely-scale]

Parked as a draft until OpenEnv ships FastMCP 4 (openenv/OpenEnv#1304).

The TRL route through OpenEnv needs OpenEnv in the trainer, and OpenEnv 0.10 requires mcp 1. So this PR doesn't unblock vLLM 0.30+ for that route yet, and the first TRL runs can use vLLM 0.29. Merging now would mean carrying the compat layer and unit-mcp2 meanwhile, and our agent and env images would move to mcp 2 at their next build.

Once #1304 is released, we'll decide between this dual support and mcp 2 only, with the OpenEnv check done in the same change. The branch is kept: CI was green apart from integration-local-slow, which is also timing out on main.

🤖 Generated with Claude Code